Platform concepts

Agents

How agents are created, changed, versioned, paused and removed, and how the platform chooses the model they run on.

An agent is a worker in your company: it has a name, a description, the tools it may use, its memory and its limits. You talk to it in a conversation, and each piece of work it does is a run.

Most people never create an agent by hand. They ask the Chief of Staff, which creates focused specialists when work needs them. The API below is the same one it uses, and you can call it directly.

Creating an agent

Only name is required. Creating agents needs the agents:write scope.

curl -X POST https://api.snaga.ai/api/v1/agents \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Market researcher", "description": "Finds and summarises competitor news"}'

The answer is 201 with the agent. Along the way the platform writes version 1 of the agent and gives it its own identity key. If your plan's agent limit is already reached, the call is refused with 403.

Models are chosen by the platform

Every agent runs on the platform's default model. model and fallback_model in a create or update body are accepted and ignored, and responses do not reveal the provider, model or endpoint behind an agent. You do not need to pick a model to get started.

To see what the platform offers, read:

Call	What it answers
`GET /api/v1/providers/platform-defaults`	The default and fallback model. Needs no API key.
`GET /api/v1/llm/models`	The models your company's plan lets you call, with their capabilities and the price you pay (`agents:read`).
`GET /api/v1/providers`	The providers the platform knows about.

These matter when you call models directly through the compatible endpoints.

Storing your own provider API key (/api/v1/llm-credentials/*) is reserved for platform administrators: every method on that surface refuses an ordinary member.

The system prompt

prompts.system is also accepted and ignored. An agent's system prompt is managed by the Chief of Staff; a new agent starts with a neutral one. prompts.developer is stored as you send it. For the prompt a public chat uses, set public_config.system_prompt.

Changing an agent

PATCH /api/v1/agents/{agentId} and PUT /api/v1/agents/{agentId} share one handler and both merge: a field you leave out keeps its stored value; it is not cleared.

curl -X PATCH https://api.snaga.ai/api/v1/agents/<agent_id> \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Finds, summarises and ranks competitor news"}'

A few things to know:

Some objects merge one level deep (resource_limits, memory, schedule, guardrails, metadata, public_config and others); some are replaced whole (mcp, policies, thinking, autonomy and others); every array replaces the stored list.
An unknown field is dropped. A known field of the wrong type is 422.
A concurrent update to the same agent answers 409; read it again and retry.

Versions

Every update snapshots the agent before and after the write, so one update adds two entries to its history. Versions are never deleted.

Call	What it does
`GET /api/v1/agents/{agentId}/versions`	The history, newest first. `?fields=summary` leaves out each version's full config.
`POST /api/v1/agents/{agentId}/versions`	Take a snapshot now, with an optional `changelog`. Refused `403` when the plan's version history is full.
`GET /api/v1/agents/{agentId}/versions/{versionNum}/diff`	What changed between two versions (`?compare_to=`, default the previous one).
`POST /api/v1/agents/{agentId}/rollback`	Restore the config of `{"version": N}`.

A rollback records a new version ("Rollback to version N") instead of erasing later ones, so the history stays complete. It restores what the agent does, not how it looks: its appearance is kept.

Who can reach an agent

visibility is private, team or public. Setting public alone does not open the agent to the world: it is reachable anonymously only when visibility is public, public_config.enabled is true and the agent's status is active.

Pausing, resetting and removing

Call	Effect
`POST /api/v1/agents/{agentId}/suspend`	`active` → `suspended`; it stops accepting new runs. Optional `reason`.
`POST /api/v1/agents/{agentId}/activate`	`suspended` → `active`.
`POST /api/v1/agents/{agentId}/reset`	Deletes the agent's memory and every conversation it owns, with their runs. The agent's settings stay.
`DELETE /api/v1/agents/{agentId}`	Deletes the agent and everything keyed to it. Refused `409` while it serves a public chat — unpublish first.
`POST /api/v1/agents/{agentId}/terminate`	Deletes the agent like `DELETE`, but also tears down a published agent's public access.

Reset, delete and terminate cannot be undone. The company's Chief of Staff cannot be deleted or terminated (403).

Listing agents

GET /api/v1/agents returns your agents newest first, 20 per page by default and at most 100. Follow cursor while has_more is true — see pagination.

The Chief of Staff — the agent that builds and directs the others.
Approvals — tools an agent must ask before using.
Usage and limits — the agent and version limits of your plan.