Agent API Reference

Agent

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

Endpoints

`GET`
`POST`
`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`GET`
`GET`
`GET`
`GET`
`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`POST`
`GET`

List all agent applications

Agent applications — the deployable unit of the platform.

URLs: GET /api/projects/<team>/agent_applications/ list POST /api/projects/<team>/agent_applications/ create GET /api/projects/<team>/agent_applications/<id|slug>/ retrieve PATCH /api/projects/<team>/agent_applications/<id|slug>/ update DELETE /api/projects/<team>/agent_applications/<id|slug>/ archive POST /api/projects/<team>/agent_applications/<id|slug>/set_env/ bulk replace env GET /api/projects/<team>/agent_applications/<id|slug>/env_keys/ list set keys GET /api/projects/<team>/agent_applications/<id|slug>/env_keys/<KEY>/ is one key set? PUT /api/projects/<team>/agent_applications/<id|slug>/env_keys/<KEY>/ set one key DELETE /api/projects/<team>/agent_applications/<id|slug>/env_keys/<KEY>/ clear one key

Required API key scopes

agents:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/agent_applications
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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "team_id": 0,
      "name": "string",
      "slug": "string",
      "description": "string",
      "live_revision": "067b8498-180d-45ba-92a8-76a49fa0e492",
      "archived": true,
      "archived_at": "2019-08-24T14:15:22Z",
      "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",
      "slack_events_url": "http://example.com",
      "slack_interactivity_url": "http://example.com",
      "ingress_base_url": "http://example.com"
    }
  ]
}

Create agent applications

Agent applications — the deployable unit of the platform.

Required API key scopes

agents:write

Request parameters

name
string
slug
string
description
string
archived
boolean

Response

Example request

POST /api/projects/:project_id/agent_applications
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/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "name": "string",
  "slug": "string",
  "description": "string",
  "live_revision": "067b8498-180d-45ba-92a8-76a49fa0e492",
  "archived": true,
  "archived_at": "2019-08-24T14:15:22Z",
  "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",
  "slack_events_url": "http://example.com",
  "slack_interactivity_url": "http://example.com",
  "ingress_base_url": "http://example.com"
}

List all agent memory list

List memory file headers under the agent's prefix. Headers only — no bodies.

Required API key scopes

agents:read

Path parameters

application_id
string

Query parameters

prefix
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/files
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/memory/files/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/files/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 0,
  "entries": [
    {
      "path": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

Create agent memory create

Create a memory file. Fails if the path already exists — use the update endpoint to overwrite.

Required API key scopes

agents:write

Path parameters

application_id
string

Request parameters

path
string
description
string
content
string
tags
array

Response

Example request

POST /api/projects/:project_id/agent_applications/:application_id/memory/files
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/memory/files/\
	-d path="string",\
	-d description="string",\
	-d content="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/files/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string",
		"description": "string",
		"content": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "content": "string"
}

Retrieve agent memory get

Read one memory file in full (frontmatter + markdown body).

Required API key scopes

agents:read

Path parameters

application_id
string

Query parameters

path
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/files/by_path
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/memory/files/by_path/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/files/by_path/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "content": "string"
}

Update agent memory update

Update a memory file. Any field omitted is preserved from the existing file.

Required API key scopes

agents:write

Path parameters

application_id
string

Query parameters

path
string

Request parameters

description
string
content
string
tags
array

Response

Example request

PATCH /api/projects/:project_id/agent_applications/:application_id/memory/files/by_path
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/memory/files/by_path/\
	-d description="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/files/by_path/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"description": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "content": "string"
}

Delete agent memory delete

Hard-delete a memory file. Activity log captures the action against the agent.

Required API key scopes

agents:write

Path parameters

application_id
string

Query parameters

path
string

Example request

DELETE /api/projects/:project_id/agent_applications/:application_id/memory/files/by_path
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/memory/files/by_path/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/files/by_path/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Retrieve agent memory

BM25 search across the agent's memory files. Ranks by description+tags+path+body with field weighting.

Required API key scopes

agents:read

Path parameters

application_id
string

Query parameters

limit
integer
prefix
string
q
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/search
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/memory/search/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/search/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "cue": "string",
  "count": 0,
  "results": [
    {
      "path": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "score": 0.1,
      "snippet": "string"
    }
  ]
}

List all agent memory list

List the agent's tabular-reference tables (the @posthog/table-* JSONL tables): name + byte size.

Required API key scopes

agents:read

Path parameters

application_id
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/tables
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/memory/tables/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/tables/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 0,
  "tables": [
    {
      "name": "string",
      "size": 0
    }
  ]
}

Retrieve agent memory read

Read rows from one tabular-reference table (capped via ?limit).

Required API key scopes

agents:read

Path parameters

application_id
string
name
string

Query parameters

limit
integer

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/tables/:name
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/memory/tables/:name/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/tables/{name}/".format(
        project_id=project_id,
		application_id="<the application id>",,
		name="<the name>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "name": "string",
  "total": 0,
  "returned": 0,
  "limit": 0,
  "rows": [
    {}
  ]
}

Retrieve agent memory

Pre-aggregated folder tree of memory files. Saves the frontend re-derivation work.

Required API key scopes

agents:read

Path parameters

application_id
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/memory/tree
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/memory/tree/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/memory/tree/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "root": {}
}

List all agent applications revisions

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:read

Path parameters

application_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions
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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "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

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

Request parameters

parent_revision
stringnull
bundle_uri
string
Default:
spec

Response

Example request

POST /api/projects/:project_id/agent_applications/:application_id/revisions
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/\
	-d application="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/".format(
        project_id=project_id,
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"application": "string"
	}
).json()

Example response

Status 201

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

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:read

Path parameters

application_id
string
id
string

Response

Example request

GET /api/projects/:project_id/agent_applications/:application_id/revisions/:id
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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/{agent_application_id}/".format(
        project_id=project_id,
		agent_application_id="<the agent application id>",
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
}

Update agent applications revisions

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

Request parameters

parent_revision
stringnull
bundle_uri
string
Default:
spec

Response

Example request

PATCH /api/projects/:project_id/agent_applications/:application_id/revisions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/agent_applications/:application_id/revisions/:id/\
	-d application="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/{agent_application_id}/".format(
        project_id=project_id,
		agent_application_id="<the agent application id>",
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"application": "string"
	}
).json()

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"
}

Delete agent applications revisions

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)

Path parameters

application_id
string
id
string

Example request

DELETE /api/projects/:project_id/agent_applications/:application_id/revisions/: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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/{agent_application_id}/".format(
        project_id=project_id,
		agent_application_id="<the agent application id>",
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Create agent applications revisions archive

Mark a revision archived. If it was the live one, clear the application's live_revision pointer (the app effectively has no deployable version until another revision is promoted).

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/archive
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/archive/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/{agent_application_id}/archive/".format(
        project_id=project_id,
		agent_application_id="<the agent application id>",
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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 bundle

Read the full typed bundle: { agent_md, skills, tools, spec }.

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/bundle
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/bundle/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/agent_applications/{application_id}/revisions/{agent_application_id}/bundle/".format(
        project_id=project_id,
		agent_application_id="<the agent application id>",
		application_id="<the application id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
}