Agent definitions API

An agent definition is the saved recipe for an agent: which Amara model it runs on, the instructions it follows, the tools, skills and MCP servers it may use, and the limits it works within. The Agent definitions API lets you create, read, change and retire these recipes with an API key, so agents can live in source control and be deployed from CI the same way the rest of your stack is.

The API uses the same schema the Console’s AI Agents area uses. An agent created through the API appears in the Console, and an edit made in the Console shows up in the API as a new version. There is one source of truth, not two copies kept in sync.

A definition does nothing on its own. To put an agent to work you start a session with it, or schedule one with a deployment.

When to use it

Endpoints

Base URL: https://app.syntic.ai/v1 (see API host).

Authentication: a private inference key, Authorization: Bearer sk_live_.... Keys belong to one workspace; an agent belongs to the workspace of the key that created it, and keys from other workspaces cannot see it.

Headers while in preview: syntic-beta: agents-2026-11-01. Requests without it get 400 invalid_request with code beta_required. See Versioning and beta flags.

Who may write: any key in the workspace may read agents. Creating, changing, archiving and deleting need a key whose creator holds the Developer role or higher in the organization. Turning on tools marked approval required follows the same rule as the Console: only Administrators and Owners may enable them.

The agent object

{
  "id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "type": "agent",
  "name": "refund-desk",
  "description": "Handles refund requests from the support inbox.",
  "version": 4,
  "status": "active",
  "model": "Amara S1.2",
  "instructions": "You handle refund requests for Acme Store. ...",
  "tools": [
    { "type": "function", "function": { "name": "lookup_order", "description": "...", "parameters": { "type": "object", "properties": { "order_id": { "type": "string" } }, "required": ["order_id"] } } },
    { "type": "syntic_web_search", "max_uses": 3 }
  ],
  "tool_policy": {
    "default": "allow",
    "require_approval": ["issue_refund"]
  },
  "mcp_servers": [
    { "name": "crm", "url": "https://mcp.example.com/crm", "vault_secret": "crm-token", "allowed_tools": ["find_customer"] }
  ],
  "skills": [{ "skill_id": "skl_01JB9...", "version": "latest" }],
  "environment_id": null,
  "memory_store_ids": ["mem_01JC1..."],
  "vault_ids": ["vlt_01JC2..."],
  "limits": {
    "max_turns": 40,
    "max_output_tokens_per_turn": 4096,
    "session_token_budget": 400000,
    "session_cost_budget_usd": 2.0
  },
  "metadata": { "team": "support" },
  "created_at": "2026-11-03T09:14:22Z",
  "updated_at": "2026-11-05T16:02:10Z"
}

Versions

Each PATCH that changes at least one field produces a new version with the next integer. A PATCH that changes nothing returns the current version and does not create a new one.

• New sessions use the latest version unless they name one with agent_version.
• Running sessions keep the version they started with until they end.
• Versions are immutable. You cannot edit or delete a single version, only the whole agent.

Pinning sessions to a version and moving the pin in a deploy step gives you a clean rollback: point back to the previous number.

Create an agent

POST /v1/agents

Request body

Send an Idempotency-Key header to make retries safe: a repeated key within 24 hours returns the first result instead of creating a second agent.

Response

201 Created with the agent object, version: 1.

curl -sS https://app.syntic.ai/v1/agents \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Idempotency-Key: create-refund-desk-001" \
  -d '{
    "name": "refund-desk",
    "model": "Amara S1.2",
    "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Fetch an order by its id.",
        "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}
      }
    }],
    "limits": {"max_turns": 30}
  }'

const res = await fetch('https://app.syntic.ai/v1/agents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
    'syntic-beta': 'agents-2026-11-01',
    'Idempotency-Key': 'create-refund-desk-001',
  },
  body: JSON.stringify({
    name: 'refund-desk',
    model: 'Amara S1.2',
    instructions: 'You handle refund requests for Acme Store. Look the order up before answering.',
    tools: [{
      type: 'function',
      function: {
        name: 'lookup_order',
        description: 'Fetch an order by its id.',
        parameters: { type: 'object', properties: { order_id: { type: 'string' } }, required: ['order_id'] },
      },
    }],
    limits: { max_turns: 30 },
  }),
})
const agent = await res.json()
if (!res.ok) throw new Error(`${agent.error.code}: ${agent.error.message}`)
console.log(agent.id, agent.version)

import os, requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/agents",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "agents-2026-11-01",
        "Idempotency-Key": "create-refund-desk-001",
    },
    json={
        "name": "refund-desk",
        "model": "Amara S1.2",
        "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
        "tools": [{
            "type": "function",
            "function": {
                "name": "lookup_order",
                "description": "Fetch an order by its id.",
                "parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]},
            },
        }],
        "limits": {"max_turns": 30},
    },
)
resp.raise_for_status()
agent = resp.json()
print(agent["id"], agent["version"])

Update an agent

PATCH /v1/agents/{agent_id}

Include just the fields being changed. Arrays (tools, skills, mcp_servers and so on) are replaced whole, not merged. metadata is merged key by key; set a key to null to remove it.

To avoid overwriting someone else’s change, send if_version with the version you last read. If the agent has moved on, the call fails with 409 and code version_conflict; read it again and reapply your change.

curl -sS -X PATCH https://app.syntic.ai/v1/agents/agt_01JC4R8W6Q2N9X3T5V7Y \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: agents-2026-11-01" \
  -d '{"if_version": 4, "model": "Amara Deep"}'

The response is the agent object at its new version (200 OK).

List agents

GET /v1/agents

{
  "data": [{ "id": "agt_01JC4R8W6Q2N9X3T5V7Y", "type": "agent", "name": "refund-desk", "version": 4, "status": "active", "...": "..." }],
  "has_more": false,
  "first_id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "last_id": "agt_01JC4R8W6Q2N9X3T5V7Y"
}

Archive and delete

• POST /v1/agents/{agent_id}/archive sets status to archived. New sessions and deployments referencing the agent are refused with 409 agent_archived. POST /v1/agents/{agent_id}/unarchive reverses it.
• DELETE /v1/agents/{agent_id} only works on an archived agent with no running sessions, and removes every version. Execution records keep the agent id and name so history stays readable. Returns {"id": "...", "type": "agent_deleted"}.

Errors

All errors use the error envelope:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_tool_schema",
    "message": "tools[0].function.parameters is not a valid JSON Schema object.",
    "param": "tools[0].function.parameters"
  },
  "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d"
}

Limits

Creating and editing definitions is free. Tokens are billed when sessions run.

Build notes for the platform team

• Reuse the Console’s agent table; add a version column and an append-only versions table rather than a second schema.
• Every write produces an audit event (agent.created, agent.updated, agent.archived, agent.deleted) with the key id as actor.
• Validate tool schemas with the same validator used by strict tools so both paths reject the same inputs.
• Never return vault secret values or MCP tokens in any agent response.

Related

• Sessions: run an agent.
• Scheduled and triggered runs
• Environments, Memory stores, Credential vaults
• Tool calling