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. Bots join inbound work as workflow assignment-group members, not as address auto-reply routes. Conversations and inbound attachment materialization are managed through the separate Conversations service.
/api/v1/agentsAutomation triggers: view every Agent Hub event, payload field, and predicate.
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.
/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, manage_skills, view_automations, manage_automations, manage_budgets, 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,
"manage_skills": true,
"view_automations": true,
"manage_automations": true,
"manage_budgets": true,
"view_activity": true,
"manage_security": false
},
"config": null
}/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,
"manage_skills": true,
"view_automations": true,
"manage_automations": true,
"manage_budgets": true,
"view_activity": true,
"manage_security": false
},
"config": null
}/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/api/v1/agents/{agent_id}/avatarUpload 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 "file=@avatar.png"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,
"manage_skills": true,
"view_automations": true,
"manage_automations": true,
"manage_budgets": true,
"view_activity": true,
"manage_security": false
},
"config": null
}/api/v1/agents/{agent_id}/avatarDelete 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,
"manage_skills": true,
"view_automations": true,
"manage_automations": true,
"manage_budgets": 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.
/api/v1/agents/companies/{company_id}/provider-keysCreate a Provider Key
Register a new LLM provider API key for the organization.
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": "<provider-api-key>"
}'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
}/api/v1/agents/companies/{company_id}/provider-keysList 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
}
]/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
}/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
}/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 ContentLLM Configs
LLM configurations pair a pool of provider keys with a set of catalog models that agents can run.
/api/v1/agents/llm-providersList 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,
"reasoning_efforts": ["none", "low", "medium", "high", "xhigh"],
"default_reasoning_effort": "low",
"thinking": {
"mode": "effort",
"can_disable": true,
"provider_default_effort": "medium",
"display": "summarized"
},
"sampling_parameters": false
},
"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-5-5",
"name": "Claude Opus 5.5",
"description": "For long-running agentic coding and knowledge work.",
"tag": "Flagship",
"context_window": 1000000,
"max_output_tokens": 128000,
"input_price_per_mtok": 4.0,
"output_price_per_mtok": 20.0,
"currency": "USD",
"capabilities": {
"tools": true,
"structured_output": true,
"reasoning": true,
"reasoning_efforts": ["low", "medium", "high", "xhigh", "max"],
"thinking": {
"mode": "adaptive",
"can_disable": false,
"between_tools": false,
"provider_default_effort": "medium",
"display": "summarized"
},
"forced_tool_choice": false,
"sampling_parameters": false
},
"status": "available"
}
]
},
{
"id": "66666666-6666-6666-6666-666666666666",
"slug": "gemini",
"name": "Google Gemini",
"status": "coming_soon",
"pricing_url": "https://ai.google.dev/pricing",
"models": []
}
]/api/v1/agents/companies/{company_id}/llm-configsCreate 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 | Deprecated. Accepted and ignored: no temperature is sent to the provider. |
max_tokens | integer | null | Deprecated. Accepted and ignored: output tokens per model call are always Auto (the model's catalog ceiling, clamped by budgets and context headroom). |
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 | Deprecated. Always null. |
max_tokens* | integer | null | Deprecated. Always null. Output tokens per model call are always Auto. |
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" }
]
}'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": null,
"max_tokens": null,
"created_at": "2025-01-15T10:30:00Z"
}/api/v1/agents/companies/{company_id}/llm-configsList 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"
}
]/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": null,
"max_tokens": null,
"created_at": "2025-01-15T10:30:00Z"
}/api/v1/agents/llm-configs/{config_id}Update LLM Config
Update an LLM configuration's name, key pool, or model set.
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 | Deprecated. Accepted and ignored: no temperature is sent to the provider. |
max_tokens | integer | null | Deprecated. Accepted and ignored: output tokens per model call are always Auto (the model's catalog ceiling, clamped by budgets and context headroom). |
curl -X PATCH https://platform.ergondata.ai/api/v1/agents/llm-configs/{config_id} \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"name": "Production"}'Response
200 OK{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
"name": "Production",
"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": null,
"max_tokens": null,
"created_at": "2025-01-15T10:30:00Z"
}/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/api/v1/agents/{agent_id}/usable-modelsList 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_route": {
"llm_config_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"model_slug": "gpt-5.5"
},
"default_model_slug": "gpt-5.5",
"primary_llm_config_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}/api/v1/agents/{agent_id}/usable-configsList 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-5-5", "name": "Claude Opus 5.5" }
]
}
]Skills
Reusable, versioned instruction bundles. The capped Markdown manifest stays in Agents; larger topics, templates, and assets live in a system-managed skill bucket. A custom skill is a connection-gated federated zone: agents need agents:skills:view to load it and receive read/copy access to its files, while agents:skills:edit enables authoring. Platform skill buckets are tenant-readable but platform-authored.
/api/v1/agents/companies/{company_id}/skillsList 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
}/api/v1/agents/companies/{company_id}/skillsCreate Skill
Create a custom company skill with its ready system-managed file bucket. The response includes a non-null bucket_id and the creator receives author access.
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 |
is_template | boolean | Controls template copy/patch/deliver semantics only; every custom skill receives a bucket and may store files |
Response Fields
| Name | Type | Description |
|---|---|---|
id* | UUID | Skill ID |
company_id* | UUID | null | Organization ID |
name* | string | Display name |
slug* | string | Stable slug |
kind* | "custom" | Visible skill kind |
bucket_id* | UUID | Ready system-managed skill bucket |
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",
"kind": "custom",
"bucket_id": "b0c11111-2222-3333-4444-555566667777",
"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"
}/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"
}/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"
}/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/api/v1/agents/skills/{skill_id}/bucketRepair Skill Files
Idempotently repair/provision the system-managed working-file bucket for an older custom skill. Normal skill creation already returns a ready bucket. Tool slug: agents.skills.ensure_bucket.
Bearer token with agents:skills:edit on the custom skill.
Path Parameters
| Name | Type | Description |
|---|---|---|
skill_id* | string (UUID) | Skill ID |
curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/bucket \
-H "Authorization: Bearer {token}"Response
200 OK{
"skill_id": "5ki11111-2222-3333-4444-555566667777",
"bucket_id": "b0c11111-2222-3333-4444-555566667777",
"created": true
}/api/v1/agents/skills/{skill_id}/versionsList Skill Versions
List immutable manifest and working-file snapshot metadata. Tool slug: agents.skills.list_versions.
Bearer token with agents:skills:view on a custom skill; platform skills are readable.
Path Parameters
| Name | Type | Description |
|---|---|---|
skill_id* | string (UUID) | Skill ID |
curl https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/versions \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [{
"id": "ver11111-2222-3333-4444-555566667777",
"skill_id": "5ki11111-2222-3333-4444-555566667777",
"version_number": 2,
"content_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"label": "approved",
"message": "Updated escalation template",
"files": [],
"created_by_principal_id": null,
"created_at": "2026-09-14T12:00:00Z"
}],
"current_version": 2
}/api/v1/agents/skills/{skill_id}/versionsPublish Skill Version
Append an immutable snapshot of the current manifest and working files. Returns 409 no_changes when the working copy matches the latest version. Tool slug: agents.skills.publish_version.
Bearer token with agents:skills:edit on the custom skill.
Path Parameters
| Name | Type | Description |
|---|---|---|
skill_id* | string (UUID) | Skill ID |
Request Body
| Name | Type | Description |
|---|---|---|
label | string | null | Optional version label |
message | string | null | Optional change description |
curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/versions \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"label":"approved","message":"Updated escalation template"}'Response
201 Created{
"id": "ver11111-2222-3333-4444-555566667777",
"skill_id": "5ki11111-2222-3333-4444-555566667777",
"version_number": 2,
"content_digest": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"label": "approved",
"message": "Updated escalation template",
"files": [],
"created_by_principal_id": null,
"created_at": "2026-09-14T12:00:00Z"
}/api/v1/agents/skills/{skill_id}/versions/{version_number}/restoreRestore Skill Version
Restore a custom skill's working copy and append a new immutable version labeled with the source version. Existing version numbers are never reused. Tool slug: agents.skills.restore_version.
Bearer token with agents:skills:edit on the custom skill.
Path Parameters
| Name | Type | Description |
|---|---|---|
skill_id* | string (UUID) | Skill ID |
version_number* | integer | Version to restore |
curl -X POST https://platform.ergondata.ai/api/v1/agents/skills/{skill_id}/versions/1/restore \
-H "Authorization: Bearer {token}"Response
200 OK{
"id": "ver33333-2222-3333-4444-555566667777",
"skill_id": "5ki11111-2222-3333-4444-555566667777",
"version_number": 3,
"content_digest": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
"label": "restore of v1",
"message": null,
"files": [],
"created_by_principal_id": null,
"created_at": "2026-09-14T12:05:00Z"
}/api/v1/agents/agents/{agent_id}/skills/catalogList 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"
}
}
]/api/v1/agents/agents/{agent_id}/skills/assignmentsList Agent Skill Assignments
List explicit general/custom skill assignments. load_mode is pinned, selectable, searchable, or null (explicitly disabled). Built-in general 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"
}
]/api/v1/agents/agents/{agent_id}/skills/assignmentsCreate 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"
}/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"
}/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 ContentAgent Configs
Configure individual agents with system prompts, LLM configs, reasoning effort, and runtime limits such as the run timeout and tool calls per run.
/api/v1/agents/{agent_id}/configGet 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 | Deprecated. Always null. |
top_p* | float | null | Deprecated. Always null. |
max_tokens* | integer | null | Deprecated. Always null; output tokens per model call are always Auto. |
timeout* | integer | null | Request timeout in seconds (1-600) |
max_tool_iterations* | integer | null | Internal action-round safety (1-100) |
max_tool_calls_per_run* | integer | null | Max tool calls in one run (1-500) |
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: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": null,
"top_p": null,
"max_tokens": null,
"timeout": 120,
"max_tool_iterations": 10,
"max_tool_calls_per_run": 200,
"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"
}/api/v1/agents/{agent_id}/configUpdate 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 | Deprecated. Accepted and ignored: no temperature is sent to the provider. |
top_p | float | null | Deprecated. Accepted and ignored: top-p is never sent to the provider. |
max_tokens | integer | null | Deprecated. Accepted and ignored: output tokens per model call are always Auto (the model's catalog ceiling, clamped by budgets and context headroom). |
timeout | integer | null | Timeout in seconds (1-600) |
max_tool_iterations | integer | null | Internal action-round safety (1-100) |
max_tool_calls_per_run | integer | null | Max tool calls in one run (1-500) |
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",
"timeout": 120
}'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": null,
"top_p": null,
"max_tokens": null,
"timeout": 120,
"max_tool_iterations": 10,
"max_tool_calls_per_run": 200,
"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"
}/api/v1/agents/{agent_id}/conversation-startersResolve 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}/api/v1/agents/{agent_id}/conversation-starters/previewPreview Conversation Starters
Preview the starter suggestions produced by unsaved off, preset, or infer settings without changing the agent configuration.
Bearer token with agents:agents:view on the agent.
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | UUID | Agent ID |
Request Body
| Name | Type | Description |
|---|---|---|
mode* | "off" | "preset" | "infer" | Starter mode to preview |
presets | string[] | Candidate preset prompts |
curl -X POST "https://platform.ergondata.ai/api/v1/agents/{agent_id}/conversation-starters/preview" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d '{"mode":"preset","presets":["Summarize this project"]}'Response
200 OK{"mode":"preset","items":["Summarize this project"],"source":"preset","inference_available":true}/api/v1/agents/{agent_id}/prior-digests/searchSearch 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."}/api/v1/agents/{agent_id}/config/privacyUpdate 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:agents:privacy:manage, separate from the general config write.
Bearer token required. Permission: agents: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": null,
"updated_at": "2025-01-16T09:00:00Z"
}Config Status
Check agent configuration state and list the operational agents visible in Agent Hub.
/api/v1/agents/companies/{company_id}/hubList Agent Hub Agents
List operationally visible agents with readiness derived from effective runtime access and model-route configuration.
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}/hub" -H "Authorization: Bearer {token}"Response
200 OK{"items":[],"total":0}/api/v1/agents/companies/{company_id}/config-statusList 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.
/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}/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}/api/v1/agents/users/me/preferencesList 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}/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}/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/api/v1/agents/{agent_id}/preferencesList Agent Preferences
Manager audit view of participant preference records retained for an agent. Tool slug: agents.preferences.list.
Bearer token with agents: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}/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: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"}/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: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/api/v1/agents/{agent_id}/memoriesRecord 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: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"}/api/v1/agents/{agent_id}/memoriesList Agent Memories
List authoritative typed semantic memories. Tool slug: agents.memories.list.
Bearer token with agents: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}/api/v1/agents/{agent_id}/memories/recallRecall 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: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"}/api/v1/agents/{agent_id}/memories/exportExport Agent Memories
Download every authoritative semantic memory for the agent as Markdown. Tool slug: agents.memories.export.
Bearer token with agents: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./api/v1/agents/{agent_id}/memories/{memory_id}/retry-exportRetry 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: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"}/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: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 ContentInvoke
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.
/api/v1/agents/agents/{agent_id}/invokeInvoke 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. When an agent calls this from one of its conversation turns for an agent of the same company, result_delivery is 'conversation': the invoked agent's status and result are posted back into that conversation; otherwise it is 'poll'. Agent-to-agent chains past the configured depth return 409 invoke_depth_exceeded; too many handoffs per conversation per hour (invoking turns, timers and waits for a reply count together), or too many invokes in one turn, return 429 invoke_turn_limit or invoke_children_limit.
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_tool_iterations, max_tool_calls_per_run, timeout. Deprecated max_tokens, temperature and top_p are accepted and ignored; output tokens are always Auto |
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. |
working_directory | boolean | Give the run its own bucket for the files it brings in. The agent saves files there unless its instructions name another destination. The bucket is deleted 7 days after the run ends.Default: false |
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 |
result_delivery* | string | 'conversation' when an agent calls this from one of its conversation turns for an agent of the same company (the result is posted back there and wakes the caller); otherwise 'poll' (read it with GET runs/{run_id}; polling your own invoke needs no extra permission, reading other runs needs agents:agents:activity:view on the agent) |
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": "customer@example.com",
"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",
"result_delivery": "poll"
}/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. A run that does not exist or belongs to another agent returns 404, as does a personal agent you can't see, all with the same body. The caller's company is not compared: the run's invoker gets 200 from any company, and anyone else without activity on the agent gets 403.
Polling your own invoke needs no extra permission: the run's invoker (from any company) only needs agents:agents:use on the agent. Reading other runs needs agents:agents:activity:view on the concrete agent resource (agents:agents:view is not enough).
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, waiting (the run called agents.runs.wait or sleep and holds no worker), 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 |
parent_run_id | string | null | The calling run when another agent invoked this one; root_run_id, calling_agent_id and invoke_depth describe the rest of the chain. parent_run_id and calling_agent_id are null when the calling run belongs to another company, and root_run_id is null when the root run does |
wake_at | string (ISO 8601) | null | Set while status is waiting: when the run wakes at the latest |
awaited_run_id | string (UUID) | null | Set while status is waiting: the run it waits for (null while it sleeps) |
working_directory_bucket_id | string (UUID) | null | The run's working-directory bucket when it was invoked with working_directory: true; null before it exists and after it is deleted, 7 days after the run ends |
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
}/api/v1/agents/agents/{agent_id}/runs/{run_id}/messagesList Agent Run Messages
Page through the durable provider-compatible transcript for a headless AgentRun, including role/content, kind, tool fields, usage, and timestamps. kind is message for the rows the model saw (tool errors included); thinking (the provider's reasoning summary) and progress (text written before a round's tool calls) rows are for display only and never reach the model.
Bearer token with agents:agents:activity:view on the concrete agent resource (agents:agents:view is not enough). A refusal on a personal agent you cannot see is the missing-run 404.
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", "kind": "message", "content": "hello", "tool_name": null},
{"sequence": 1, "role": "assistant", "kind": "thinking", "content": "A greeting.", "tool_name": null}
],
"total": 2
}/api/v1/agents/ws/agents/{agent_id}/runs/{run_id}/streamWatch an Agent Run Live (WebSocket)
Streams what a headless run does while it works: run.started (with resumed when it was woken), thinking, status, reasoning.delta, reasoning.done, chunk, tool_call.started, tool_call.completed, app.progress and file.progress, then done or error when it ends, or run.waiting when it starts waiting. Events that draw the turn carry run_id. Nothing is replayed: read List Agent Run Messages when the socket is ready, and again after it reconnects. The server sends {type: ready} once subscribed and {type: ping} every 30 seconds, and closes after an hour. Close codes: 4001 authentication failed; 4003 forbidden (a caller of the run's company who can see the agent but lacks the permission); 4004 run not found, also for any other refusal (a caller from another company, or a personal agent you cannot see), so the code never confirms the run exists; 1013 try again later.
JWT via Sec-WebSocket-Protocol (access_token.<jwt>, offered with ergon.live.v1). Never put the token in the URL. Same check as List Agent Run Messages: agents:agents:activity:view on the concrete agent resource (agents:agents:view is not enough).
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Owning agent ID |
run_id* | string (UUID) | AgentRun ID |
curl -i -N \
-H "Connection: Upgrade" \
-H "Upgrade: websocket" \
-H "Sec-WebSocket-Version: 13" \
-H "Sec-WebSocket-Key: {base64_nonce}" \
-H "Sec-WebSocket-Protocol: ergon.live.v1, access_token.{token}" \
"https://platform.ergondata.ai/api/v1/agents/ws/agents/{agent_id}/runs/{run_id}/stream"Response
101{
"type": "chunk",
"run_id": "9b2f1c3e-0d4a-4f5b-8c6d-7e8f9a0b1c2d",
"content": "Checking the invoice"
}/api/v1/agents/agents/{agent_id}/runsList Agent Runs
List one agent's headless runs (from automations, schedules, the API or another agent), newest first, with status, source, timings, model and summed token usage. An agent of another company returns 404.
Bearer token with agents:agents:activity:view on the concrete agent resource (agents:agents:view is not enough).
Path Parameters
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | Owning agent ID |
Query Parameters
| Name | Type | Description |
|---|---|---|
status | string | Only runs in this status: pending, running, waiting, completed or failed |
limit | number | Page size, 1–100Default: 50 |
offset | number | Zero-based offsetDefault: 0 |
Response Fields
| Name | Type | Description |
|---|---|---|
items* | array | Run summaries, newest first: id, agent_id, status, source_type, mode, error_code, error_message, automation_id, automation_run_id, automation_node_slug, llm_config_id, model_slug, invoke_depth, started_at, completed_at, created_at, updated_at and usage (input_tokens, output_tokens, cost_usd) |
total* | number | Runs that match the filter |
curl "https://platform.ergondata.ai/api/v1/agents/agents/{agent_id}/runs?status=failed&limit=50" \
-H "Authorization: Bearer {token}"Response
200 OK{
"items": [
{
"id": "run-1111-2222-3333-444455556666",
"agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"status": "failed",
"source_type": "api",
"automation_id": "aut-1111-2222-3333-444455556666",
"model_slug": "gpt-5-mini",
"invoke_depth": 0,
"started_at": "2026-11-20T12:00:01Z",
"completed_at": "2026-11-20T12:00:09Z",
"usage": {"input_tokens": 123, "output_tokens": 17, "cost_usd": "0.00042"}
}
],
"total": 1
}/api/v1/agents/runs/{run_id}Lookup Agent Run
Find a headless run, and the agent it belongs to, from the run id alone; for callers such as an automation timeline that know the run but not its agent. A run of another company, or one you may not view, returns the same 404 as a missing run.
Bearer token with agents:agents:activity:view on the run's agent (agents:agents:view is not enough).
Path Parameters
| Name | Type | Description |
|---|---|---|
run_id* | string (UUID) | AgentRun ID |
Response Fields
| Name | Type | Description |
|---|---|---|
agent_id* | string (UUID) | The agent the run belongs to |
status* | string | pending, running, waiting, completed, or failed |
usage* | object | Summed input_tokens, output_tokens and cost_usd |
curl https://platform.ergondata.ai/api/v1/agents/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",
"source_type": "api",
"usage": {"input_tokens": 123, "output_tokens": 17, "cost_usd": "0.00042"}
}/api/v1/agents/output-schema/generateGenerate 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 |
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"]
}
}Approvals
Before running an action, an agent in a direct or widget conversation can ask a person to approve it with the request_approval runtime tool. It names one tool call (tool slug and exact arguments) plus a headline, a reason and optional labelled fields for the card. The request is refused when the tool does not exist or the agent may not call it, or when the same model response also calls another tool (then nothing in that response runs). The agent's turn then ends and the conversation shows an approval card: a kind="event" message with an agent_approval block (approval_id, status, headline, reason, fields, approve_label, asked_because, tool, arguments, decider_principal_id). A new event message is posted per status change (pending, running, executed, failed, denied, withdrawn) and clients show the furthest status per approval_id. Only one person can decide: the owner of a personal agent, otherwise the person whose message started the turn. Approving makes the platform run exactly the stored tool call with the agent's access, whatever the card text says; denying runs nothing. Either way the agent is woken with the outcome. A new message from the person neither approves nor denies. Approvals are not offered in headless runs or on email and WhatsApp conversations.
/api/v1/agents/approvals/{approval_id}/decisionDecide Approval
Approve or deny the tool call an agent asked about. Approving queues the stored call (status approved, then running, then executed or failed); denying records the optional note and runs nothing. Repeating the decision already recorded returns the request unchanged; a different decision returns 409. Returns 403 for anyone but the person named in decider_principal_id, for agents and automations, and for a person who left the conversation. Returns 404 for an unknown approval or one in another organization.
Bearer token of the signed-in person who may decide (decider_principal_id on the approval card). API clients, agents and automations are refused.
Path Parameters
| Name | Type | Description |
|---|---|---|
approval_id* | string (UUID) | approval_id from the agent_approval block |
Request Body
| Name | Type | Description |
|---|---|---|
decision* | "approve" | "deny" | What the person decided. |
note | string | null | With a denial: what the agent should change instead (up to 2000 characters). |
curl -X POST https://platform.ergondata.ai/api/v1/agents/approvals/{approval_id}/decision \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{ "decision": "deny", "note": "Keep the newest row of each pair." }'Response
200 OK{
"id": "7d3f1c1e-52b1-4c5d-9a53-0a4f6f0d2b11",
"conversation_id": "5e2a9d1c-9c0b-4d0e-8a43-b1f2a8c7d900",
"agent_id": "abcd1234-ef56-7890-abcd-ef1234567890",
"status": "approved",
"tool": "worksheets.rows.delete",
"headline": "Delete 14 rows from Leads 2026",
"decider_principal_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"decided_by_principal_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"decided_at": "2026-11-19T22:42:00Z",
"note": null
}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.
/api/v1/agents/agents/{agent_id}/grantsCreate 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"
}/api/v1/agents/agents/{agent_id}/grantsList 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"
}
]/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/api/v1/agents/agents/grantedList 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.
/api/v1/agents/companies/{company_id}/budgetsList 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"}]/api/v1/agents/companies/{company_id}/budgetsCreate 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:budgets: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"}/api/v1/agents/companies/{company_id}/llm-configs/{llm_config_id}/budgetsCreate 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"}/api/v1/agents/companies/{company_id}/agents/{agent_id}/budgets/totalCreate 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:budgets: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"}/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:budgets: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/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/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:budgets: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/api/v1/agents/companies/{company_id}/budgets/usage-summaryGet 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}/api/v1/agents/companies/{company_id}/budgets/planGet 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"}/api/v1/agents/companies/{company_id}/budgets/planUpdate 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}}]}/api/v1/agents/{agent_id}/budget-planGet 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}]}/api/v1/agents/{agent_id}/budget-planUpdate 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:budgets: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}]}/api/v1/agents/llm-configs/{llm_config_id}/usageGet 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":[]}/api/v1/agents/{agent_id}/usageGet 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":[]}/api/v1/agents/conversations/{conversation_id}/usageGet 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.
/api/v1/agents/event-typesList 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" }
]/api/v1/agents/companies/{company_id}/activityList 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
}/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.
/api/v1/agents/companies/{company_id}/access/eligibleList 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"
}
]/api/v1/agents/companies/{company_id}/access/resource-typesList 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
}
]
}/api/v1/agents/companies/{company_id}/access/grantsList 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
}/api/v1/agents/companies/{company_id}/access/grantsCreate 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"
}/api/v1/agents/access/agents/grants/batchCreate 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}
}/api/v1/agents/access/skills/grants/batchCreate 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}}/api/v1/agents/access/llm-configs/grants/batchCreate 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}}/api/v1/agents/access/provider-keys/grants/batchCreate 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}}/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/api/v1/agents/agents/{agent_id}/access/eligibleList 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"
}
]/api/v1/agents/agents/{agent_id}/access/resource-typesList 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
}
]
}/api/v1/agents/agents/{agent_id}/access/grantsList 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
}/api/v1/agents/agents/{agent_id}/access/grantsCreate 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"
}/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/api/v1/agents/agents/{agent_id}/access/connection-requestsList 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"
}
]/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/approveApprove 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"
}/api/v1/agents/agents/{agent_id}/access/connection-requests/{request_id}/rejectReject 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"
}/api/v1/agents/agents/{agent_id}/access/connectionsList 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"
}
]/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/api/v1/agents/skills/{skill_id}/access/eligibleList 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"
}
]/api/v1/agents/skills/{skill_id}/access/resource-typesList 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
}
]
}/api/v1/agents/skills/{skill_id}/access/grantsList 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
}/api/v1/agents/skills/{skill_id}/access/grantsCreate 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"
}/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/api/v1/agents/skills/{skill_id}/access/connection-requestsList 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"
}
]/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/approveApprove 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"
}/api/v1/agents/skills/{skill_id}/access/connection-requests/{request_id}/rejectReject 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/api/v1/agents/skills/{skill_id}/access/connectionsList 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"
}
]/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/api/v1/agents/llm-configs/{config_id}/access/eligibleList 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"
}
]/api/v1/agents/llm-configs/{config_id}/access/resource-typesList 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
}
]
}/api/v1/agents/llm-configs/{config_id}/access/grantsList 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
}/api/v1/agents/llm-configs/{config_id}/access/grantsCreate 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"
}/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/api/v1/agents/llm-configs/{config_id}/access/connection-requestsList 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"
}
]/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/approveApprove 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"
}/api/v1/agents/llm-configs/{config_id}/access/connection-requests/{request_id}/rejectReject 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"
}/api/v1/agents/llm-configs/{config_id}/access/connectionsList 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"
}
]/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/api/v1/agents/provider-keys/{key_id}/access/eligibleList 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"
}
]/api/v1/agents/provider-keys/{key_id}/access/resource-typesList 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
}
]
}/api/v1/agents/provider-keys/{key_id}/access/grantsList 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
}/api/v1/agents/provider-keys/{key_id}/access/grantsCreate 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"
}/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/api/v1/agents/provider-keys/{key_id}/access/connection-requestsList 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"
}
]/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/approveApprove 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"
}/api/v1/agents/provider-keys/{key_id}/access/connection-requests/{request_id}/rejectReject 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"
}/api/v1/agents/provider-keys/{key_id}/access/connectionsList 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"
}
]/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/api/v1/agents/agents/{agent_id}/connectionsList 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"
}
]/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/api/v1/agents/agents/{agent_id}/connection-requests/{request_id}/withdrawWithdraw 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"
}