Agents

Create an agent

Requires an active subscription and canCreateAgents permission. teamId may be ANY team of your live company; a team outside it (or belonging to no company) is only accepted if you belong to it — NOT_TEAM_MEMBER (403) otherwise. Guards, checked in order: NOT_TEAM_MEMBER (403), AGENT_CREATION_NOT_ALLOWED (403), AGENT_LIMIT_REACHED (403), NO_ACTIVE_SUBSCRIPTION (402), MODEL_NOT_FOUND/HARNESS_NOT_FOUND (400), CLIENT_NOT_FOUND (404).

post/agents

Request

  • Base URL: https://api.atako.ai
  • URL: https://api.atako.ai/agents
  • Auth: HTTP bearer

Request body

namestring required
imagestring required

PNG filename under apps/web/public/aiygents/.

finish'carbone' | 'chrome-studio' | 'titane' | 'candy' | 'nacre-ormeau' | 'velours' | 'ceramique' | 'marbre' | 'terrazzo' | 'cuir' | 'jade' | 'maille' | 'mercure' | 'lave' | 'eau' | 'glace' | 'malachite' | 'labradorite' | 'calacatta' | 'noyer' | 'soie' | 'ecailles' nullable

The 3D body finish (the user-facing « skin »). Absent or null = carbone; unknown → 400 FINISH_INVALID.

missionstring nullable

The agent's mission in 1–3 sentences, trimmed.

systemPromptstring nullable

Free-text agent instructions, trimmed. Stored and sent to the orchestrator as-is (no business context appended).

clientContextstring nullable

Free-text per-agent business context, trimmed. Kept in its own column.

modelIdstring

Either an ai_models UUID (from GET /models or aiModelId in GET /models/catalog) or a raw OpenRouter slug (slug in GET /models/catalog, e.g. "mistralai/mistral-small"). A slug unknown to the catalog is rejected with 400. Omitted → admin-declared default model. With a direct-provider BYOK key (openai/anthropic), this is instead the provider's own model id.

harnessIdstring uuid

From GET /harnesses.

teamIdstring uuid nullable

Assigns the agent to a shared team instead of keeping it personal.

engine'openclaw' | 'hermes' | 'opencode'

Defaults to the platform default engine (hermes). opencode additionally requires allowedRepos.

allowedReposstring[]

Repositories (owner/repo) the agent may work on. REQUIRED (≥1) for engine: opencode, which also requires an active company GitHub connection; ignored by the other engines.

llmKeyIdstring uuid

BYOK: id of a company LLM provider key (see docs — BYOK key management is not part of this customer API cut).

Example request

{
  "modelId": "anthropic/claude-sonnet-4"
}

Response

The created agent (raw row).

idstring uuid required
clientIdstring uuid required
teamIdstring uuid nullable
companyIdstring uuid nullable
namestring required
imagestring required
systemPromptstring nullable

Raw user instructions (no business context appended).

missionstring nullable
profileUpdatedAtstring date-time
modelIdstring uuid nullable
directModelIdstring nullable
llmKeyIdstring uuid nullable

Set for a BYOK agent (company LLM provider key); null for the platform key.

harnessIdstring uuid nullable
engine'openclaw' | 'hermes' | 'opencode' required
status'active' | 'completed' | 'paused' | 'provisioning' | 'unresponsive' | 'failed' required
agentAuthTokenHashstring nullable
agentAuthIssuedAtstring date-time nullable
agentAuthLastUsedAtstring date-time nullable
startDatestring date-time required
activatedAtstring date-time nullable
endDatestring date-time nullable
lastHeartbeatAtstring date-time nullable
lastReadAtstring date-time nullable
engineVersionstring nullable
engineImagestring nullable
engineRequestedVersionstring nullable
upgradingAtstring date-time nullable
upgradeRequestedAtstring date-time nullable
upgradeStatus'requested' | 'running' | 'succeeded' | 'failed' nullable
upgradeErrorstring nullable
provisioningErrorstring nullable
pausedAtstring date-time nullable
pausedReasonstring nullable
clientContextstring nullable

Per-agent "contexte business" free text.

createdAtstring date-time required

Changes

No recorded changes to this operation across all 2 revisions of this API.