AI Agents API

Create, deploy, and secure managed AI agents: the container, its source revisions, and the invoke token.

Manage AI agents over the API. See the AI Agents guide for the concepts, the portal flow, and how to call an agent's public /invoke endpoint with its bearer token.

All endpoints use your portal Bearer JWT. The /invoke endpoint itself lives on the agent's own public hostname and is authenticated by the agent's invoke token, not by these credentials.

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Query Parameters

limit?integer

offset?integer

Response Body

`application/json`

curl -X GET "https://example.com/v1/agents"

{
  "agents": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "project_name": "string",
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "name": "my-support-bot",
      "display_name": "My Support Bot",
      "template": "langchain",
      "provider": "alawadi",
      "model": "string",
      "status": "running",
      "endpoint": "https://my-support-bot-a1b2c3.alawadi.cloud/invoke",
      "revision": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "public": true,
      "invoke_token_prefix": "ak-live-a1b2c3"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents"

{
  "agents": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
      "project_name": "string",
      "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
      "name": "my-support-bot",
      "display_name": "My Support Bot",
      "template": "langchain",
      "provider": "alawadi",
      "model": "string",
      "status": "running",
      "endpoint": "https://my-support-bot-a1b2c3.alawadi.cloud/invoke",
      "revision": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "public": true,
      "invoke_token_prefix": "ak-live-a1b2c3"
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

display_name?string

template?string

provider?string

model?string

Optional per-provider model override.

public?boolean

Serve /invoke without the bearer token (owner opt-out).

resources?

Reserved compute and storage for the service.

openai_api_key?string

BYOK credential, stored only in the per-agent Secret. Required for provider=openai.

openrouter_api_key?string

gemini_api_key?string

anthropic_api_key?string

vertex_sa_json?string

vertex_project?string

vertex_location?string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents" \  -H "Content-Type: application/json" \  -d '{    "name": "my-support-bot"  }'

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "project_name": "string",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "name": "my-support-bot",
  "display_name": "My Support Bot",
  "template": "langchain",
  "provider": "alawadi",
  "model": "string",
  "status": "running",
  "endpoint": "https://my-support-bot-a1b2c3.alawadi.cloud/invoke",
  "revision": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "public": true,
  "invoke_token_prefix": "ak-live-a1b2c3",
  "key": "string",
  "invoke_token": "string"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "project_name": "string",
  "container_id": "aab18899-d71b-4b1d-a9c0-6f480c2125fa",
  "name": "my-support-bot",
  "display_name": "My Support Bot",
  "template": "langchain",
  "provider": "alawadi",
  "model": "string",
  "status": "running",
  "endpoint": "https://my-support-bot-a1b2c3.alawadi.cloud/invoke",
  "revision": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "public": true,
  "invoke_token_prefix": "ak-live-a1b2c3"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08"

Empty

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/source"

{
  "revision": 0,
  "entrypoint": "handler.py",
  "files": {
    "property1": "string",
    "property2": "string"
  }
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

files*

entrypoint?string

message?string

Optional deploy note.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/source" \  -H "Content-Type: application/json" \  -d '{    "files": {      "property1": "string",      "property2": "string"    }  }'

{
  "revision": 0,
  "rolled_out": true
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoke-token/rotate"

{
  "invoke_token": "string",
  "invoke_token_prefix": "string",
  "public": true,
  "rolled_out": true
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Empty

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/revisions"

{
  "current_revision": 0,
  "revisions": [
    {
      "revision": 0,
      "entrypoint": "string",
      "message": "string",
      "created_by": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "current": true
    }
  ]
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Path Parameters

projectId*string

agentId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

revision*integer

The existing revision number to roll back to.

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/rollback" \  -H "Content-Type: application/json" \  -d '{    "revision": 0  }'

{
  "revision": 0,
  "rolled_back_to": 0,
  "rolled_out": true
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

Authorization

bearerAuth

AuthorizationBearer <token>

Bearer JWT obtained after Google sign-in in the portal.

In: header

Query Parameters

from?string

Start of window, inclusive (YYYY-MM-DD or RFC 3339). Defaults to 30 days ago.

to?string

End of window (YYYY-MM-DD or RFC 3339; date-only is inclusive). Defaults to today.

format?string

Response format. csv requires a single kind.

kind?string

Comma-separated subset of usage, keys, agents (default: all three). REQUIRED and single-valued when format=csv (one table per file).

Response Body

`application/json`

curl -X GET "https://example.com/v1/ai/audit"

{
  "from": "2019-08-24T14:15:22Z",
  "to": "2019-08-24T14:15:22Z",
  "truncated": true,
  "usage": [
    {
      "id": 0,
      "ts": "2019-08-24T14:15:22Z",
      "model": "string",
      "key_prefix": "sk-alwd-a1b2",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "cost_uusd": 0,
      "request_id": "string",
      "status_code": 0,
      "stream": true,
      "latency_ms": 0,
      "usage_estimated": true
    }
  ],
  "keys": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "key_prefix": "sk-alwd-a1b2",
      "status": "active",
      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",
      "hidden": true,
      "created_at": "2019-08-24T14:15:22Z",
      "last_used_at": "2019-08-24T14:15:22Z",
      "revoked_at": "2019-08-24T14:15:22Z",
      "revoke_reason": "string",
      "expires_at": "2019-08-24T14:15:22Z"
    }
  ],
  "agents": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "display_name": "string",
      "template": "string",
      "framework": "string",
      "provider": "string",
      "model": "string",
      "status": "string",
      "public": true,
      "current_revision": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "revisions": [
        {
          "revision": 0,
          "entrypoint": "string",
          "message": "string",
          "created_by": "string",
          "created_at": "2019-08-24T14:15:22Z"
        }
      ]
    }
  ]
}

null

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

{
  "error": "validation failed",
  "request_id": "01J9Z3K8QWERTYUIOP"
}

AI Agents API

200application/json

401application/json

200application/json

401application/json

404application/json

201application/json

400application/json

401application/json

404application/json

200application/json

401application/json

404application/json

204

401application/json

404application/json

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

413

200application/json

401application/json

404application/json

503

200application/json

401application/json

404application/json

200application/json

400application/json

401application/json

404application/json

200application/json

400application/json

401application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`