Agent

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

Endpoints

GET
DELETE
GET
GET
GET
GET
GET
GET
← Previous page

List all agent applications users

List this agent's end-users (the stable identities behind inbound principals) and each user's linked external connections. Connection metadata only — credential material is never returned.

Required API key scopes

agents:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/:id/users
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/:id/users/

Example response

Status 200
RESPONSE
{
  "count": 0,
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "principal_kind": "string",
      "principal_id": "string",
      "metadata": null,
      "created_at": "2019-08-24T14:15:22Z",
      "connections": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "provider": "string",
          "scopes": [
            "string"
          ],
          "state": "string",
          "subject": "string",
          "access_expires_at": "2019-08-24T14:15:22Z",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "revoked_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

Delete agent applications users connection

Revoke one of an end-user's linked connections. The credential is marked revoked (kept for audit), so the agent can no longer act as that user on the provider.

Required API key scopes

agents:write

Path parameters

  • agent_user_id
    string
  • id
    string
  • provider
    string

Example request

DELETE /api/projects/:project_id/agent_applications/:id/users/:agent_user_id/connections/:provider
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/:id/users/:agent_user_id/connections/:provider/

Example response

Status 204 No response body

Retrieve agent applications

Served-model catalog — each model's id, provider, context window, and USD-per-million-token pricing — plus the curated auto-level → model map. Project-agnostic; sourced from the AI gateway catalog. Powers the config UI model browser and the agent builder's model-choosing skill.

Required API key scopes

agents:read

Response


Example request

GET /api/projects/:project_id/agent_applications/models
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/models/

Example response

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

Retrieve agent applications spec

The canonical JSON Schema for an agent spec — every field, type, enum, default, and the discriminated unions for models / triggers[] / tools[], each with an inline description. Emitted from the same source the runner validates against (fields with a default are optional on write), so read it BEFORE composing a spec for create / revisions-spec-update instead of guessing the shape. Pass section to fetch just one part.

Required API key scopes

agents:read

Query parameters

  • section
    string

Response


Example request

GET /api/projects/:project_id/agent_applications/spec_schema
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/spec_schema/

Example response

Status 200
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 fleet approvals

Approval-gated tool requests across every agent in this team. Team-admin only.

Required API key scopes

agents:read

Query parameters

  • agent_id
    string
  • limit
    integer
  • offset
    integer
  • state
    string

Example request

GET /api/projects/:project_id/agent_fleet/approvals
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_fleet/approvals/

Example response

Status 200 No response body

Retrieve agent fleet live

Live (non-terminal) sessions across every agent owned by this team, newest activity first.

Required API key scopes

agents:read

Query parameters

  • limit
    integer

Response


Example request

GET /api/projects/:project_id/agent_fleet/live_sessions
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_fleet/live_sessions/

Example response

Status 200
RESPONSE
{
  "results": [
    {
      "usage_total": {
        "tokens_in": 0,
        "tokens_out": 0,
        "cache_read": 0,
        "cache_write": 0,
        "cost_input": 0.1,
        "cost_output": 0.1,
        "cost_cache_read": 0.1,
        "cost_cache_write": 0.1,
        "cost_total": 0.1
      },
      "principal": {
        "kind": "anonymous",
        "id": "string",
        "team_id": 0
      },
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "application_id": "48ac72d0-a829-4896-a067-dcb1c2b0f30c",
      "revision_id": "f8f7f022-982b-4bef-ba7d-4bb808fdbe2a",
      "team_id": 0,
      "state": "queued",
      "external_key": "string",
      "trigger_metadata": {},
      "turns": 0,
      "preview": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve agent fleet

Roll-up stats across every agent owned by this team.

Required API key scopes

agents:read

Query parameters

  • since
    string

Response


Example request

GET /api/projects/:project_id/agent_fleet/stats
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_fleet/stats/

Example response

Status 200
RESPONSE
{
  "liveCount": 0,
  "sessionsInWindowCount": 0,
  "spendInWindowUsd": 0.1,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "failedInWindowCount": 0,
  "pendingApprovalsCount": 0
}

List all agent native tools

Read-only catalog of every @posthog/* native tool the runner knows.

Required API key scopes

agents:read

Example request

GET /api/projects/:project_id/agent_native_tools
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_native_tools/

Example response

Status 200
RESPONSE
{
  "tools": [
    {
      "id": "string",
      "schema": {}
    }
  ]
}
← Previous page

Community questions