Managing Agents

Create, list, and provision agents programmatically with a personal key.

List Agents

GET /v1/agents

Returns a summary for each agent: id, name, status, widget settings, and allowed domains.

Create an Agent

Provide instructions and configuration. Set generate_runtime_key to receive a runtime key in the response so you can immediately run tasks.

Request:

POST /v1/agents
{
  "name": "Research Assistant",
  "description": "Competitor analysis on demand",
  "instructions": "Produce concise, sourced competitor reports.",
  "execution_mode": "balanced",
  "knowledge_bases": [],
  "skills": ["evidence-based-rag"],
  "tool_categories": ["basic", "file"],
  "suggested_prompts": ["Summarize the market"],
  "generate_runtime_key": true
}

Response:

{
  "agent": {
    "id": 42,
    "name": "Research Assistant",
    "status": "active",
    "execution_mode": "balanced",
    "knowledge_bases": [],
    "skills": ["evidence-based-rag"],
    "tool_categories": ["basic", "file"],
    "widget_enabled": false,
    "allowed_domains": []
  },
  "api_key": {
    "full_key": "xag_Ab3xY9_Qw7Rt2Kp9Lm4Nz8Vc1Bd6Hf5Jg0Xs3Tr",
    "key_prefix": "Ab3xY9",
    "created_at": "2026-06-23T12:00:00Z"
  }
}

Save the runtime key

The full_key is returned only once. Store it securely — you cannot retrieve it again later, only rotate it.

Create from a Template

POST /v1/agents/from-template
{
  "template_id": "marketing-content-agent",
  "name": "My Marketing Agent",
  "generate_runtime_key": true
}

Rotate a Runtime Key

POST /v1/agents/{agent_id}/api-key

Issues a fresh runtime key for the agent, invalidating the previous one.

Model ids

When you set the models field, known model slots must use integer model ids from your workspace's configured models.

Next Steps

Running Tasks →