Agent

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

POST
POST
POST
GET
GET
DELETE
POST
GET
POST
POST
GET
GET
DELETE
POST
← Previous pageNext page →

Create agent applications revisions bundle import

Bulk-merge a set of .md files into a draft revision.

Sets agent_md on the draft bundle if present. skills[] are store-backed and merge by id: an id already referenced by the draft publishes a new version of its store skill; an unreferenced id attaches the store skill of that name (publishing the payload's body to it), or creates it when no such skill exists — and each ref is (re-)pinned to the published version. Skills not mentioned are left alone, so the import is safe to retry. Draft-only; non-draft revisions return 409 untouched.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Request parameters

  • agent_md
    string
  • skills
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/bundle/import
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/bundle/import/\
	-d agent_md="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 409 The revision is frozen (ready/live/archived); clone a new draft and edit that instead.
RESPONSE
{
  "error": "string",
  "state": "draft",
  "detail": "string"
}

Create agent applications revisions clone from

Copy every file from source_revision_id into this revision.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Request parameters

  • source_revision_id
    string

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/clone_from
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/clone_from/\
	-d source_revision_id="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create agent applications revisions cron fire

Fire one cron job out-of-band — the same execution path the scheduler walks, but on demand. Authoring UX: the user iterates on a cron prompt by clicking 'Fire now' rather than waiting for the next scheduled firing. Without this, 'did my prompt do the right thing?' is unanswerable until the cron actually fires.

Idempotent via request_id: repeat clicks with the same id resolve to the same session id rather than firing N times.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Request parameters

  • cron_name
    string
  • request_id
    stringnull

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/cron/fire
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/cron/fire/\
	-d cron_name="string"

Example response

Status 200 Cron job was fired (or deduped to an existing session).
RESPONSE
{
  "ok": true,
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "fired_at": "string",
  "idempotency_key": "string",
  "request_id": "string"
}

List all agent revisions env keys

List the names of secrets currently set on this revision.

Returns names only — values stay server-side under EncryptedTextField. Use this to drive the "set / unset" badge next to a declared secret in the editor UI.

Required API key scopes

agents:read

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys/

Example response

Status 200
RESPONSE
{
  "keys": [
    "string"
  ]
}

Retrieve agent revisions env keys

GET / PUT / DELETE one secret by name on this revision.

  • GET → { key, is_set } (never returns the value).
  • PUT → upserts { value } into the env block.
  • DELETE → removes the key. No-op when it wasn't set.

Per-method scope: GET is treated as a write action so the single action name maps to one consistent scope; reading whether a secret is set is restricted to writers in any case.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string
  • key
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys/:key
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys/:key/

Example response

Status 200
RESPONSE
{
  "key": "string",
  "is_set": true
}

Delete agent revisions env keys

GET / PUT / DELETE one secret by name on this revision.

  • GET → { key, is_set } (never returns the value).
  • PUT → upserts { value } into the env block.
  • DELETE → removes the key. No-op when it wasn't set.

Per-method scope: GET is treated as a write action so the single action name maps to one consistent scope; reading whether a secret is set is restricted to writers in any case.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string
  • key
    string

Example request

DELETE /api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys/:key
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/env_keys/:key/

Example response

Status 204 No response body

Create agent applications revisions freeze

Freeze the bundle: draft → ready, stamps sha256 on the row.

Django is a thin proxy here: resolve template refs into the bundle, ask the janitor to seal it (the janitor returns the sha

  • the spec it derived from the typed resources), then stamp the row. No transaction.atomic() — the janitor's freeze is idempotent (on retry it re-reads the existing .frozen marker + re-derives spec), so a partial failure here is recoverable by re-calling freeze, not by transactional rollback. Holding an atomic block across the janitor HTTP call previously deadlocked the agent_revision row against the janitor's spec write — that's moved off the janitor side as part of the same fix.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/freeze
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/freeze/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve agent applications revisions manifest

List every file in this revision's bundle (path, size, sha256).

Required API key scopes

agents:read

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id/manifest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/manifest/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create agent applications revisions promote

ready → live. Sets the parent application's live_revision.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/promote
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/promote/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create agent applications revisions set env

Replace this revision's encrypted env block.

The body is { "env": { "<KEY>": "<value>", ... } }. The encrypted text is stored on AgentRevision.encrypted_env; the worker decrypts it at session start via the same Fernet schedule (see agent-shared/src/runtime/encryption.ts).

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string

Request parameters

  • env
    object

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/set_env
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/set_env/\
	-d env="object"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "application": "2b22d485-f04e-492b-b364-e14f8506726a",
  "parent_revision": "7dd0ec7f-ff92-4923-86ab-83534b1f3236",
  "state": "draft",
  "bundle_uri": "",
  "bundle_sha256": "string",
  "spec": null,
  "skill_refs": [
    {
      "from_template": "string",
      "alias": "string",
      "version": 1
    }
  ],
  "created_by_id": 0,
  "created_by": {
    "id": 0,
    "first_name": "string",
    "email": "user@example.com"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve agent applications revisions slack

Build a Slack app manifest for this revision's slack trigger.

Deterministic: the OAuth scopes and bot event subscriptions are derived from the slack trigger config (mention_only / auto_resume_threads / ack_reaction) and the agent's Slack tools, so the manifest already subscribes to exactly the events the config needs. 400 if the revision has no slack trigger.

Required API key scopes

agents:read

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id/slack_manifest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/slack_manifest/

Example response

Status 200
RESPONSE
{
  "revision_id": "f8f7f022-982b-4bef-ba7d-4bb808fdbe2a",
  "manifest": null,
  "notes": [
    "string"
  ],
  "events_url": "string",
  "interactivity_url": "string"
}

Retrieve agent applications revisions system

Return the fully-assembled system prompt for this revision.

Authoring tools call this to preview what the model will actually see at session start — the platform framework preamble plus the bundle's agent.md plus the skills index. Useful for debugging author-vs-framework precedence conflicts and verifying spec.framework_prompt.omit overrides took effect.

Required API key scopes

agents:read

Path parameters

  • application_id
    string
  • id
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id/system_prompt
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/system_prompt/

Example response

Status 200
RESPONSE
{
  "revision_id": "f8f7f022-982b-4bef-ba7d-4bb808fdbe2a",
  "framework_prompt_version": 0,
  "system_prompt": "string"
}

Delete agent applications revisions tools

Revisions of an agent. Created in draft, promoted through ready → live once the bundle has been uploaded + frozen.

URLs (nested under an application):

Model CRUD:
    GET   .../revisions/                       list
    POST  .../revisions/                       create draft
    GET   .../revisions/<id>/                  retrieve
    PATCH .../revisions/<id>/                  update spec (draft only)

Lifecycle:
    POST  .../revisions/<id>/promote/          ready → live
    POST  .../revisions/<id>/archive/          → archived
    POST  .../revisions/<id>/freeze/           draft → ready (stamps sha256)
    POST  .../revisions/<id>/clone_from/       copy bundle from another rev
    POST  .../revisions/new_draft/             create draft + clone_from atomically

Bundle authoring (proxied to the janitor):
    GET    .../revisions/<id>/manifest/        list paths + sha256
    GET    .../revisions/<id>/file/?path=…     read one file
    PUT    .../revisions/<id>/file/?path=…     write one file (draft)
    DELETE .../revisions/<id>/file/?path=…     delete one file (draft)
    GET    .../revisions/<id>/bundle/          bulk pull all files
    PUT    .../revisions/<id>/bundle/          bulk push (replace|merge)

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string
  • tool_id
    string

Example request

DELETE /api/projects/:project_id/agent_applications/:application_id/revisions/:id/tools/:tool_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/tools/:tool_id/

Example response

Status 204 No response body

Create agent applications revisions tools dry run

Execute one persisted custom tool in a single-shot sandbox.

Authoring loop's "test this tool" button. The tool's source must already be PUT (compiled.js is what runs); this just invokes it with the caller-supplied args and a stubbed ctx. No real secrets leave Django — mock_secrets is a {name → placeholder} map.

Required API key scopes

agents:write

Path parameters

  • application_id
    string
  • id
    string
  • tool_id
    string

Request parameters

  • args
  • mock_secrets
    object

Response


Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions/:id/tools/:tool_id/dry_run
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/tools/:tool_id/dry_run/\
	-d args=undefined

Example response

Status 200
RESPONSE
{
  "ok": true,
  "tool_id": "string",
  "result": null,
  "error": {
    "code": "string",
    "message": "string"
  },
  "duration_ms": 0
}
← Previous pageNext page →

Community questions