Skip to main content
POST
/
agents
Create agent
curl --request POST \
  --url https://api.akua.dev/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "instructions": "<string>",
  "capabilities": [],
  "description": "<string>",
  "ambient": {
    "enabled": true,
    "triggers": [
      {
        "trigger_id": "<string>",
        "cooldown_seconds": 123,
        "relationship_scope": {},
        "resource_filters": [
          {
            "type": "<string>",
            "id": "<string>"
          }
        ]
      }
    ]
  }
}
'
{
  "id": "<string>",
  "workspace_id": "<string>",
  "organization_id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "capabilities": [],
  "ambient": {
    "enabled": true,
    "triggers": [
      {
        "trigger_id": "<string>",
        "cooldown_seconds": 123,
        "relationship_scope": {},
        "resource_filters": [
          {
            "type": "<string>",
            "id": "<string>"
          }
        ],
        "quiet_hours": {
          "timezone": "<string>",
          "start": "<string>",
          "end": "<string>"
        }
      }
    ],
    "policy": {
      "allowed_resource_scopes": [
        {
          "type": "<string>",
          "id": "<string>"
        }
      ],
      "max_spend_cents_per_trigger": 1
    }
  },
  "model_policy": {
    "default_model": "<string>",
    "credential_secret_id": "<string>",
    "allowed_models": [
      "<string>"
    ],
    "severity_model_overrides": [
      {
        "model": "<string>"
      }
    ],
    "max_budget_cents": 1,
    "max_turn_budget_cents": 1
  },
  "created_by": "<string>",
  "usage_summary": {
    "provider_cost_cents": 1,
    "provider_token_count": 1,
    "runtime_compute_seconds": 1,
    "runtime_storage_gb_hours": 1,
    "mcp_call_count": 1,
    "api_call_count": 1,
    "ambient_trigger_count": 1
  },
  "created_at": 1,
  "updated_at": 1,
  "etag": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.akua.dev/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

​
akua-context
string

Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens — a workspace-owned token implies its workspace.

Required string length: 1 - 53
Example:

"ws_j572abc123def456"

Body

application/json
​
name
string
required
Required string length: 1 - 120
​
instructions
string
required
Required string length: 1 - 20000
​
capabilities
enum<string>[]
required
Required array length: 1 - 10 elements
Available options:
CHAT,
CODING,
AMBIENT
​
description
string
Maximum string length: 500
​
ambient
object
​
model_policy
object

Response

Agent created

​
id
string
required
Required string length: 1 - 54
​
workspace_id
string
required
Required string length: 1 - 53
​
organization_id
string | null
required
Required string length: 1 - 54
​
name
string
required
​
description
string | null
required
​
instructions
string
required
​
state
enum<string>
required
Available options:
ENABLED,
ARCHIVED
​
origin
enum<string>
required
Available options:
PLATFORM,
USER,
SYSTEM
​
capabilities
enum<string>[]
required
Available options:
CHAT,
CODING,
AMBIENT
​
ambient
object
required
​
model_policy
object
required
​
created_by
string
required
​
usage_summary
object
required
​
created_at
integer
required

Unix timestamp (seconds)

Required range: x >= 0
​
updated_at
integer
required

Unix timestamp (seconds)

Required range: x >= 0
​
etag
string
required