Agent Hub API

Configure AI agents: LLM provider keys, model configurations, reusable skills, per-agent runtime settings, zero-trust access grants and connection requests, service-to-service grants, and agent invocation. Inbound email auto-reply routes appear in Agent Hub but are Channels-owned: the agent manager controls route lifecycle, status, policy, and reply address, while the address manager independently controls authoritative address_status. Conversations and inbound attachment materialization are managed through the separate Conversations service.

Base URL/api/v1/agents

Automation triggers: view every Agent Hub event, payload field, and predicate.

Inbound Email Routes

These cross-service endpoints are owned by Channels and surfaced in Agent Hub. An agent manager can create, pause, resume, configure, or delete the agent's auto-reply route and select a send-capable reply address. The canonical max_auto_replies_per_thread policy accepts 1-100 and defaults to 10. An address manager separately sets address_status to allowed or blocked; blocked is authoritative even when the route status is active.

GET/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes

List Agent Inbound Routes

List receiving addresses visible and receivable by the agent, their routes, and send-capable reply-address candidates.

Bearer token required. Permission: agents:agents:manage on the agent; Channels address visibility and receive eligibility also apply.

curl https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes \
  -H "Authorization: Bearer {token}"

Response

200 OK

[]

POST/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id}

Create Agent Inbound Route

Create an auto-reply route owned by the agent. Body accepts reply_address_id, status, and policy.max_auto_replies_per_thread.

Bearer token required. Permission: agents:agents:manage on the agent.

curl -X POST https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"policy":{"max_auto_replies_per_thread":10}}'

Response

201 Created

{
  "mode": "auto-reply",
  "status": "active",
  "address_status": "allowed",
  "policy": { "max_auto_replies_per_thread": 10 }
}

PATCH/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id}/{route_id}

Update Agent Inbound Route

Update the agent-owned reply address, active/paused status, or auto-reply policy. address_status is not writable from this surface.

Bearer token required. Permission: agents:agents:manage on the agent.

curl -X PATCH https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id}/{route_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Response

200 OK

{
  "status": "paused",
  "address_status": "allowed",
  "policy": { "max_auto_replies_per_thread": 10 }
}

DELETE/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id}/{route_id}

Delete Agent Inbound Route

Delete the agent-owned auto-reply route.

Bearer token required. Permission: agents:agents:manage on the agent.

curl -X DELETE https://platform.ergondata.ai/api/v1/channels/companies/{company_id}/agents/{agent_id}/inbound-routes/{address_id}/{route_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Agents

Read, update, and delete agents, and manage their avatars. An agent's identity (name, description, active flag) lives in IAM; this surface exposes it alongside the caller's capabilities and embedded runtime config.

GET/api/v1/agents/{agent_id}

Get Agent

Retrieve an agent's identity, the caller's capabilities, and its runtime config (if one has been set).

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Response Fields

Name	Type	Description
`identity`*	object	Agent identity
`capabilities`*	object	Caller's capabilities on this agent (view_settings, manage_settings, view_activity, manage_security)
`config`	object \| null	Embedded agent runtime config (see Agent Configs), or null if unset

curl https://platform.ergondata.ai/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "identity": {
    "id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Support Bot",
    "description": "Handles tier-1 support requests",
    "is_active": true,
    "avatar_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/agents/abcd1234-ef56-7890-abcd-ef1234567890/3f9b1c2d.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=...",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12"
  },
  "capabilities": {
    "view_settings": true,
    "manage_settings": true,
    "view_activity": true,
    "manage_security": false
  },
  "config": null
}

PATCH/api/v1/agents/{agent_id}

Update Agent

Update an agent's name, description, or active flag.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`name`	string \| null	Updated display name (1-200 chars)
`description`	string \| null	Updated description
`is_active`	boolean \| null	Activate or deactivate the agent

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Bot v2", "is_active": true}'

Response

200 OK

{
  "identity": {
    "id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Support Bot v2",
    "description": "Handles tier-1 support requests",
    "is_active": true,
    "avatar_url": null,
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12"
  },
  "capabilities": {
    "view_settings": true,
    "manage_settings": true,
    "view_activity": true,
    "manage_security": false
  },
  "config": null
}

DELETE/api/v1/agents/{agent_id}

Delete Agent

Permanently delete an agent and its configuration.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

PUT/api/v1/agents/{agent_id}/avatar

Upload Agent Avatar

Upload an avatar image for the agent (multipart form-data).

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`file`*	binary (multipart/form-data)	Avatar image file

curl -X PUT https://platform.ergondata.ai/api/v1/agents/{agent_id}/avatar \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

Response

200 OK

{
  "identity": {
    "id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Support Bot",
    "description": "Handles tier-1 support requests",
    "is_active": true,
    "avatar_url": "https://ergon-files.s3.us-east-1.amazonaws.com/avatars/agents/abcd1234-ef56-7890-abcd-ef1234567890/3f9b1c2d.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=86400&X-Amz-Signature=...",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12"
  },
  "capabilities": {
    "view_settings": true,
    "manage_settings": true,
    "view_activity": true,
    "manage_security": false
  },
  "config": null
}

DELETE/api/v1/agents/{agent_id}/avatar

Delete Agent Avatar

Remove the agent's avatar. Returns the updated agent detail.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/{agent_id}/avatar \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "identity": {
    "id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "name": "Support Bot",
    "description": "Handles tier-1 support requests",
    "is_active": true,
    "avatar_url": null,
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12"
  },
  "capabilities": {
    "view_settings": true,
    "manage_settings": true,
    "view_activity": true,
    "manage_security": false
  },
  "config": null
}

Provider Keys

Manage API keys for LLM providers (OpenAI, Anthropic, etc.). Provider keys are scoped to an organization and referenced by LLM configurations.

POST/api/v1/agents/companies/{company_id}/provider-keys

Create a Provider Key

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`name`*	string	Display name (1-200 chars)
`provider`*	string	Provider slug, e.g. openai, anthropic (1-50 chars). Providers marked coming_soon (see List LLM Providers) are not accepted yet.
`api_key`*	string	The provider API key (non-empty)
`base_url`	string \| null	Custom API base URL for a proxy or self-hosted model

Response Fields

Name	Type	Description
`id`*	UUID	Provider key ID
`company_id`*	UUID	Organization ID
`provider`*	string	Provider slug
`name`*	string	Display name
`api_key_masked`*	string	Masked API key (e.g. sk-...xxxx)
`base_url`*	string \| null	Custom base URL if set
`created_at`*	datetime	Creation timestamp
`health_status`*	string	Key health derived from the last agent run that used it: ok, exhausted (out of credits / quota), or invalid (provider rejected the key). The runtime flips this on a key-fatal error and resets it to ok after a successful run.
`last_error_code`*	string \| null	Normalised error code from the most recent failed run (kept even for transient errors that don't flip health_status).
`last_error_at`*	datetime \| null	Timestamp of the most recent error.
`last_error_message`*	string \| null	Human-readable detail of the most recent error.

curl -X POST https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/provider-keys \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production",
    "provider": "openai",
    "api_key": "sk-proj-abc123..."
  }'

Response

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "provider": "openai",
  "name": "OpenAI Production",
  "api_key_masked": "sk-...c123",
  "base_url": null,
  "created_at": "2025-01-15T10:30:00Z",
  "health_status": "ok",
  "last_error_code": null,
  "last_error_at": null,
  "last_error_message": null
}

GET/api/v1/agents/companies/{company_id}/provider-keys

List Provider Keys

List all provider keys for an organization.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Response Fields

Name	Type	Description
`[]`*	array	Array of provider key list items (id, provider, name, api_key_masked, created_at)

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/provider-keys \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "provider": "openai",
    "name": "OpenAI Production",
    "api_key_masked": "sk-...c123",
    "created_at": "2025-01-15T10:30:00Z",
    "health_status": "ok",
    "last_error_code": null,
    "last_error_at": null,
    "last_error_message": null
  }
]

GET/api/v1/agents/provider-keys/{key_id}

Get Provider Key

Retrieve a single provider key by ID.

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

curl https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "provider": "openai",
  "name": "OpenAI Production",
  "api_key_masked": "sk-...c123",
  "base_url": null,
  "created_at": "2025-01-15T10:30:00Z",
  "health_status": "ok",
  "last_error_code": null,
  "last_error_at": null,
  "last_error_message": null
}

PATCH/api/v1/agents/provider-keys/{key_id}

Update Provider Key

Update a provider key's name, API key, or base URL.

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

Request Body

Name	Type	Description
`name`	string \| null	Updated display name
`api_key`	string \| null	New API key value
`base_url`	string \| null	Updated base URL

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "OpenAI Production v2"}'

Response

200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "provider": "openai",
  "name": "OpenAI Production v2",
  "api_key_masked": "sk-...c123",
  "base_url": null,
  "created_at": "2025-01-15T10:30:00Z",
  "health_status": "ok",
  "last_error_code": null,
  "last_error_at": null,
  "last_error_message": null
}

DELETE/api/v1/agents/provider-keys/{key_id}

Delete Provider Key

Delete a provider key. LLM configs referencing this key will stop working.

Bearer token required.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

LLM Configs

LLM configurations pair a provider key with a specific model and parameters like temperature and max tokens.

GET/api/v1/agents/llm-providers

List LLM Providers

Get available LLM providers and their models. Each model includes its context window, capabilities, and the platform's current per-million-token prices (used for cost estimation). Capabilities are tools (native tool calling, required to back a config -- so every offered model has it), structured_output (schema-constrained JSON, required for structured/hybrid agent invocations), and reasoning. Providers with status "coming_soon" are placeholders and cannot back a config yet. Prices are indicative and may lag the provider's changes -- confirm against each provider's official pricing page (pricing_url).

Bearer token required.

curl https://platform.ergondata.ai/api/v1/agents/llm-providers \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "11111111-1111-1111-1111-111111111111",
    "slug": "openai",
    "name": "OpenAI",
    "status": "available",
    "pricing_url": "https://openai.com/api/pricing/",
    "models": [
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "slug": "gpt-5.5",
        "name": "GPT-5.5",
        "description": "Latest flagship - best for complex coding and professional work.",
        "tag": "Flagship",
        "context_window": 1050000,
        "max_output_tokens": 128000,
        "input_price_per_mtok": 5.0,
        "output_price_per_mtok": 30.0,
        "currency": "USD",
        "capabilities": { "tools": true, "structured_output": true, "reasoning": true },
        "status": "available"
      }
    ]
  },
  {
    "id": "44444444-4444-4444-4444-444444444444",
    "slug": "anthropic",
    "name": "Anthropic",
    "status": "available",
    "pricing_url": "https://www.anthropic.com/pricing",
    "models": [
      {
        "id": "55555555-5555-5555-5555-555555555555",
        "slug": "claude-opus-4-8",
        "name": "Claude Opus 4.8",
        "description": "Anthropic's most capable model for complex reasoning and agentic coding.",
        "tag": "Flagship",
        "context_window": 1000000,
        "max_output_tokens": 128000,
        "input_price_per_mtok": 5.0,
        "output_price_per_mtok": 25.0,
        "currency": "USD",
        "capabilities": { "tools": true, "structured_output": true, "reasoning": true },
        "status": "available"
      }
    ]
  },
  {
    "id": "66666666-6666-6666-6666-666666666666",
    "slug": "gemini",
    "name": "Google Gemini",
    "status": "coming_soon",
    "pricing_url": "https://ai.google.dev/pricing",
    "models": []
  }
]

POST/api/v1/agents/companies/{company_id}/llm-configs

Create LLM Config

Create a new LLM configuration. A config holds a pool of provider keys and a set of catalog models that agents can run.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`name`*	string	Display name (1-200 chars)
`provider_key_ids`	UUID[]	The config's provider-key pool. May include more than one key, even for the same provider. Defaults to empty.
`models`	{ provider, model_slug }[]	The config's model set. Each model must be an available, tool-capable catalog model (see List LLM Providers) whose provider has a key in provider_key_ids; unknown, coming_soon, non-tool, or unbacked models are rejected. Defaults to empty.
`temperature`	float \| null	Sampling temperature
`max_tokens`	integer \| null	Maximum response tokens

Response Fields

Name	Type	Description
`id`*	UUID	Config ID
`company_id`*	UUID	Organization ID
`name`*	string	Display name
`keys`*	{ provider_key_id, provider_key_name, provider }[]	The provider-key pool
`models`*	{ provider, model_slug, name }[]	The model set
`temperature`*	float \| null	Temperature if set
`max_tokens`*	integer \| null	Max tokens if set
`created_at`*	datetime	Creation timestamp

curl -X POST https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/llm-configs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default",
    "provider_key_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "models": [
      { "provider": "openai", "model_slug": "gpt-5.5" },
      { "provider": "openai", "model_slug": "gpt-5.5-codex" }
    ],
    "temperature": 0.7,
    "max_tokens": 4096
  }'

Response

201 Created

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Default",
  "keys": [
    {
      "provider_key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider_key_name": "OpenAI Production",
      "provider": "openai"
    }
  ],
  "models": [
    { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" },
    { "provider": "openai", "model_slug": "gpt-5.5-codex", "name": "GPT-5.5 Codex" }
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/agents/companies/{company_id}/llm-configs

List LLM Configs

List all LLM configurations for an organization.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/llm-configs \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "Default",
    "providers": ["openai"],
    "models": [
      { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" },
      { "provider": "openai", "model_slug": "gpt-5.5-codex", "name": "GPT-5.5 Codex" }
    ],
    "model_count": 2,
    "key_count": 1,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

GET/api/v1/agents/llm-configs/{config_id}

Get LLM Config

Retrieve a single LLM configuration.

Bearer token required.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

curl https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Default",
  "keys": [
    {
      "provider_key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider_key_name": "OpenAI Production",
      "provider": "openai"
    }
  ],
  "models": [
    { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" }
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "created_at": "2025-01-15T10:30:00Z"
}

PATCH/api/v1/agents/llm-configs/{config_id}

Update LLM Config

Update an LLM configuration's name, key pool, model set, or parameters.

Bearer token required.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

Request Body

Name	Type	Description
`name`	string \| null	Updated display name
`provider_key_ids`	UUID[] \| null	When present, fully replaces the key pool (PUT semantics). Omit to leave unchanged.
`models`	{ provider, model_slug }[] \| null	When present, fully replaces the model set (PUT semantics). Omit to leave unchanged. Same validation as create.
`temperature`	float \| null	Updated temperature
`max_tokens`	integer \| null	Updated max tokens

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"temperature": 0.3}'

Response

200 OK

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Default",
  "keys": [
    {
      "provider_key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "provider_key_name": "OpenAI Production",
      "provider": "openai"
    }
  ],
  "models": [
    { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" }
  ],
  "temperature": 0.3,
  "max_tokens": 4096,
  "created_at": "2025-01-15T10:30:00Z"
}

DELETE/api/v1/agents/llm-configs/{config_id}

Delete LLM Config

Delete an LLM configuration.

Bearer token required.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/{agent_id}/usable-models

List Agent Usable Models

List every concrete (llm_config_id, model_slug) route a specific agent can run, enriched with catalog metadata, configuration identity, and the invoking principal's budget_state/remaining allowance. The same model may appear more than once when several usable configurations provide it; clients must preserve llm_config_id when selecting a route. Exhausted routes should be disabled rather than silently replaced. is_default marks the primary configuration/model route used without an override. Agent tool: agents.agents.list_usable_models.

Bearer token with agents:agents:view on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/usable-models \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "models": [
    {
      "provider": "openai",
      "model_slug": "gpt-5.5",
      "name": "GPT-5.5",
      "tag": "Flagship",
      "description": "Latest flagship - best for complex coding and professional work.",
      "context_window": 1050000,
      "input_price_per_mtok": 5.0,
      "output_price_per_mtok": 30.0,
      "currency": "USD",
      "capabilities": { "tools": true, "structured_output": true, "reasoning": true },
      "llm_config_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "llm_config_name": "Default",
      "is_default": true,
      "budget_state": "available",
      "budget_exhausted_metric": null,
      "remaining_cost_usd": 87.5,
      "remaining_tokens": 4580000
    }
  ],
  "default_model_slug": "gpt-5.5",
  "primary_llm_config_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}

GET/api/v1/agents/{agent_id}/usable-configs

List Agent Usable Configs

List the LLM configs a specific agent holds agents:llm-configs:use on -- the exact set eligible to be its primary config. This is scoped to what has been granted to the agent (from a config's Security page), not every config the calling user can see, so it is empty until such a grant exists. Each summary includes the config's model set.

Bearer token with agents:agents:view on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/usable-configs \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "Default",
    "models": [
      { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" },
      { "provider": "anthropic", "model_slug": "claude-opus-4-8", "name": "Claude Opus 4.8" }
    ]
  }
]

Skills

Reusable Markdown instruction bundles. A skill is a connection-gated federated zone: an agent sees and uses a custom skill only when its principal is granted agents:skills:view on the skill (from the skill's Security surface, which also manages connections). Skills are created and listed under a company, addressed individually by ID, and attached to an agent (assignments). The per-agent catalog combines platform skills and the skills the agent can view, with their assignment state.

GET/api/v1/agents/companies/{company_id}/skills

List Skills

List platform skills and company skills the caller can view. Each item carries capability flags (view, edit, delete, manage_access).

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Query Parameters

Name	Type	Description
`q`	string \| null	Free-text search (max 200 chars)
`limit`	integer	Results per page (1-100)Default: `24`
`offset`	integer	Number of results to skipDefault: `0`

Response Fields

Name	Type	Description
`items`*	array	Array of skill list items (id, company_id, name, slug, description, is_system_managed, capabilities, created_at, updated_at)
`total`*	integer	Total skill count
`limit`*	integer	Page size
`offset`*	integer	Offset applied

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/skills?limit=24&offset=0" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "5ki11111-2222-3333-4444-555566667777",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "name": "Support Triage",
      "slug": "support-triage",
      "description": "Classify and route support requests",
      "is_system_managed": false,
      "capabilities": {
        "view": true,
        "edit": true,
        "delete": false,
        "manage_access": true
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 24,
  "offset": 0
}

POST/api/v1/agents/companies/{company_id}/skills

Create Skill

Create a company skill. The creator receives manage access on the new skill.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`name`*	string	Skill display name (1-200 chars)
`instructions_markdown`*	string	Instructions injected when the skill is attached to an agent (non-empty)
`slug`	string \| null	Optional stable slug (1-100 chars)
`description`	string \| null	Catalog summary

Response Fields

Name	Type	Description
`id`*	UUID	Skill ID
`company_id`*	UUID \| null	Organization ID
`name`*	string	Display name
`slug`*	string	Stable slug
`description`*	string \| null	Catalog summary
`instructions_markdown`*	string	Skill instructions
`is_system_managed`*	boolean	Whether the skill is platform-managed
`capabilities`*	object	Caller capabilities (view, edit, delete, manage_access)
`created_at`*	datetime	Creation timestamp
`updated_at`*	datetime	Last update timestamp

curl -X POST https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/skills \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Triage",
    "instructions_markdown": "Classify the user request and propose the next owner."
  }'

Response

201 Created

{
  "id": "5ki11111-2222-3333-4444-555566667777",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Support Triage",
  "slug": "support-triage",
  "description": null,
  "instructions_markdown": "Classify the user request and propose the next owner.",
  "is_system_managed": false,
  "capabilities": {
    "view": true,
    "edit": true,
    "delete": true,
    "manage_access": true
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/agents/skills/{skill_id}

Get Skill

Retrieve a single skill, including its instructions.

Bearer token required.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

Query Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID the skill is viewed under

curl "https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}?company_id={company_id}" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "5ki11111-2222-3333-4444-555566667777",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Support Triage",
  "slug": "support-triage",
  "description": "Classify and route support requests",
  "instructions_markdown": "Classify the user request and propose the next owner.",
  "is_system_managed": false,
  "capabilities": {
    "view": true,
    "edit": true,
    "delete": true,
    "manage_access": true
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

PATCH/api/v1/agents/skills/{skill_id}

Update Skill

Update a skill's name, slug, description, or instructions.

Bearer token required.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

Request Body

Name	Type	Description
`name`	string \| null	Updated name (1-200 chars)
`slug`	string \| null	Updated slug (1-100 chars)
`description`	string \| null	Updated description
`instructions_markdown`	string \| null	Updated instructions (non-empty)

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/skills/{skill_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Classify, prioritize, and route support requests"}'

Response

200 OK

{
  "id": "5ki11111-2222-3333-4444-555566667777",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Support Triage",
  "slug": "support-triage",
  "description": "Classify, prioritize, and route support requests",
  "instructions_markdown": "Classify the user request and propose the next owner.",
  "is_system_managed": false,
  "capabilities": {
    "view": true,
    "edit": true,
    "delete": true,
    "manage_access": true
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z"
}

DELETE/api/v1/agents/skills/{skill_id}

Delete Skill

Delete a skill. Existing agent assignments to the skill are removed.

Bearer token required.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/skills/{skill_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/agents/{agent_id}/skills/catalog

List Agent Skill Catalog

List skills the agent can use: platform skills (source 'platform') and custom skills the agent holds agents:skills:view on (source 'granted'), each annotated with its source and current assignment, if any.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/skills/catalog \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "skill": {
      "id": "5ki11111-2222-3333-4444-555566667777",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "name": "Support Triage",
      "slug": "support-triage",
      "description": "Classify and route support requests",
      "is_system_managed": false,
      "capabilities": {
        "view": true,
        "edit": true,
        "delete": false,
        "manage_access": true
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    "source": "granted",
    "assignment": {
      "id": "asg11111-2222-3333-4444-555566667777",
      "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
      "skill_id": "5ki11111-2222-3333-4444-555566667777",
      "load_mode": "selectable",
      "attached_by_principal_id": "mem-1234-5678-90ab-cdef12345678",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  }
]

GET/api/v1/agents/agents/{agent_id}/skills/assignments

List Agent Skill Assignments

List explicit non-primitive skill assignments. load_mode is pinned, selectable, searchable, or null (explicitly disabled). System non-primitive skills with no row default to searchable; custom skills require a row.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/skills/assignments \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "asg11111-2222-3333-4444-555566667777",
    "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "skill_id": "5ki11111-2222-3333-4444-555566667777",
    "load_mode": "selectable",
    "attached_by_principal_id": "mem-1234-5678-90ab-cdef12345678",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/agents/agents/{agent_id}/skills/assignments

Create Agent Skill Assignment

Attach a skill to an agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`skill_id`*	UUID	Skill to attach
`load_mode`*	"pinned" \| "selectable" \| "searchable" \| null	How instructions are made available; null explicitly disables

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/skills/assignments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"skill_id": "5ki11111-2222-3333-4444-555566667777", "load_mode": "selectable"}'

Response

201 Created

{
  "id": "asg11111-2222-3333-4444-555566667777",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "skill_id": "5ki11111-2222-3333-4444-555566667777",
  "load_mode": "selectable",
  "attached_by_principal_id": "mem-1234-5678-90ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

PATCH/api/v1/agents/agents/{agent_id}/skills/assignments/{assignment_id}

Update Agent Skill Assignment

Change an attached skill's load mode or explicitly disable it with null.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`assignment_id`*	string (UUID)	Assignment ID

Request Body

Name	Type	Description
`load_mode`*	"pinned" \| "selectable" \| "searchable" \| null	New load mode

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/skills/assignments/{assignment_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"load_mode": null}'

Response

200 OK

{
  "id": "asg11111-2222-3333-4444-555566667777",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "skill_id": "5ki11111-2222-3333-4444-555566667777",
  "load_mode": null,
  "attached_by_principal_id": "mem-1234-5678-90ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z"
}

DELETE/api/v1/agents/agents/{agent_id}/skills/assignments/{assignment_id}

Delete Agent Skill Assignment

Detach a skill from an agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`assignment_id`*	string (UUID)	Assignment ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/skills/assignments/{assignment_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Agent Configs

Configure individual agents with system prompts, LLM configs, and runtime parameters such as temperature, token limits, and tool-call rate limits.

GET/api/v1/agents/{agent_id}/config

Get Agent Config

Retrieve the runtime configuration for a specific agent.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Response Fields

Name	Type	Description
`id`*	UUID	Config record ID
`agent_id`*	UUID	Agent ID
`company_id`*	UUID	Organization ID
`system_prompt`*	string \| null	System prompt for the agent
`primary_llm_config`	object \| null	Primary LLM config summary (id, name, models[])
`default_model_slug`	string \| null	Default model the agent runs (from the primary config's model set). Null falls back to the config's first model.
`temperature`*	float \| null	Override temperature (0-2)
`top_p`*	float \| null	Top-p sampling (0-1)
`max_tokens`*	integer \| null	Max response tokens
`timeout`*	integer \| null	Request timeout in seconds (1-600)
`max_tool_iterations`*	integer \| null	Max tool call loops (1-100)
`max_tool_calls_per_minute`*	integer \| null	Tool call rate limit (1-600)
`conversation_starters_mode`	"off" \| "preset" \| "infer"	Default opening behavior for new conversations with this agent
`conversation_starter_presets`	string[]	Current inferred starter suggestions, when available
`conversations_always_public`*	boolean	Privacy lock. When true, every conversation this agent joins is forced public. Toggle it via PATCH /agents/{agent_id}/config/privacy (gated by agents:privacy:manage), not this config endpoint.
`created_at`*	datetime	Creation timestamp
`updated_at`*	datetime	Last update timestamp

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/config \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "system_prompt": "You are a helpful support assistant.",
  "primary_llm_config": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "Default",
    "models": [
      { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" }
    ]
  },
  "default_model_slug": "gpt-5.5",
  "temperature": 0.7,
  "top_p": null,
  "max_tokens": 4096,
  "timeout": 120,
  "max_tool_iterations": 10,
  "max_tool_calls_per_minute": 60,
  "conversation_starters_mode": "infer",
  "conversation_starter_presets": ["What changed since our last review?"],
  "conversations_always_public": false,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

PUT/api/v1/agents/{agent_id}/config

Update Agent Config

Create or update an agent's configuration. company_id is required; all other fields are optional and only provided fields are updated.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`company_id`*	UUID	Organization ID
`system_prompt`	string \| null	System prompt
`primary_llm_config_id`	UUID \| null	Primary LLM config ID
`default_model_slug`	string \| null	Default model slug; must belong to the primary config's model set. Null falls back to the config's first model.
`temperature`	float \| null	Temperature (0-2)
`top_p`	float \| null	Top-p (0-1)
`max_tokens`	integer \| null	Max tokens (>= 1)
`timeout`	integer \| null	Timeout in seconds (1-600)
`max_tool_iterations`	integer \| null	Max tool loops (1-100)
`max_tool_calls_per_minute`	integer \| null	Tool rate limit (1-600)
`conversation_starters_mode`	"off" \| "preset" \| "infer"	Default opening behavior for new conversations

curl -X PUT https://platform.ergondata.ai/api/v1/agents/{agent_id}/config \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "system_prompt": "You are a helpful support assistant.",
    "primary_llm_config_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "temperature": 0.7,
    "max_tokens": 4096
  }'

Response

200 OK

{
  "id": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "system_prompt": "You are a helpful support assistant.",
  "primary_llm_config": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "name": "Default",
    "models": [
      { "provider": "openai", "model_slug": "gpt-5.5", "name": "GPT-5.5" }
    ]
  },
  "default_model_slug": "gpt-5.5",
  "temperature": 0.7,
  "top_p": null,
  "max_tokens": 4096,
  "timeout": 120,
  "max_tool_iterations": 10,
  "max_tool_calls_per_minute": 60,
  "conversation_starters_mode": "off",
  "conversation_starter_presets": [],
  "conversations_always_public": false,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T09:00:00Z"
}

GET/api/v1/agents/{agent_id}/conversation-starters

Resolve Conversation Starters

Resolve off, preset, or inferred starter items for the authenticated principal. Infer mode falls back to configured presets when the optional Conversations inference hook is unavailable. Tool slug: agents.agents.get_conversation_starters.

Bearer token with agents:agents:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`principal_id`	UUID	Compatibility assertion; when supplied it must equal the authenticated principal

Response Fields

Name	Type	Description
`mode`*	"off" \| "preset" \| "infer"	Configured mode
`items`*	string[]	Resolved starter chips
`source`*	string	off, preset, llm_inferred, deterministic_fallback, mixed, or unavailable
`inference_available`*	boolean	Whether inference succeeded

curl "https://platform.ergondata.ai/api/v1/agents/{agent_id}/conversation-starters" -H "Authorization: Bearer {token}"

Response

200 OK

{"mode":"infer","items":["What changed since our last review?"],"source":"llm_inferred","inference_available":true}

POST/api/v1/agents/{agent_id}/prior-digests/search

Search Prior Conversation Digests

Search participant-scoped digests from prior conversations. The server binds the acting agent to the authenticated principal and returns confidence-aware guidance. Tool slug: agents.conversations.search_prior_digests.

Bearer agent token with agents:agents:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Request Body

Name	Type	Description
`current_user_id`*	UUID	Current user
`current_conversation_id`*	UUID	Current conversation
`q`*	string	Semantic search query
`limit`	integer	Maximum digest hits

curl -X POST https://platform.ergondata.ai/api/v1/agents/{agent_id}/prior-digests/search -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"current_user_id":"{user_id}","current_conversation_id":"{conversation_id}","q":"renewal policy"}'

Response

200 OK

{"items":[],"total":0,"status":"ok","guidance":"No matching prior context was found. Say that explicitly and do not speculate."}

PATCH/api/v1/agents/{agent_id}/config/privacy

Update Agent Privacy Lock

Toggle the agent's conversations_always_public privacy lock. When enabled, every conversation the agent participates in is forced public (and explicit private requests on those conversations are rejected). This is a dedicated endpoint gated by agents:privacy:manage, separate from the general config write.

Bearer token required. Permission: agents:privacy:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`company_id`*	UUID	Organization ID
`conversations_always_public`*	boolean	Enable or disable the always-public privacy lock.

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/{agent_id}/config/privacy \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe", "conversations_always_public": true }'

Response

200 OK

{
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "conversations_always_public": true,
  "system_prompt": "You are a helpful support assistant.",
  "temperature": 0.7,
  "updated_at": "2025-01-16T09:00:00Z"
}

Config Status

Check which agents have active configurations within your organization.

GET/api/v1/agents/companies/{company_id}/config-status

List Configured Agents

List agent IDs that have a configuration row for the organization.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Query Parameters

Name	Type	Description
`limit`	integer	Results per page (1-500)Default: `100`
`offset`	integer	Number of results to skipDefault: `0`

Response Fields

Name	Type	Description
`configured_agent_ids`*	string[]	List of agent IDs with active configurations

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/config-status?limit=100&offset=0" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "configured_agent_ids": [
    "abcd1234-ef56-7890-abcd-ef1234567890",
    "dcba4321-65fe-0987-dcba-0987654321fe"
  ]
}

Memory & Preferences

Transparent user preferences and agent-scoped semantic memories. These are separate from Conversations notes and digests.

GET/api/v1/agents/{agent_id}/user-preferences/{principal_id}

Get User Preference

Get the revised-in-place Markdown preferences for an active conversation participant. Tool slug: agents.user_preferences.view.

Bearer token with agents:agents:use on the agent; caller/target participation is enforced.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`principal_id`*	UUID	User principal ID

Response Fields

Name	Type	Description
`markdown`*	string	Current preferences
`source_conversation_id`	UUID \| null	Last source conversation

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/user-preferences/{principal_id} -H "Authorization: Bearer {token}"

Response

200 OK

{"id":"pref-id","agent_id":"agent-id","principal_id":"principal-id","markdown":"Prefer concise answers.","source_conversation_id":null}

PUT/api/v1/agents/{agent_id}/user-preferences/{principal_id}

Update User Preference

Replace and consolidate the complete preference record for an active participant. Tool slug: agents.user_preferences.update.

Bearer token with agents:agents:use on the agent; caller/target participation is enforced.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`principal_id`*	UUID	User principal ID

Request Body

Name	Type	Description
`markdown`*	string	Replacement preferences

curl -X PUT https://platform.ergondata.ai/api/v1/agents/{agent_id}/user-preferences/{principal_id} -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"markdown":"Prefer concise answers."}'

Response

200 OK

{"id":"pref-id","agent_id":"agent-id","principal_id":"principal-id","markdown":"Prefer concise answers.","source_conversation_id":null}

GET/api/v1/agents/users/me/preferences

List My Preferences

List every preference for the signed-in principal across agents.

Bearer token bound to a company principal.

Response Fields

Name	Type	Description
`items`*	UserPreference[]	Preferences with source and confidence
`total`*	integer	Total count

curl https://platform.ergondata.ai/api/v1/agents/users/me/preferences -H "Authorization: Bearer {token}"

Response

200 OK

{"items":[{"id":"pref-id","category":"communication","key":"tone","value":"concise","source":"inferred","confidence":0.92}],"total":1}

PATCH/api/v1/agents/users/me/preferences/{preference_id}

Update My Preference

Correct a preference; the revised record becomes explicit.

Bearer token. The preference must belong to the signed-in principal.

Path Parameters

Name	Type	Description
`preference_id`*	UUID	Preference ID

Request Body

Name	Type	Description
`value`*	string	Corrected value

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/users/me/preferences/{preference_id} -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"value":"concise"}'

Response

200 OK

{"id":"pref-id","category":"communication","key":"tone","value":"concise","source":"explicit","confidence":null}

DELETE/api/v1/agents/users/me/preferences/{preference_id}

Delete My Preference

Delete one preference owned by the signed-in user.

Bearer token required. Self only.

Path Parameters

Name	Type	Description
`preference_id`*	UUID	Preference ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/users/me/preferences/{preference_id} -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/{agent_id}/preferences

List Agent Preferences

Manager audit view of participant preference records retained for an agent. Tool slug: agents.preferences.list.

Bearer token with agents:preferences:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`limit`	integer	1-200; default 100
`offset`	integer	Pagination offset

curl "https://platform.ergondata.ai/api/v1/agents/{agent_id}/preferences" -H "Authorization: Bearer {token}"

Response

200 OK

{"items":[{"id":"pref-id","agent_id":"agent-id","principal_id":"principal-id","markdown":"Prefer concise answers."}],"total":1}

PATCH/api/v1/agents/{agent_id}/preferences/{preference_id}

Update Agent Preference

Manager correction of one participant preference record. Tool slug: agents.preferences.update.

Bearer token with agents:preferences:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`preference_id`*	UUID	Preference ID

Request Body

Name	Type	Description
`value`*	string	Replacement preference

curl -X PATCH https://platform.ergondata.ai/api/v1/agents/{agent_id}/preferences/{preference_id} -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"value":"Prefer concise answers."}'

Response

200 OK

{"id":"pref-id","agent_id":"agent-id","principal_id":"principal-id","markdown":"Prefer concise answers.","source":"explicit"}

DELETE/api/v1/agents/{agent_id}/preferences/{preference_id}

Delete Agent Preference

Manager deletion of one participant preference record. Tool slug: agents.preferences.delete.

Bearer token with agents:preferences:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`preference_id`*	UUID	Preference ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/{agent_id}/preferences/{preference_id} -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/agents/{agent_id}/memories

Record Agent Memory

Record durable general knowledge in authoritative Agents storage. The lazy Buckets general/ export is best-effort and is never the source of truth. Tool slug: agents.memories.record.

Bearer token with agents:memories:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Request Body

Name	Type	Description
`title`*	string	Memory title (1-240 characters)
`markdown`*	string	Durable general knowledge; never a person's preferences
`scope`	"general"	Only general is accepted
`source_conversation_id`	UUID \| null	Optional provenance
`source_type`	string \| null	Optional source category
`source_id`	string \| null	Optional source identifier

curl -X POST https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"title":"Renewal policy","markdown":"Renewals require finance approval.","scope":"general"}'

Response

201 Created

{"id":"memory-id","agent_id":"agent-id","title":"Renewal policy","markdown":"Renewals require finance approval.","export_status":"exported"}

GET/api/v1/agents/{agent_id}/memories

List Agent Memories

List authoritative typed semantic memories. Tool slug: agents.memories.list.

Bearer token with agents:memories:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`limit`	integer	1-200; default 50
`offset`	integer	Pagination offset

Response Fields

Name	Type	Description
`items`*	AgentMemory[]	Semantic memories
`total`*	integer	Total count

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories -H "Authorization: Bearer {token}"

Response

200 OK

{"items":[{"id":"memory-id","agent_id":"agent-id","title":"Renewal policy","markdown":"Renewals require finance approval.","source_conversation_id":"conversation-id","export_status":"exported"}],"total":1}

GET/api/v1/agents/{agent_id}/memories/recall

Recall Agent Memories

Search the lazy general/ export with folder-scoped Buckets hybrid search and return only hits that still map to live authoritative Agents rows. A bounded authoritative-text fallback preserves availability. Tool slug: agents.memories.recall.

Bearer token with agents:memories:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`q`*	string[]	One or more non-empty search queries
`limit`	integer	1-25; default 10
`min_similarity`	number	0-1; default 0.3

Response Fields

Name	Type	Description
`items`*	object[]	Authoritative memory hits and scores
`total`*	integer	Returned hit count
`source`*	"buckets_hybrid" \| "authoritative_fallback"	Retrieval path used

curl "https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories/recall?q=renewal&q=finance&limit=10" -H "Authorization: Bearer {token}"

Response

200 OK

{"items":[{"memory_id":"memory-id","title":"Renewal policy","content_text":"Renewals require finance approval."}],"total":1,"source":"buckets_hybrid"}

GET/api/v1/agents/{agent_id}/memories/export

Export Agent Memories

Download every authoritative semantic memory for the agent as Markdown. Tool slug: agents.memories.export.

Bearer token with agents:memories:view on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Response Fields

Name	Type	Description
`body`*	text/markdown	Ordered Markdown export

curl https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories/export -H "Authorization: Bearer {token}"

Response

200 OK

# Agent memory export — agent-id

## Renewal policy

Renewals require finance approval.

POST/api/v1/agents/{agent_id}/memories/{memory_id}/retry-export

Retry Agent Memory Export

Retry the idempotent Buckets export for a failed or pending semantic memory. Successful exports are returned without duplication. Tool slug: agents.memories.retry_export.

Bearer token with agents:memories:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`memory_id`*	UUID	Memory ID

curl -X POST https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories/{memory_id}/retry-export -H "Authorization: Bearer {token}"

Response

200 OK

{"id":"memory-id","agent_id":"agent-id","title":"Renewal policy","export_status":"exported"}

DELETE/api/v1/agents/{agent_id}/memories/{memory_id}

Delete Agent Memory

Delete one authoritative semantic memory and best-effort remove its export. Tool slug: agents.memories.delete.

Bearer token with agents:memories:manage on the agent.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID
`memory_id`*	UUID	Memory ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/{agent_id}/memories/{memory_id} -H "Authorization: Bearer {token}"

Response

204 No Content

Invoke

Trigger an agent invocation programmatically for explicit service-to-service integrations and draft structured-output JSON schemas. Inbound email does not call this route directly; Channels emits a route snapshot and Conversations triggers the selected agent through conversations.message.added.

POST/api/v1/agents/agents/{agent_id}/invoke

Invoke Agent

Send an input payload to an agent as a headless AgentRun. No Conversations conversation, message, bucket, participant, or grant is created. The agent processes the request asynchronously and publishes run lifecycle events keyed by run_id. The agent's company is derived from the agent record, not the caller.

Bearer token with agents:agents:use on the agent's resource. Internal service-key callers skip the use gate but cannot claim automation principal attribution without a matching bearer token.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID to invoke

Request Body

Name	Type	Description
`input`*	object	Opaque payload handed to the agent (e.g. message, metadata; channel hand-offs may add subject, text, html, contact_id)
`prompt`	string \| null	Optional system-level prompt appended to the run metadata
`mode`	string \| null	Reply shape: freeform, structured, or hybrid. structured/hybrid require the agent's model to support the structured_output capability (see List LLM Providers); otherwise the call is rejected with 422.
`output_schema`	object \| null	JSON Schema the structured reply must satisfy (for structured/hybrid modes)
`settings`	object \| null	Per-run overrides: max_tokens, max_tool_iterations, temperature, top_p, max_tool_calls_per_minute, timeout
`skill_ids`	string[] \| null	Assigned selectable skill IDs to activate for this run; pinned skills remain active
`llm_config_id`	string \| null	Pin a specific LLM config for this run, overriding the agent's primary config. Must be a config the agent holds agents:llm-configs:use on (see List Agent Usable Configs); an unusable id falls back to the agent's primary binding. Omit to use the agent default.
`model_slug`	string \| null	Pin a specific model slug for this run, resolved against llm_config_id (or the agent's primary config). Omit to use the config / agent default model.
`source_type`	string	Source of the invocationDefault: `api`

Response Fields

Name	Type	Description
`run_id`*	string	Created agent run ID
`conversation_id`	string \| null	Legacy transition field; null for headless invokes
`message_id`	string \| null	Legacy transition field; null for headless invokes
`status`*	string	Initially 'pending'; final state arrives via lifecycle events

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/invoke \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "from": "[email protected]",
      "subject": "Order status",
      "body": "Where is my order #12345?"
    },
    "source_type": "api"
  }'

Response

202 Accepted

{
  "run_id": "run-1111-2222-3333-444455556666",
  "conversation_id": null,
  "message_id": null,
  "status": "pending"
}

GET/api/v1/agents/agents/{agent_id}/runs/{run_id}

Get Agent Run

Read durable lifecycle, output/error, automation attribution, transcript count, aggregated usage/cost, and the latest prompt-section telemetry for a headless run. Agent, company, and run ownership are resolved together, so cross-tenant or wrong-agent IDs return 404.

Bearer token with agents:agents:view on the concrete agent resource.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Owning agent ID
`run_id`*	string (UUID)	AgentRun ID

Response Fields

Name	Type	Description
`status`*	string	pending, running, completed, or failed
`output_text`	string \| null	Durable text output
`output_structured`	object \| null	Durable structured output
`usage`*	object	Aggregated input/output tokens, cost, and latest prompt_section_tokens
`message_count`*	number	Durable run transcript row count

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/runs/{run_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "run-1111-2222-3333-444455556666",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "status": "completed",
  "output_text": "done",
  "conversation_id": null,
  "message_id": null,
  "usage": {
    "input_tokens": 123,
    "output_tokens": 17,
    "cost_usd": "0.00042",
    "prompt_section_tokens": {"provider-input-estimate": 950}
  },
  "message_count": 4
}

GET/api/v1/agents/agents/{agent_id}/runs/{run_id}/messages

List Agent Run Messages

Page through the durable provider-compatible transcript for a headless AgentRun, including role/content, tool fields, usage, and timestamps.

Bearer token with agents:agents:view on the concrete agent resource.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Owning agent ID
`run_id`*	string (UUID)	AgentRun ID

Query Parameters

Name	Type	Description
`limit`	number	Page size, 1–500Default: `100`
`offset`	number	Zero-based offsetDefault: `0`

Response Fields

Name	Type	Description
`items`*	array	Transcript messages ordered by sequence
`total`*	number	Total transcript row count

curl "https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/runs/{run_id}/messages?limit=100&offset=0" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [{"sequence": 0, "role": "user", "content": "hello", "tool_name": null}],
  "total": 1
}

POST/api/v1/agents/output-schema/generate

Generate Output Schema

Infer a JSON Schema from a natural-language description of the desired structured output. Useful for drafting an agent's output_schema. Authenticated company members only.

Bearer token required.

Request Body

Name	Type	Description
`prompt`*	string	Natural-language description of the desired structured output
`name`	string \| null	Optional name for the generated schema

Response Fields

Name	Type	Description
`json_schema`*	object	The generated JSON Schema
`rationale`*	string	Short explanation of the inferred schema

curl -X POST https://platform.ergondata.ai/api/v1/agents/output-schema/generate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Extract the order id and a boolean is_refundable"}'

Response

200 OK

{
  "json_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "is_refundable": { "type": "boolean" }
    },
    "required": ["order_id", "is_refundable"]
  },
  "rationale": "Derived two fields from the prompt: a string order id and a boolean refund flag."
}

Grants

Service-to-service grants let other services invoke or integrate with specific agents. Used by Channels for trigger routing and by Automations for agent invocation.

POST/api/v1/agents/agents/{agent_id}/grants

Create Agent Grant

Grant another service access to invoke or integrate with a specific agent.

Bearer token with agents:permissions:manage on the target agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID (IAM principal ID)

Request Body

Name	Type	Description
`service_name`*	string	Target service, e.g. channels, automations (1-50 chars)
`resource_id`	string \| null	Specific resource in the target service
`resource_label`	string \| null	Human-readable label for the resource
`label`	string \| null	Human-readable label for the grant

Response Fields

Name	Type	Description
`id`*	string	Grant ID
`company_id`*	string	Organization ID
`agent_id`*	string	Agent ID
`service_name`*	string	Target service
`resource_id`*	string \| null	Target resource
`resource_label`*	string \| null	Resource label
`label`*	string \| null	Grant label
`created_by`*	string \| null	Creator principal
`created_at`*	datetime	Creation timestamp

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"service_name": "channels", "resource_id": "addr-uuid"}'

Response

201 Created

{
  "id": "grant-001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "service_name": "channels",
  "resource_id": "addr-uuid",
  "resource_label": "Support Inbox",
  "label": null,
  "created_by": "mem-1234-5678-90ab-cdef12345678",
  "created_at": "2026-04-20T14:30:00Z"
}

GET/api/v1/agents/agents/{agent_id}/grants

List Agent Grants

List all service grants for an agent.

Bearer token with agents:permissions:manage on the target agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID (IAM principal ID)

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/grants \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "grant-001",
    "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
    "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "service_name": "channels",
    "resource_id": "addr-uuid",
    "resource_label": "Support Inbox",
    "label": null,
    "created_by": "mem-1234-5678-90ab-cdef12345678",
    "created_at": "2026-04-20T14:30:00Z"
  }
]

DELETE/api/v1/agents/agent-grants/{grant_id}

Delete Agent Grant

Revoke a service grant from an agent.

Bearer token with agents:permissions:manage on the target agent zone.

Path Parameters

Name	Type	Description
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/agent-grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/agents/granted

List Granted Agents

Discover which agents have granted access to a specific service. Used by Channels to find agents available for trigger routing and by Automations for agent invocation steps.

Bearer token required.

Query Parameters

Name	Type	Description
`service`*	string	Service slug, e.g. channels, automations
`resource_id`	string \| null	Specific resource in the calling service

Response Fields

Name	Type	Description
`[]`*	array	Array of granted agents (id, name)

curl "https://platform.ergondata.ai/api/v1/agents/agents/granted?service=channels" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "abcd1234-ef56-7890-abcd-ef1234567890",
    "name": "Support Bot"
  }
]

Budgets

Set recurring spend limits (estimated USD and exact tokens) on an LLM configuration, allocate portions to agents, and sub-allocate an agent/configuration share to IAM principals. An optional agent-wide recurring cap spans every configuration. The same agent_total policy may independently limit estimated cost, exact tokens, and session time for each conversation. Applicable scopes intersect, and the first limit reached stops further model calls. Worst-case usage is reserved atomically before each provider attempt so concurrent runs cannot spend the same remaining allowance.

GET/api/v1/agents/companies/{company_id}/budgets

List Budgets

List budgets for an LLM configuration, optionally narrowed to an agent or principal allocation. The agent_total scope is configuration-independent and is managed through the agent budget-plan API.

Bearer token required. Permission: agents:llm-configs:view.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Query Parameters

Name	Type	Description
`llm_config_id`*	UUID	LLM configuration ID
`agent_id`	UUID	Include this agent's allocation
`principal_id`	UUID	Include this user's allocation

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/budgets?llm_config_id={config_id}" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[{"scope_type":"llm_config","max_cost_usd":100,"window":"monthly"}]

PUT/api/v1/agents/companies/{company_id}/budgets

Create or Update Budget (Deprecated)

Deprecated compatibility dispatcher for existing clients. It preserves the original polymorphic authorization behavior, but agents should use the scope-specific config-budget or agent-total tools.

Bearer token required. Permission: agents:llm-configs:manage, or agents:agents:manage for agent_total.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Request Body

Name	Type	Description
`scope_type`*	llm_config \| agent \| agent_total \| agent_principal	Hierarchy level
`llm_config_id`	UUID \| null	Required except for agent_total
`agent_id`	UUID \| null	Required for agent, agent_total, and agent_principal scopes
`principal_id`	UUID \| null	Required for agent_principal scope
`principal_type`	member \| agent \| api_key \| automation \| null	IAM principal type for agent_principal scope
`max_cost_usd`	number \| null	USD ceiling. Maximum 10,000.
`max_tokens`	integer \| null	Combined input/output token ceiling. Maximum 100,000,000.
`conversation_max_cost_usd`	number \| null	Best-effort estimated cost limit for each conversation. Valid only on agent_total; maximum 100.
`conversation_max_tokens`	integer \| null	Exact combined token limit for each conversation. Valid only on agent_total; maximum 1,000,000.
`conversation_max_session_minutes`	integer \| null	Wall-clock session time limit for each conversation. Valid only on agent_total; maximum 1,440 minutes.
`allocation_mode`	fixed \| automatic \| null	Agent scope only. Fixed reserves allocation_percent; automatic receives a weighted share of the remainder.
`allocation_percent`	number \| null	Required for fixed agent allocations; greater than 0 and at most 100.
`allocation_weight`	number \| null	Required for automatic agent allocations; must be positive.
`window`*	daily \| weekly \| monthly	Recurring reset window

curl -X PUT https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/budgets \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"scope_type":"llm_config","llm_config_id":"{config_id}","max_cost_usd":100,"max_tokens":5000000,"window":"monthly"}'

Response

200 OK

{"scope_type":"llm_config","max_cost_usd":100,"max_tokens":null,"window":"monthly"}

PUT/api/v1/agents/companies/{company_id}/llm-configs/{llm_config_id}/budgets

Create or Update Config-Scoped Budget

Upsert an llm_config, agent allocation, or agent_principal budget anchored to one LLM configuration. Child allocations cannot exceed their parent. Agent tool: agents.budgets.upsert_config_scope.

Bearer token required. Permission: agents:llm-configs:manage on the path configuration.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`llm_config_id`*	UUID	LLM configuration ID; must match the request body

Request Body

Name	Type	Description
`scope_type`*	llm_config \| agent \| agent_principal	Configuration-anchored hierarchy level
`llm_config_id`*	UUID	Must equal the path llm_config_id
`agent_id`	UUID \| null	Required for agent and agent_principal scopes
`principal_id`	UUID \| null	Required for agent_principal scope
`max_cost_usd`	number \| null	Recurring USD ceiling
`max_tokens`	integer \| null	Recurring token ceiling
`window`*	daily \| weekly \| monthly	Recurring reset window

curl -X PUT https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/llm-configs/{llm_config_id}/budgets -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"scope_type":"llm_config","llm_config_id":"{llm_config_id}","max_cost_usd":100}'

Response

200 OK

{"scope_type":"llm_config","llm_config_id":"...","max_cost_usd":100,"window":"monthly"}

PUT/api/v1/agents/companies/{company_id}/agents/{agent_id}/budgets/total

Create or Update Agent Total Budget

Upsert an agent's cross-configuration recurring and per-conversation limits. Agent tool: agents.budgets.upsert_agent_total.

Bearer token required. Permission: agents:agents:manage on the path agent.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`agent_id`*	UUID	Agent ID; must match the request body

Request Body

Name	Type	Description
`scope_type`*	agent_total	Must be agent_total
`agent_id`*	UUID	Must equal the path agent_id
`max_cost_usd`	number \| null	Cross-configuration recurring USD ceiling
`max_tokens`	integer \| null	Cross-configuration recurring token ceiling
`conversation_max_cost_usd`	number \| null	Per-conversation USD ceiling
`conversation_max_tokens`	integer \| null	Per-conversation token ceiling
`conversation_max_session_minutes`	integer \| null	Per-conversation duration ceiling

curl -X PUT https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/agents/{agent_id}/budgets/total -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"scope_type":"agent_total","agent_id":"{agent_id}","max_cost_usd":250}'

Response

200 OK

{"scope_type":"agent_total","agent_id":"...","max_cost_usd":250,"window":"monthly"}

DELETE/api/v1/agents/budgets/{budget_id}

Delete Budget (Deprecated)

Deprecated compatibility dispatcher for existing clients. Agents should use the scope-specific delete tool.

Bearer token required. Permission: agents:llm-configs:manage, or agents:agents:manage for agent_total.

Path Parameters

Name	Type	Description
`budget_id`*	UUID	Budget ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/budgets/{budget_id} -H "Authorization: Bearer {token}"

Response

204 No Content

DELETE/api/v1/agents/companies/{company_id}/llm-configs/{llm_config_id}/budgets/{budget_id}

Delete Config-Scoped Budget

Delete an LLM-config, agent-allocation, or principal-allocation budget anchored to the path configuration. Agent tool: agents.budgets.delete_config_scope.

Bearer token required. Permission: agents:llm-configs:manage on the path configuration.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`llm_config_id`*	UUID	LLM config ID
`budget_id`*	UUID	Budget ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/llm-configs/{llm_config_id}/budgets/{budget_id} -H "Authorization: Bearer {token}"

Response

204 No Content

DELETE/api/v1/agents/companies/{company_id}/agents/{agent_id}/budgets/total/{budget_id}

Delete Agent Total Budget

Delete an agent's cross-configuration total budget. Agent tool: agents.budgets.delete_agent_total.

Bearer token required. Permission: agents:agents:manage on the path agent.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`agent_id`*	UUID	Agent ID
`budget_id`*	UUID	Budget ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/agents/{agent_id}/budgets/total/{budget_id} -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/companies/{company_id}/budgets/usage-summary

Get Budget Usage

Return spent and remaining USD/tokens for every applicable scope in its current reset window.

Bearer token required. Permission: agents:llm-configs:view.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Query Parameters

Name	Type	Description
`llm_config_id`*	UUID	LLM configuration ID
`agent_id`*	UUID	Agent ID
`principal_id`	UUID	Invoking user principal ID

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/budgets/usage-summary?llm_config_id={config_id}&agent_id={agent_id}" -H "Authorization: Bearer {token}"

Response

200 OK

{"items":[{"scope_type":"llm_config","spent_cost_usd":12.5,"remaining_cost_usd":87.5}],"exhausted":false}

GET/api/v1/agents/companies/{company_id}/budgets/plan

Get Budget Plan

Return the configuration pool draft, configuration-wide current-window usage, connected agent identities and policies, frozen active-window shares, policy versions, and the draft effective date. This endpoint is read-only and never creates a snapshot. Agent tool: agents.budgets.get_config_plan.

Bearer token required. Permission: agents:llm-configs:view.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Query Parameters

Name	Type	Description
`llm_config_id`*	UUID	LLM configuration ID

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/budgets/plan?llm_config_id={config_id}" -H "Authorization: Bearer {token}"

Response

200 OK

{"pool":{"max_cost_usd":100,"window":"monthly","policy_version":2},"pool_usage":{"spent_cost_usd":12.5,"remaining_cost_usd":87.5,"spent_tokens":420000,"remaining_tokens":4580000},"agents":[{"agent_id":"...","name":"Support Agent","can_use":true,"resolved_percent":50}],"active_window_end":"2026-08-01T00:00:00Z","draft_effective_at":"2026-08-01T00:00:00Z"}

PUT/api/v1/agents/companies/{company_id}/budgets/plan

Update Budget Plan

Atomically replace the pool spend limits (cost and tokens) and complete currently authorized agent allocation policy. Fixed rows provide allocation_percent; automatic rows provide allocation_weight. Conversation duration is not a pool concept; set it on the agent budget plan. Returns 409 when the IAM roster changed since the draft was loaded. Agent tool: agents.budgets.update_config_plan.

Bearer token required. Permission: agents:llm-configs:manage.

Path Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Request Body

Name	Type	Description
`llm_config_id`*	UUID	Configuration ID
`max_cost_usd`	number \| null	Pool USD ceiling. Maximum 10,000.
`max_tokens`	integer \| null	Pool token ceiling. Maximum 100,000,000.
`window`*	daily \| weekly \| monthly	Recurring reset window
`allocations`*	array	One row for every currently authorized agent: agent_id, allocation_mode, and allocation_percent or allocation_weight.

curl -X PUT https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/budgets/plan \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"llm_config_id":"{config_id}","max_cost_usd":100,"window":"monthly","allocations":[{"agent_id":"{agent_a}","allocation_mode":"fixed","allocation_percent":30},{"agent_id":"{agent_b}","allocation_mode":"automatic","allocation_weight":70}]}'

Response

200 OK

{"pool":{"max_cost_usd":100,"policy_version":3},"agents":[{"name":"Agent A","allocation":{"allocation_mode":"fixed","allocation_percent":30}},{"name":"Agent B","allocation":{"allocation_mode":"automatic","allocation_weight":70}}]}

GET/api/v1/agents/{agent_id}/budget-plan

Get Agent Budget Plan

Return the optional cross-configuration agent cap, default per-conversation guardrails, the selected configuration allocation, current usage, and the complete connected principal roster (members, agents, API keys, and automations) with draft and frozen shares. New agents default to $5 estimated cost, 250,000 tokens, and 60 minutes per conversation. Agent tool: agents.budgets.get_agent_plan.

Bearer token required. Permission: agents:agents:view.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`llm_config_id`*	UUID	Usable configuration whose principal allocation is projected

curl "https://platform.ergondata.ai/api/v1/agents/{agent_id}/budget-plan?company_id={company_id}&llm_config_id={config_id}" -H "Authorization: Bearer {token}"

Response

200 OK

{"agent_id":"...","llm_config_id":"...","agent_budget":{"scope_type":"agent_total","max_cost_usd":250,"conversation_max_cost_usd":5,"conversation_max_tokens":50000,"conversation_max_session_minutes":30},"config_allocation":{"scope_type":"agent","allocation_mode":"automatic"},"principals":[{"principal_id":"...","principal_type":"automation","name":"Customer follow-up","resolved_percent":25}]}

PUT/api/v1/agents/{agent_id}/budget-plan

Update Agent Budget Plan

Atomically replace the optional recurring agent-wide cap, the per-conversation limits, and the complete principal spend-allocation policy for one configuration. Per-configuration allocations are managed exclusively through the configuration budget plan and are read-only here. Active spend snapshots remain frozen until the reset boundary; conversation limits apply to every conversation immediately. Returns 409 when the IAM roster changed. Agent tool: agents.budgets.update_agent_plan.

Bearer token required. Permission: agents:agents:manage.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

Request Body

Name	Type	Description
`llm_config_id`*	UUID	Usable configuration being allocated
`max_cost_usd`	number \| null	Agent-wide USD cap across every configuration. Maximum 10,000.
`max_tokens`	integer \| null	Agent-wide token cap across every configuration. Maximum 100,000,000.
`window`*	daily \| weekly \| monthly	Recurring reset window for the agent-wide cost and token caps
`conversation_max_cost_usd`	number \| null	Best-effort estimated cost limit for each conversation session. Defaults to 5; maximum 100.
`conversation_max_tokens`	integer \| null	Exact combined token limit for each conversation session. Defaults to 250,000; maximum 1,000,000.
`conversation_max_session_minutes`	integer \| null	Maximum wall-clock age of each conversation session, in minutes. Defaults to 60; maximum 1,440.
`principal_allocations`*	array	One spend-share row for every authorized IAM principal: principal_id, principal_type, allocation_mode, and allocation_percent or allocation_weight.

curl -X PUT "https://platform.ergondata.ai/api/v1/agents/{agent_id}/budget-plan?company_id={company_id}" \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"llm_config_id":"{config_id}","max_cost_usd":250,"window":"monthly","conversation_max_cost_usd":5,"conversation_max_tokens":50000,"conversation_max_session_minutes":30,"principal_allocations":[{"principal_id":"{automation_principal}","principal_type":"automation","allocation_mode":"fixed","allocation_percent":25},{"principal_id":"{member_principal}","principal_type":"member","allocation_mode":"automatic","allocation_weight":75}]}'

Response

200 OK

{"agent_id":"...","agent_budget":{"scope_type":"agent_total","max_cost_usd":250,"conversation_max_cost_usd":5},"principals":[{"principal_type":"automation","resolved_percent":25}]}

GET/api/v1/agents/llm-configs/{llm_config_id}/usage

Get LLM Configuration Usage

Return platform-derived provider-call cost and tokens for a configuration, with model, source, agent, principal, automation, and daily breakdowns. Agent tool: agents.usage.get_llm_config.

Bearer token required. Permission: agents:llm-configs:view.

Path Parameters

Name	Type	Description
`llm_config_id`*	UUID	LLM configuration ID

Query Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`days`	integer	Reporting lookback, 1–366 days (default 30)

curl "https://platform.ergondata.ai/api/v1/agents/llm-configs/{llm_config_id}/usage?company_id={company_id}&days=30" -H "Authorization: Bearer {token}"

Response

200 OK

{"totals":{"total_tokens":420000,"estimated_cost_usd":12.5,"provider_calls":42},"by_model":[{"key":"claude-sonnet","total_tokens":420000,"estimated_cost_usd":12.5}],"time_series":[]}

GET/api/v1/agents/{agent_id}/usage

Get Agent Usage

Return usage across every configuration, conversation, principal, and automation involving an agent. Agent tool: agents.usage.get_agent.

Bearer token required. Permission: agents:agents:view.

Path Parameters

Name	Type	Description
`agent_id`*	UUID	Agent ID

Query Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID
`days`	integer	Reporting lookback, 1–366 days (default 30)

curl "https://platform.ergondata.ai/api/v1/agents/{agent_id}/usage?company_id={company_id}" -H "Authorization: Bearer {token}"

Response

200 OK

{"totals":{"total_tokens":900000,"estimated_cost_usd":24.1,"provider_calls":80},"by_configuration":[],"by_automation":[]}

GET/api/v1/agents/conversations/{conversation_id}/usage

Get Conversation Usage

Return settled provider-call usage attributed to one conversation. The same conversation-level authorization used by Conversations is checked before the usage ledger, including for conversations with no usage. Agent tool: agents.usage.get_conversation.

Bearer token required with access to the conversation.

Path Parameters

Name	Type	Description
`conversation_id`*	UUID	Conversation ID

Query Parameters

Name	Type	Description
`company_id`*	UUID	Organization ID

curl "https://platform.ergondata.ai/api/v1/agents/conversations/{conversation_id}/usage?company_id={company_id}" -H "Authorization: Bearer {token}"

Response

200 OK

{"totals":{"total_tokens":18000,"estimated_cost_usd":0.42,"provider_calls":3},"by_model":[],"by_source":[]}

Activity

Browse the activity log for agent-related events — invocations, responses, errors, tool calls, and more.

GET/api/v1/agents/event-types

List Event Types

Get all available agent event types for filtering.

Bearer token required.

curl https://platform.ergondata.ai/api/v1/agents/event-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  { "slug": "agent.invoked", "name": "Agent Invoked", "description": "An agent was invoked" },
  { "slug": "agent.response", "name": "Agent Response", "description": "Agent generated a response" },
  { "slug": "agent.error", "name": "Agent Error", "description": "Agent encountered an error" }
]

GET/api/v1/agents/companies/{company_id}/activity

List Activity

List activity events for an organization with filtering and pagination.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Query Parameters

Name	Type	Description
`event_type`	string	Filter by event type slug
`agent_id`	string	Filter by agent ID
`conversation_id`	string	Filter by conversation ID
`correlation_id`	string	Filter by correlation ID
`search`	string	Full-text search
`date_from`	datetime	Start date filter
`date_to`	datetime	End date filter
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-100)Default: `50`

Response Fields

Name	Type	Description
`items`*	array	Array of activity events (id, event_type, agent_id, conversation_id, correlation_id, actor_type, payload, created_at)
`total`*	integer	Total event count
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/activity?event_type=agent.invoked&limit=20" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "evt-001",
      "event_type": "agent.invoked",
      "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
      "conversation_id": "conv-1234",
      "correlation_id": "corr-001",
      "actor_type": "user",
      "payload": { "source_type": "api" },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

GET/api/v1/agents/companies/{company_id}/activity/{event_id}

Get Activity Event

Retrieve a single activity event by ID.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID
`event_id`*	string (UUID)	Event ID

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/activity/{event_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "evt-001",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "event_type": "agent.invoked",
  "agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
  "conversation_id": "conv-1234",
  "correlation_id": "corr-001",
  "actor_type": "user",
  "actor_id": "user-uuid",
  "payload": { "source_type": "api" },
  "created_at": "2025-01-15T10:30:00Z"
}

Access Management

Manage fine-grained access for Agent Hub. Organization routes manage border grants; per-agent, per-skill, per-LLM-config, and per-provider-key routes delegate inside concrete federated zones. Zones also expose connection requests and connections -- agents additionally surface their outbound connections (where the agent is the one wired into another zone). Batch ToolDefs are agents.agent_access.create_grants_batch, agents.skill_access.create_grants_batch, agents.llm_config_access.create_grants_batch, and agents.provider_key_access.create_grants_batch. LLM-config and provider-key access routes use the agents.{llm_config|provider_key}_access.{list_eligible|list_resource_types|list_grants|create_grant|delete_grant|list_connection_requests|approve_connection_request|reject_connection_request|list_connections|revoke_connection} ToolDef families.

GET/api/v1/agents/companies/{company_id}/access/eligible

List Eligible Principals

List principals eligible to receive Agent Hub grants at the org border.

Bearer token with agents:permissions:manage on org/{company_id}.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Response Fields

Name	Type	Description
`[]`*	array	Array of eligible principals
`principal_type`*	string	Principal kind (member, api_key, agent, role, ...)
`principal_id`*	string	Principal ID
`label`*	string	Human-readable label

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "label": "Jane Doe"
  },
  {
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "label": "Researcher"
  },
  {
    "principal_type": "api_key",
    "principal_id": "key-7777-8888-9999-aaaabbbbcccc",
    "label": "CI Bot"
  }
]

GET/api/v1/agents/companies/{company_id}/access/resource-types

List Resource Types

List the resource types and permissions available for the agents service.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Response Fields

Name	Type	Description
`resource_types`*	array	Hierarchical tree of resource types (id, name, slug, parent_id, children)
`permissions`*	array	Flat list of permission options (id, name, friendly_name, description, resource_type_id, parent_resource_type_slug, scope_anchor, display_order)

curl https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    {
      "id": "rt-100",
      "name": "Agent",
      "slug": "agent",
      "parent_id": null,
      "children": []
    },
    {
      "id": "rt-101",
      "name": "Provider Key",
      "slug": "provider_key",
      "parent_id": null,
      "children": []
    }
  ],
  "permissions": [
    {
      "id": "perm-100",
      "name": "agents:agents:view",
      "friendly_name": "View Agent",
      "description": "View an agent",
      "resource_type_id": "rt-100",
      "parent_resource_type_slug": null,
      "scope_anchor": "instance",
      "display_order": 0
    }
  ]
}

GET/api/v1/agents/companies/{company_id}/access/grants

List Access Grants

List all access grants for the organization border.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-500)Default: `100`

Response Fields

Name	Type	Description
`items`*	array	Array of grant entries (id, principal_type, principal_id, principal_label, permission_id, permission_name, resource, effect, granted_at)
`total`*	integer	Total grant count
`page`*	integer	Current page
`limit`*	integer	Page size

curl "https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-a1b2c3d4",
      "principal_type": "member",
      "principal_id": "mem-1234-5678-90ab-cdef12345678",
      "principal_label": "Jane Doe",
      "permission_id": "perm-100",
      "permission_name": "agents:agents:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
      "effect": "allow",
      "granted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/agents/companies/{company_id}/access/grants

Create Access Grant

Create a new access grant for a principal at the org border.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`principal_type`*	string	One of member, api_key, agent, or role
`principal_id`*	string	Principal ID
`permission_id`*	string	Permission ID to grant
`resource`	string \| null	Resource target (defaults to the org scope)
`effect`	string	Grant effect (allow or deny)Default: `allow`

Response Fields

Name	Type	Description
`id`*	string	Grant ID
`permission_id`*	string	Granted permission ID
`name`*	string	Permission slug (e.g. agents:agents:view)
`resource`*	string	Resource target the grant applies to
`effect`*	string	allow or deny
`is_system`*	boolean	Whether the grant came from a system-managed role
`granted_at`*	datetime	Grant creation timestamp

curl -X POST https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "permission_id": "perm-100"
  }'

Response

201 Created

{
  "id": "grant-a1b2c3d4",
  "permission_id": "perm-100",
  "name": "agents:agents:view",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2025-01-15T10:30:00Z"
}

POST/api/v1/agents/access/agents/grants/batch

Create Agent Access Grants Batch

Create grants across agent roots in one ordered, partial-success operation. Group one subject with resources and permission UUIDs; the Cartesian expansion across all operations may contain at most 200 grants. Whole-request retries are idempotent. ToolDef slug: agents.agent_access.create_grants_batch.

Bearer token with agents:permissions:manage on every target agent zone.

Request Body

Name	Type	Description
`operations`*	array	Grouped BatchGrantOperation values

Response Fields

Name	Type	Description
`results`*	array	Ordered created, already_exists, or failed outcomes
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/agents/access/agents/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [{
      "client_ref": "reviewers",
      "principal_type": "member",
      "principal_id": "{member_principal_id}",
      "resources": ["org/{company_id}/agent/{agent_id}"],
      "permission_ids": ["{agents_view_permission_id}", "{agents_use_permission_id}"],
      "effect": "allow"
    }]
  }'

Response

200 OK

{
  "results": [{
    "index": 0,
    "client_ref": "reviewers",
    "status": "created",
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "permission_id": "perm-100",
    "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
    "effect": "allow",
    "grant": {
      "id": "grant-b2c3d4e5",
      "permission_id": "perm-100",
      "name": "agents:agents:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-07-15T16:30:00Z"
    },
    "error_status": null,
    "error_detail": null,
    "side_effect_error_status": null,
    "side_effect_error_detail": null
  }],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

POST/api/v1/agents/access/skills/grants/batch

Create Skill Access Grants Batch

Apply the BatchCreateGrantsRequest contract across skill roots (maximum 200 expanded grants), returning an ordered BatchCreateGrantsResponse with independent, idempotent outcomes. ToolDef slug: agents.skill_access.create_grants_batch.

Bearer token with agents:permissions:skills:manage on every target skill zone.

Request Body

Name	Type	Description
`operations`*	array	Grouped operations whose Cartesian expansion is limited to 200 grants

Response Fields

Name	Type	Description
`results`*	array	Ordered result for every expanded grant
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/agents/access/skills/grants/batch \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"agent","principal_id":"{agent_principal_id}","resources":["org/{company_id}/skill/{skill_id}"],"permission_ids":["{skills_view_permission_id}"],"effect":"allow"}]}'

Response

200 OK

{"results": [], "summary": {"created": 0, "already_exists": 0, "failed": 0}}

POST/api/v1/agents/access/llm-configs/grants/batch

Create LLM Config Access Grants Batch

Apply the BatchCreateGrantsRequest contract across LLM config roots (maximum 200 expanded grants), returning an ordered BatchCreateGrantsResponse with independent, idempotent outcomes. ToolDef slug: agents.llm_config_access.create_grants_batch.

Bearer token with agents:permissions:llm-configs:manage on every target LLM config zone.

Request Body

Name	Type	Description
`operations`*	array	Grouped operations whose Cartesian expansion is limited to 200 grants

Response Fields

Name	Type	Description
`results`*	array	Ordered result for every expanded grant
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/agents/access/llm-configs/grants/batch \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"agent","principal_id":"{agent_principal_id}","resources":["org/{company_id}/llm-config/{config_id}"],"permission_ids":["{llm_configs_use_permission_id}"],"effect":"allow"}]}'

Response

200 OK

{"results": [], "summary": {"created": 0, "already_exists": 0, "failed": 0}}

POST/api/v1/agents/access/provider-keys/grants/batch

Create Provider Key Access Grants Batch

Apply the BatchCreateGrantsRequest contract across provider-key roots (maximum 200 expanded grants), returning an ordered BatchCreateGrantsResponse with independent, idempotent outcomes. ToolDef slug: agents.provider_key_access.create_grants_batch.

Bearer token with agents:permissions:provider-keys:manage on every target provider-key zone.

Request Body

Name	Type	Description
`operations`*	array	Grouped operations whose Cartesian expansion is limited to 200 grants

Response Fields

Name	Type	Description
`results`*	array	Ordered result for every expanded grant
`summary`*	object	created, already_exists, and failed counts

curl -X POST https://platform.ergondata.ai/api/v1/agents/access/provider-keys/grants/batch \
  -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"agent","principal_id":"{agent_principal_id}","resources":["org/{company_id}/provider-key/{key_id}"],"permission_ids":["{provider_keys_use_permission_id}"],"effect":"allow"}]}'

Response

200 OK

{"results": [], "summary": {"created": 0, "already_exists": 0, "failed": 0}}

DELETE/api/v1/agents/companies/{company_id}/access/grants/{grant_id}

Delete Access Grant

Revoke an org-border access grant.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID
`grant_id`*	string (UUID)	Grant ID to revoke

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/companies/{company_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/agents/{agent_id}/access/eligible

List Agent Eligible Principals

List principals eligible to receive grants inside a specific agent zone.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "label": "Jane Doe"
  }
]

GET/api/v1/agents/agents/{agent_id}/access/resource-types

List Agent Resource Types

List the resource types and permissions delegable inside an agent zone.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-100", "name": "Agent", "slug": "agent", "parent_id": null, "children": [] }
  ],
  "permissions": [
    {
      "id": "perm-100",
      "name": "agents:agents:use",
      "friendly_name": "Use Agent",
      "description": "Invoke an agent",
      "resource_type_id": "rt-100",
      "parent_resource_type_slug": null,
      "scope_anchor": "instance",
      "display_order": 0
    }
  ]
}

GET/api/v1/agents/agents/{agent_id}/access/grants

List Agent Access Grants

List access grants delegated inside a specific agent zone.

Bearer token required.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-500)Default: `100`

curl "https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-b2c3d4e5",
      "principal_type": "member",
      "principal_id": "mem-1234-5678-90ab-cdef12345678",
      "principal_label": "Jane Doe",
      "permission_id": "perm-100",
      "permission_name": "agents:agents:use",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
      "effect": "allow",
      "granted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/agents/agents/{agent_id}/access/grants

Create Agent Access Grant

Grant a principal a permission inside a specific agent zone.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Request Body

Name	Type	Description
`principal_type`*	string	One of member, api_key, agent, or role
`principal_id`*	string	Principal ID
`permission_id`*	string	Permission ID to grant
`resource`	string \| null	Resource target (defaults to the agent zone)
`effect`	string	Grant effect (allow or deny)Default: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "permission_id": "perm-100"
  }'

Response

201 Created

{
  "id": "grant-b2c3d4e5",
  "permission_id": "perm-100",
  "name": "agents:agents:use",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2025-01-15T10:30:00Z"
}

DELETE/api/v1/agents/agents/{agent_id}/access/grants/{grant_id}

Delete Agent Access Grant

Revoke an access grant inside a specific agent zone.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/agents/{agent_id}/access/connection-requests

List Agent Connection Requests

List connection requests where another principal asks to connect to this agent zone (the approver-side inbox).

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request statusDefault: `pending`

curl "https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "creq-001",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
    "status": "pending",
    "requested_permissions": ["agents:agents:use"],
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "message": "Researcher needs to call the support agent",
    "connection_id": null,
    "decided_at": null,
    "decided_by": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/approve

Approve Agent Connection Request

Approve a pending connection request, optionally granting the requested (or overridden) permissions.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to grant access on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	string[] \| null	Permissions to grant (overrides the requested set)

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true}'

Response

200 OK

{
  "id": "creq-001",
  "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
  "target_service": "agents",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
  "status": "approved",
  "requested_permissions": ["agents:agents:use"],
  "requested_by": "mem-1234-5678-90ab-cdef12345678",
  "message": "Researcher needs to call the support agent",
  "connection_id": "conn-001",
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

POST/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/reject

Reject Agent Connection Request

Reject a pending connection request, optionally with a reason.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Reason for rejection

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not needed"}'

Response

200 OK

{
  "id": "creq-001",
  "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
  "target_service": "agents",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
  "status": "rejected",
  "requested_permissions": ["agents:agents:use"],
  "requested_by": "mem-1234-5678-90ab-cdef12345678",
  "message": "Researcher needs to call the support agent",
  "connection_id": null,
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/agents/agents/{agent_id}/access/connections

List Agent Inbound Connections

List active connections where another principal is wired into this agent zone, with provenance.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "conn-001",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "principal_type": "agent",
    "principal_label": "Researcher",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/agent/abcd1234-ef56-7890-abcd-ef1234567890",
    "label": "Researcher -> Support Bot",
    "created_by": "mem-9999-8888-77ab-cdef12345678",
    "created_by_label": "Admin",
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "requested_by_label": "Jane Doe",
    "system_managed_by": null,
    "created_at": "2025-01-16T09:00:00Z"
  }
]

DELETE/api/v1/agents/agents/{agent_id}/access/connections/{connection_id}

Revoke Agent Inbound Connection

Sever an inbound connection to this agent, cutting the principal's access.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/skills/{skill_id}/access/eligible

List Skill Eligible Principals

List principals eligible to receive grants inside a specific skill zone.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

curl https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "label": "Researcher"
  }
]

GET/api/v1/agents/skills/{skill_id}/access/resource-types

List Skill Resource Types

List the resource types and permissions delegable inside a skill zone.

Bearer token required.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

curl https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-200", "name": "Skill", "slug": "skill", "parent_id": null, "children": [] }
  ],
  "permissions": [
    {
      "id": "perm-200",
      "name": "agents:skills:view",
      "friendly_name": "View Skill",
      "description": "View a skill",
      "resource_type_id": "rt-200",
      "parent_resource_type_slug": null,
      "scope_anchor": "instance",
      "display_order": 0
    }
  ]
}

GET/api/v1/agents/skills/{skill_id}/access/grants

List Skill Access Grants

List access grants delegated inside a specific skill zone.

Bearer token required.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-500)Default: `100`

curl "https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-c3d4e5f6",
      "principal_type": "agent",
      "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
      "principal_label": "Researcher",
      "permission_id": "perm-200",
      "permission_name": "agents:skills:view",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/skill/5ki11111-2222-3333-4444-555566667777",
      "effect": "allow",
      "granted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/agents/skills/{skill_id}/access/grants

Create Skill Access Grant

Grant a principal a permission inside a specific skill zone (e.g. grant an agent agents:skills:view so it can use the skill). The principal must already be connected to the skill — connect it first via the skill's Connections (invite/request, which can carry the grant); IAM rejects a grant to an unconnected principal.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

Request Body

Name	Type	Description
`principal_type`*	string	One of member, api_key, agent, or role
`principal_id`*	string	Principal ID
`permission_id`*	string	Permission ID to grant
`resource`	string \| null	Resource target (defaults to the skill zone)
`effect`	string	Grant effect (allow or deny)Default: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "permission_id": "perm-200"
  }'

Response

201 Created

{
  "id": "grant-c3d4e5f6",
  "permission_id": "perm-200",
  "name": "agents:skills:view",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/skill/5ki11111-2222-3333-4444-555566667777",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2025-01-15T10:30:00Z"
}

DELETE/api/v1/agents/skills/{skill_id}/access/grants/{grant_id}

Delete Skill Access Grant

Revoke an access grant inside a specific skill zone.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/skills/{skill_id}/access/connection-requests

List Skill Connection Requests

List inbound connection requests for this skill zone — principals (e.g. agents) asking to be wired into the skill so they can be granted access.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

Query Parameters

Name	Type	Description
`status`	string	Filter by status (pending, approved, rejected)Default: `pending`

curl "https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "creq-001",
    "requester_principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "requester_label": "Researcher",
    "status": "pending",
    "requested_permission": "agents:skills:view",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/approve

Approve Skill Connection Request

Approve an inbound connection request, wiring the requester into the skill zone (optionally granting agents:skills:view at the same time).

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID
`request_id`*	string (UUID)	Connection request ID

curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "conn-001",
  "subject_principal_id": "agt-abcd-ef12-3456-7890abcdef12",
  "status": "active",
  "created_at": "2025-01-15T10:31:00Z"
}

POST/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/reject

Reject Skill Connection Request

Reject an inbound connection request for this skill zone.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID
`request_id`*	string (UUID)	Connection request ID

curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/skills/{skill_id}/access/connections

List Skill Connections

List principals currently connected to this skill zone (eligible to hold grants). A principal must be connected before it can be granted agents:skills:view.

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID

curl https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "conn-001",
    "subject_principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "subject_label": "Researcher",
    "status": "active",
    "created_at": "2025-01-15T10:31:00Z"
  }
]

DELETE/api/v1/agents/skills/{skill_id}/access/connections/{connection_id}

Revoke Skill Connection

Revoke a connection, removing the principal from the skill zone (its grants there are revoked with it).

Bearer token with agents:permissions:skills:manage on the skill zone.

Path Parameters

Name	Type	Description
`skill_id`*	string (UUID)	Skill ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/llm-configs/{config_id}/access/eligible

List Config Eligible Principals

List principals eligible to receive grants inside a specific LLM config zone (e.g. agents you can grant agents:llm-configs:use to).

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

curl https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "label": "Support Bot"
  }
]

GET/api/v1/agents/llm-configs/{config_id}/access/resource-types

List Config Resource Types

List the permissions delegable inside an LLM config zone (view, use, manage, delete, activity:view).

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

curl https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-200", "name": "LLM Config", "slug": "llm-config", "parent_id": null, "children": [] }
  ],
  "permissions": [
    {
      "id": "perm-200",
      "name": "agents:llm-configs:use",
      "friendly_name": "Use LLM Config",
      "friendly_name_singular": "Use LLM Config",
      "description": "Bind this config to an agent / consume it at runtime",
      "resource_type_id": "rt-200",
      "parent_resource_type_slug": null,
      "scope_anchor": "instance",
      "display_order": 0
    }
  ]
}

GET/api/v1/agents/llm-configs/{config_id}/access/grants

List Config Access Grants

List access grants delegated inside a specific LLM config zone.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-500)Default: `100`

curl "https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-d4e5f6a7",
      "principal_type": "agent",
      "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
      "principal_label": "Support Bot",
      "permission_id": "perm-200",
      "permission_name": "agents:llm-configs:use",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "effect": "allow",
      "granted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/agents/llm-configs/{config_id}/access/grants

Create Config Access Grant

Grant a principal a permission inside an LLM config zone (e.g. agents:llm-configs:use so an agent can run this config). The principal must already be connected to the config — connect it first via the config's Connections (invite/request, which can carry the grant); IAM rejects a grant to an unconnected principal.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

Request Body

Name	Type	Description
`principal_type`*	string	One of member, api_key, agent, or role
`principal_id`*	string	Principal ID
`permission_id`*	string	Permission ID to grant (must be in the config zone's grantable set)
`resource`	string \| null	Resource target (defaults to the config zone)
`effect`	string	Grant effect (allow or deny)Default: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "agent",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "permission_id": "perm-200"
  }'

Response

201 Created

{
  "id": "grant-d4e5f6a7",
  "permission_id": "perm-200",
  "name": "agents:llm-configs:use",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2025-01-15T10:30:00Z"
}

DELETE/api/v1/agents/llm-configs/{config_id}/access/grants/{grant_id}

Delete Config Access Grant

Revoke an access grant inside a specific LLM config zone.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/llm-configs/{config_id}/access/connection-requests

List Config Connection Requests

List connection requests where a principal asks to connect to this config zone (the approver-side inbox).

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request statusDefault: `pending`

curl "https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "creq-100",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "status": "pending",
    "requested_permissions": ["agents:llm-configs:use"],
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "message": "Support Bot needs to use the Default config",
    "connection_id": null,
    "decided_at": null,
    "decided_by": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/approve

Approve Config Connection Request

Approve a pending connection request, optionally granting the requested (or overridden) permissions on the config.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to grant access on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	string[] \| null	Permissions to grant (overrides the requested set)

curl -X POST https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true}'

Response

200 OK

{
  "id": "creq-100",
  "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
  "target_service": "agents",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "approved",
  "requested_permissions": ["agents:llm-configs:use"],
  "requested_by": "mem-1234-5678-90ab-cdef12345678",
  "message": "Support Bot needs to use the Default config",
  "connection_id": "conn-100",
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

POST/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/reject

Reject Config Connection Request

Reject a pending connection request, optionally with a reason.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Reason for rejection

curl -X POST https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not needed"}'

Response

200 OK

{
  "id": "creq-100",
  "status": "rejected",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "connection_id": null,
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/agents/llm-configs/{config_id}/access/connections

List Config Connections

List active connections where a principal (e.g. an agent) is wired into this config zone, with provenance.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID

curl https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "conn-100",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "principal_type": "agent",
    "principal_label": "Support Bot",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "label": "Support Bot -> Default config",
    "created_by": "mem-9999-8888-77ab-cdef12345678",
    "created_by_label": "Admin",
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "requested_by_label": "Jane Doe",
    "system_managed_by": null,
    "created_at": "2025-01-16T09:00:00Z"
  }
]

DELETE/api/v1/agents/llm-configs/{config_id}/access/connections/{connection_id}

Revoke Config Connection

Sever a connection into this config, cutting the principal's access to use it.

Bearer token with agents:permissions:llm-configs:manage on the config zone.

Path Parameters

Name	Type	Description
`config_id`*	string (UUID)	LLM config ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/provider-keys/{key_id}/access/eligible

List Provider Key Eligible Principals

List principals eligible to receive grants inside a specific provider key zone.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

curl https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "label": "Jane Doe"
  }
]

GET/api/v1/agents/provider-keys/{key_id}/access/resource-types

List Provider Key Resource Types

List the permissions delegable inside a provider key zone (view, use, manage, delete, activity:view).

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

curl https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    { "id": "rt-300", "name": "Provider Key", "slug": "provider-key", "parent_id": null, "children": [] }
  ],
  "permissions": [
    {
      "id": "perm-300",
      "name": "agents:provider-keys:use",
      "friendly_name": "Use Provider Key",
      "friendly_name_singular": "Use Provider Key",
      "description": "Wire this key into an LLM config",
      "resource_type_id": "rt-300",
      "parent_resource_type_slug": null,
      "scope_anchor": "instance",
      "display_order": 0
    }
  ]
}

GET/api/v1/agents/provider-keys/{key_id}/access/grants

List Provider Key Access Grants

List access grants delegated inside a specific provider key zone.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Results per page (1-500)Default: `100`

curl "https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "grant-e5f6a7b8",
      "principal_type": "member",
      "principal_id": "mem-1234-5678-90ab-cdef12345678",
      "principal_label": "Jane Doe",
      "permission_id": "perm-300",
      "permission_name": "agents:provider-keys:use",
      "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "effect": "allow",
      "granted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/agents/provider-keys/{key_id}/access/grants

Create Provider Key Access Grant

Grant a principal a permission inside a provider key zone (e.g. agents:provider-keys:use so a member can wire the key into their LLM configs).

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

Request Body

Name	Type	Description
`principal_type`*	string	One of member, api_key, agent, or role
`principal_id`*	string	Principal ID
`permission_id`*	string	Permission ID to grant (must be in the key zone's grantable set)
`resource`	string \| null	Resource target (defaults to the key zone)
`effect`	string	Grant effect (allow or deny)Default: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "permission_id": "perm-300"
  }'

Response

201 Created

{
  "id": "grant-e5f6a7b8",
  "permission_id": "perm-300",
  "name": "agents:provider-keys:use",
  "resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "effect": "allow",
  "is_system": false,
  "granted_at": "2025-01-15T10:30:00Z"
}

DELETE/api/v1/agents/provider-keys/{key_id}/access/grants/{grant_id}

Delete Provider Key Access Grant

Revoke an access grant inside a specific provider key zone.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/provider-keys/{key_id}/access/connection-requests

List Provider Key Connection Requests

List connection requests where a principal asks to connect to this provider key zone (the approver-side inbox).

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request statusDefault: `pending`

curl "https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "creq-200",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending",
    "requested_permissions": ["agents:provider-keys:use"],
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "message": "Need to use the OpenAI key in my configs",
    "connection_id": null,
    "decided_at": null,
    "decided_by": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/approve

Approve Provider Key Connection Request

Approve a pending connection request, optionally granting the requested (or overridden) permissions on the key.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to grant access on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	string[] \| null	Permissions to grant (overrides the requested set)

curl -X POST https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true}'

Response

200 OK

{
  "id": "creq-200",
  "principal_id": "mem-1234-5678-90ab-cdef12345678",
  "target_service": "agents",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "approved",
  "requested_permissions": ["agents:provider-keys:use"],
  "requested_by": "mem-1234-5678-90ab-cdef12345678",
  "connection_id": "conn-200",
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

POST/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/reject

Reject Provider Key Connection Request

Reject a pending connection request, optionally with a reason.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Reason for rejection

curl -X POST https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not needed"}'

Response

200 OK

{
  "id": "creq-200",
  "status": "rejected",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "connection_id": null,
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-9999-8888-77ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/v1/agents/provider-keys/{key_id}/access/connections

List Provider Key Connections

List active connections where a principal is wired into this provider key zone, with provenance.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID

curl https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "conn-200",
    "principal_id": "mem-1234-5678-90ab-cdef12345678",
    "principal_type": "member",
    "principal_label": "Jane Doe",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/provider-key/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Jane Doe -> OpenAI Production",
    "created_by": "mem-9999-8888-77ab-cdef12345678",
    "created_by_label": "Admin",
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "requested_by_label": "Jane Doe",
    "system_managed_by": null,
    "created_at": "2025-01-16T09:00:00Z"
  }
]

DELETE/api/v1/agents/provider-keys/{key_id}/access/connections/{connection_id}

Revoke Provider Key Connection

Sever a connection into this provider key, cutting the principal's access to use it.

Bearer token with agents:permissions:provider-keys:manage on the key zone.

Path Parameters

Name	Type	Description
`key_id`*	string (UUID)	Provider key ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/provider-keys/{key_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/agents/agents/{agent_id}/connections

List Agent Outbound Connections

List connections where THIS agent is the subject wired into another zone (e.g. an LLM config or another agent it can use) -- the agent's-eye view of what it is connected to, the mirror of the inbound list under /access/connections.

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID

curl https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "conn-100",
    "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
    "principal_type": "agent",
    "principal_label": "Support Bot",
    "target_service": "agents",
    "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "label": "Support Bot -> Default config",
    "created_by": "mem-9999-8888-77ab-cdef12345678",
    "created_by_label": "Admin",
    "requested_by": "mem-1234-5678-90ab-cdef12345678",
    "requested_by_label": "Jane Doe",
    "system_managed_by": null,
    "created_at": "2025-01-16T09:00:00Z"
  }
]

DELETE/api/v1/agents/agents/{agent_id}/connections/{connection_id}

Revoke Agent Outbound Connection

Sever one of this agent's outbound connections, giving up the agent's access to that target zone (e.g. detach it from an LLM config).

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/agents/agents/{agent_id}/connection-requests/{request_id}/withdraw

Withdraw Agent Connection Request

Withdraw a pending connection request this agent issued toward another zone (the subject-side counterpart to approve/reject).

Bearer token with agents:permissions:manage on the agent zone.

Path Parameters

Name	Type	Description
`agent_id`*	string (UUID)	Agent ID
`request_id`*	string (UUID)	Connection request ID

curl -X POST https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/connection-requests/{request_id}/withdraw \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "creq-100",
  "principal_id": "agt-abcd-ef12-3456-7890abcdef12",
  "target_service": "agents",
  "target_resource": "org/c0ffee00-cafe-babe-dead-beefcafebabe/llm-config/b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "status": "withdrawn",
  "requested_permissions": ["agents:llm-configs:use"],
  "requested_by": "mem-1234-5678-90ab-cdef12345678",
  "connection_id": null,
  "decided_at": "2025-01-16T09:00:00Z",
  "decided_by": "mem-1234-5678-90ab-cdef12345678",
  "created_at": "2025-01-15T10:30:00Z"
}