Agents

Create Agent

POST/v2/agents

Request Body

titlestringrequired

instructionsstringoptional

runtime_kindstringoptional

machine_kindstringoptional

mcp_serversobjectoptional

MCP server entries. Omit or null for none.

skillsobjectoptional

Skill declarations. Omit or null for none.

secretsobjectoptional

Agent secrets, planted into every sandbox env as plain env vars. Backed by the brainbase platform — same store the CLI syncs via `brainbase agent pull`. Omit or null for none.

descriptionobjectoptional

Optional freeform description, stored on the agent row.

metadataobjectoptional

Freeform string→string labels stored on the agent. Filter the list endpoint with repeated ?metadata=key:value params. Omit or null for none.

default_modelobjectoptional

Default model id, stored in kafka_profiles.preferences.default_model (what the kafka-v2 client reads as the agent's model). Overrides a template's source_model when both are set.

group_idobjectoptional

If set, the new agent is also granted to this group via agent_group_access — making it visible to every member of the group. Caller must already be a member of the group.

template_slugobjectoptional

Instantiate from an agent template, given as "creator/slug" (e.g. "acme/resume-reviewer-agent"). The template supplies instructions, runtime, model, mcp_servers and skills; the caller still provides title, group_id, and secret VALUES (the template only declares secret placeholders). Fields set explicitly on this body override the template. There is no separate instantiate endpoint — this is the one creation path.

Request

curl --request POST \
  --url https://api.brainbaselabs.com/v2/agents \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "instructions": "",
  "runtime_kind": "claude_code_cloud",
  "machine_kind": "daytona",
  "mcp_servers": [
    {
      "name": "string",
      "url": "string",
      "command": "string",
      "args": [
        "string"
      ],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "is_enabled": true
    }
  ],
  "skills": [
    {
      "source": "string"
    }
  ],
  "secrets": {
    "property1": "string",
    "property2": "string"
  },
  "description": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "default_model": "string",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "template_slug": "string"
}'

Response

json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "owner_user_id": "65139110-7c3c-4777-b692-80c218be3b9d",
  "title": "string",
  "instructions": "string",
  "runtime_kind": "string",
  "machine_kind": "string",
  "mcp_servers": [
    {
      "name": "string",
      "url": "string",
      "command": "string",
      "args": [
        "string"
      ],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "is_enabled": true
    }
  ],
  "skills": [
    {
      "source": "string"
    }
  ],
  "secrets": {
    "property1": "string",
    "property2": "string"
  },
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "created_at": "2019-08-24T14:15:22Z"
}