Agents

The Agent endpoints manage the AI agents your organization runs. You can create, list, fetch, update, archive (soft-delete), and restore agents, and read or update an agent’s generation configuration. To actually run an agent, see Agent Query.

Reads require agents:read; writes require agents:write. Archiving and restoring additionally require the agent-delete permission on the role that minted the key.

The agent shape

Most endpoints return an agent object with this deny-by-default shape:


{
  "id": "agt_7c1d8e",
  "name": "Support Bot",
  "description": "Answers product questions.",
  "status": "active",
  "language": "en",
  "type": "custom",
  "configuration": {
    "temperature": 0.7,
    "max_tokens": 1500,
    "system_prompt": "You are a helpful support agent.",
    "response_format": "conversational",
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0,
    "streaming_enabled": true,
    "max_retrieved_chunks": 10,
    "show_citations": false
  },
  "knowledge_access": {
    "folder_ids": ["fold_abc123"],
    "tag_ids": [],
    "document_ids": [],
    "access_mode": "inclusive",
    "document_count_cache": 12
  },
  "handoff_config": {
    "enabled": false
  },
  "current_month_usage": {
    "queries": 134,
    "tokens_used": 41200,
    "last_reset_date": "2026-06-01T00:00:00Z"
  },
  "created_at": "2026-05-20T11:00:00Z",
  "updated_at": "2026-06-07T08:30:00Z"
}

The agent object exposes only tenant-facing fields. The underlying LLM provider/model identifier is deliberately not returned in any agent or configuration response — you set the model when you create an agent (a request input), but it is never echoed back. Internal identifiers, cost figures, and version/retry bookkeeping are likewise never present.

The status field is one of active, inactive, testing, or archived.

`POST /agents`

Create an agent. Returns 201 with the created agent. Accepts an Idempotency-Key so a retried create never produces a second agent.

Scope: agents:write · Success: 201

Parameter	In	Type	Required	Description
`name`	body	string	Yes	Agent name (1–100 chars).
`description`	body	string	No	A description (≤500 chars).
`status`	body	string	No	`active`, `inactive`, `testing`, or `archived`.
`language`	body	string	No	A BCP-47 response-language override. Inherits the org default when omitted.
`configuration`	body	object	Yes	The LLM configuration block (see below).
`knowledge_access`	body	object	No	Which folders/tags/documents the agent may use.
`handoff_config`	body	object	No	Human-handoff configuration.
`Idempotency-Key`	header	string	No	Replay-safe retry key.

The required configuration block carries the model and generation settings. model and system_prompt are required; everything else has a default:

Field	Type	Required	Description
`model`	string	Yes	The model the agent should use. Request input only — never returned in any response.
`system_prompt`	string	Yes	The agent’s system prompt (1–10000 chars).
`temperature`	number	No	0.0–2.0. Defaults to 0.7.
`max_tokens`	integer	No	100–4000. Defaults to 1500.
`response_format`	string	No	`conversational` or `structured`.
`top_p`	number	No	0.0–1.0. Defaults to 1.0.
`frequency_penalty`	number	No	-2.0–2.0. Defaults to 0.0.
`presence_penalty`	number	No	-2.0–2.0. Defaults to 0.0.
`streaming_enabled`	boolean	No	Defaults to `true`.
`max_retrieved_chunks`	integer	No	5–20. Defaults to 10.
`show_citations`	boolean	No	Defaults to `false`.


curl -X POST https://cuneiform.chat/api/developer/v1/agents \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "description": "Answers product questions.",
    "configuration": {
      "model": "gpt-4o-mini",
      "system_prompt": "You are a helpful support agent."
    }
  }'


{
  "id": "agt_7c1d8e",
  "name": "Support Bot",
  "description": "Answers product questions.",
  "status": "active",
  "language": null,
  "type": "custom",
  "configuration": {
    "temperature": 0.7,
    "max_tokens": 1500,
    "system_prompt": "You are a helpful support agent.",
    "response_format": "conversational",
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0,
    "streaming_enabled": true,
    "max_retrieved_chunks": 10,
    "show_citations": false
  },
  "knowledge_access": {
    "folder_ids": [],
    "tag_ids": [],
    "document_ids": [],
    "access_mode": "inclusive",
    "document_count_cache": 0
  },
  "handoff_config": {
    "enabled": false
  },
  "current_month_usage": {
    "queries": 0,
    "tokens_used": 0,
    "last_reset_date": "2026-06-01T00:00:00Z"
  },
  "created_at": "2026-06-07T08:30:00Z",
  "updated_at": "2026-06-07T08:30:00Z"
}

Errors: 400, 401, 403 (scope or tier limit), 429, 500.

`GET /agents`

List agents, cursor-paginated, with optional status and search filters.

Scope: agents:read · Success: 200

Parameter	In	Type	Required	Description
`limit`	query	integer	No	Page size, 1–100. Defaults to 20.
`cursor`	query	string	No	The `next_cursor` from the previous page.
`status`	query	string	No	Filter by agent status.
`search`	query	string	No	Filter by a name/description search term.


curl "https://cuneiform.chat/api/developer/v1/agents?limit=20&status=active" \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"


{
  "data": [
    {
      "id": "agt_7c1d8e",
      "name": "Support Bot",
      "description": "Answers product questions.",
      "status": "active",
      "language": "en",
      "type": "custom",
      "configuration": {
        "temperature": 0.7,
        "max_tokens": 1500,
        "response_format": "conversational",
        "top_p": 1.0,
        "frequency_penalty": 0.0,
        "presence_penalty": 0.0,
        "streaming_enabled": true,
        "max_retrieved_chunks": 10,
        "show_citations": false
      },
      "knowledge_access": {
        "folder_ids": ["fold_abc123"],
        "tag_ids": [],
        "document_ids": [],
        "access_mode": "inclusive",
        "document_count_cache": 12
      },
      "handoff_config": { "enabled": false },
      "current_month_usage": {
        "queries": 134,
        "tokens_used": 41200,
        "last_reset_date": "2026-06-01T00:00:00Z"
      },
      "created_at": "2026-05-20T11:00:00Z",
      "updated_at": "2026-06-07T08:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The list view omits the system_prompt from each agent’s configuration for brevity; fetch a single agent to see it.

Errors: 400 invalid_cursor, 401, 403, 429, 500.

`GET /agents/{agent_id}`

Fetch a single agent by id.

Scope: agents:read · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.


curl https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

The response is a single agent object (see the agent shape).

Errors: 401, 403, 404 agent_not_found, 429, 500.

`PATCH /agents/{agent_id}`

Update an agent’s basic fields. All body fields are optional; omitted fields are left unchanged. Generation settings live on the configuration endpoint, not here.

Scope: agents:write · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.
`name`	body	string	No	New name (1–100 chars).
`description`	body	string	No	New description (≤500 chars).
`status`	body	string	No	New status.
`language`	body	string	No	New BCP-47 language override.
`handoff_config`	body	object	No	New human-handoff configuration.


curl -X PATCH https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'

The response is the updated agent object.

Errors: 400, 401, 403, 404, 429, 500.

`DELETE /agents/{agent_id}`

Archive (soft-delete) an agent. The agent is recoverable for 30 days via the restore endpoint. Returns 200 with an archive body carrying the restore deadline.

Scope: agents:write (the minting role must also hold the agent-delete permission) · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.


curl -X DELETE https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"


{
  "id": "agt_7c1d8e",
  "archived": true,
  "restore_before": "2026-07-07T08:30:00Z"
}

Errors: 401, 403, 404, 429, 500.

`POST /agents/{agent_id}/restore`

Restore an archived agent within its 30-day recovery window. Returns the restored agent. An expired window or a not-archived agent returns 400.

Scope: agents:write (the minting role must also hold the agent-delete permission) · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.


curl -X POST https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e/restore \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"

The response is the restored agent object.

Errors: 400, 401, 403, 404, 429, 500.

`GET /agents/{agent_id}/configuration`

Fetch an agent’s configuration. Exposes only the tenant-facing generation settings; the underlying LLM provider/model identifier is not returned.

Scope: agents:read · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.


curl https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e/configuration \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx"


{
  "id": "agt_7c1d8e",
  "configuration": {
    "temperature": 0.7,
    "max_tokens": 1500,
    "system_prompt": "You are a helpful support agent.",
    "response_format": "conversational",
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0,
    "streaming_enabled": true,
    "max_retrieved_chunks": 10,
    "show_citations": false
  },
  "unsaved_changes": false
}

Errors: 401, 403, 404, 429, 500.

`PATCH /agents/{agent_id}/configuration`

Update an agent’s generation settings. All body fields are optional. A setting that breaches your plan’s limits returns 403.

Scope: agents:write · Success: 200

Parameter	In	Type	Required	Description
`agent_id`	path	string	Yes	The agent id.
`system_prompt`	body	string	No	New system prompt (1–10000 chars).
`temperature`	body	number	No	0.0–2.0.
`max_tokens`	body	integer	No	100–4000.
`response_format`	body	string	No	`conversational` or `structured`.
`top_p`	body	number	No	0.0–1.0.
`frequency_penalty`	body	number	No	-2.0–2.0.
`presence_penalty`	body	number	No	-2.0–2.0.
`streaming_enabled`	body	boolean	No	Whether streaming is enabled.
`max_retrieved_chunks`	body	integer	No	5–20.
`show_citations`	body	boolean	No	Whether to show citations.
`save_as_draft`	body	boolean	No	Save without publishing a new version. Defaults to `false`.


curl -X PATCH https://cuneiform.chat/api/developer/v1/agents/agt_7c1d8e/configuration \
  -H "Authorization: Bearer cuk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "temperature": 0.4, "max_tokens": 2000 }'


{
  "id": "agt_7c1d8e",
  "configuration": {
    "temperature": 0.4,
    "max_tokens": 2000,
    "system_prompt": "You are a helpful support agent.",
    "response_format": "conversational",
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0,
    "streaming_enabled": true,
    "max_retrieved_chunks": 10,
    "show_citations": false
  }
}

Errors: 400, 401, 403 (scope or tier limit), 404, 429, 500.