POST
/
v1
/
teams
/
{teamId}
/
agents
TypeScript client
import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.agents.createAgent({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  body: {},
})
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "slug": "<string>",
  "name": "<string>",
  "description": "<string>",
  "currentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currentVersion": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 123,
    "instructions": "<string>",
    "model": "<string>",
    "webSearch": true,
    "toolPolicy": {
      "allow": [
        "<string>"
      ],
      "deny": [
        "<string>"
      ]
    },
    "mediaPolicy": {
      "cta": {
        "mode": "none"
      },
      "forbidStock": true,
      "polishIterations": 2,
      "ctaEndSlide": true
    },
    "skillIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "mcpServerIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "perRunCreditCeilingDecimillicents": 1,
    "brandId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "maxRunMinutes": 180,
    "outputContract": {
      "mode": "text"
    },
    "createdBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "createdAt": "<string>",
    "maxPostsPerRun": 50
  },
  "archivedAt": "<string>",
  "isDefault": true,
  "createdBy": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "warnings": [
    "<string>"
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
teamId
string
required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

Body

application/json
​
name
string
required

Display name of the agent, 1-120 characters.

Required string length: 1 - 120
​
instructions
string
required

The agent's standing instructions. Appended to the platform system prompt as a delimited block on every run of this version.

Required string length: 1 - 40000
​
slug
string

Stable, url-safe identifier unique within the team (lower-case letters, digits and hyphens, 1-64 characters). Derived from the name when omitted.

Required string length: 1 - 64
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
Example:

"infographic-slideshows"

​
description
string | null

What the agent is for, shown in the agents list (up to 2000 characters); null clears it.

Maximum string length: 2000
​
model
enum<string>

Curated OpenRouter model id. Omit for the platform default agent model.

Available options:
google/gemini-3.8-flash,
anthropic/claude-opus-5.5,
openai/gpt-6-sol,
anthropic/claude-sonnet-5,
openai/gpt-6-luna,
x-ai/grok-4.7,
deepseek/deepseek-v4.1-flash,
qwen/qwen3.8-flash,
minimax/minimax-m3,
mistralai/mistral-small-2603,
moonshotai/kimi-k3,
xiaomi/mimo-v2.6-flash,
stepfun/step-3.7-flash,
google/gemini-3.7-flash,
anthropic/claude-opus-5,
openai/gpt-5.6-sol,
openai/gpt-5.6-terra,
x-ai/grok-4.6,
deepseek/deepseek-v4-flash-0731,
qwen/qwen3.7-plus,
moonshotai/kimi-k2.6,
xiaomi/mimo-v2.5,
google/gemini-3.5-flash,
anthropic/claude-opus-4.8,
google/gemini-3.1-pro-preview,
x-ai/grok-4.5
​
reasoning
enum<string> | null

Reasoning effort requested from the model on every run of this version; null keeps the model default.

Available options:
max,
xhigh,
high,
medium,
low,
minimal,
none
​
webSearch
boolean

Enable paid native web search by default for this agent. Requires a supported model and search tool permission. Defaults to false on creation; omit on update to keep the current setting.

​
toolPolicy
object

Tool visibility policy: allow and deny entry lists. Deny wins; an empty allow list means every tool not denied is visible. Omit on create for an unrestricted policy; on update the whole policy is replaced.

​
publishMode
enum<string>

auto: unattended runs may call schedule_post and post_now when the tool policy allows them. draft: unattended runs only file drafts for review.

Available options:
auto,
draft
​
mediaPolicy
object

Media policy passed through to the media runtime (image source, stock ban, polish passes, CTA end slide); null means no policy.

​
skillIds
string<uuid>[]

Team skill ids attached to this version; their names and descriptions are listed in the prompt and bodies load on demand via load_skill.

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
mcpServerIds
string<uuid>[]

Team remote MCP server ids attached to this version (reserved; the MCP server surface ships separately).

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
toolIds
string<uuid>[]

Team custom tool ids attached to this version. Each is offered to the model as custom__ (policy capability key custom, operation key custom.); the tool's current version is resolved when a run starts and pinned for that run.

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
perRunCreditCeilingDecimillicents
integer | null

Per-run credit ceiling in decimillicents; a run stops before the next model step once reached. null means the firing schedule's ceiling (or none for API runs).

Required range: x > 0
​
brandId
string<uuid> | null

Brand whose profile (voice, audience, topics) grounds every run of this version, and the default brandId for tools that take one. Must be one of the team's brands. null uses the team's primary brand at run time; a brand deleted later also falls back to the primary brand.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
maxPostsPerRun
integer

Maximum distinct content items produced by one run, including child runs. Cross-posting and revisions of the same item count once.

Required range: 1 <= x <= 100
​
maxRunMinutes
integer

Maximum cumulative execution time in minutes, including tool waits and excluding queueing, downtime and pauses. Defaults to 60; increasing it never increases credit ceilings.

Required range: 1 <= x <= 360
​
outputContract
object

How a version reports its result. text keeps the free-text answer; json_schema requires a JSON object matching the schema. Managed and scheduled runs without a json_schema contract report with the platform default run report schema.

Response

Success

​
id
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
teamId
string<uuid>
required

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
slug
string
required

Stable, url-safe identifier unique within the team (lower-case letters, digits and hyphens, 1-64 characters). Derived from the name when omitted.

Required string length: 1 - 64
Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
Example:

"infographic-slideshows"

​
name
string
required

Display name of the agent, 1-120 characters.

Required string length: 1 - 120
​
description
string | null
required

What the agent is for, shown in the agents list (up to 2000 characters); null clears it.

Maximum string length: 2000
​
currentVersionId
string<uuid> | null
required

The version new runs pin. Null only transiently while the first version is being written.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
currentVersion
object
required

The current version, embedded so one read shows the live configuration.

​
archivedAt
string | null
required

When the agent was archived (ISO-8601 UTC); null while live.

​
bundledRole
enum<string> | null
required

Immutable platform role: general or slideshow for the two protected team agents; null for customer-created agents. Bundled agents remain editable but cannot be deleted or archived.

Available options:
general,
slideshow
​
isDefault
boolean
required

true for the team's protected General agent, provisioned with Slideshow when the team is created. It is used by chat and schedules that name no other agent. Its configuration is editable; its identity cannot be changed, deleted or archived.

​
createdBy
string<uuid> | null
required

Creator of this agent; null only for bundled agents provisioned by the system for an ownerless team.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
​
createdAt
string
required

When the agent was created (ISO-8601 UTC).

​
updatedAt
string
required

When the agent or its current version last changed (ISO-8601 UTC).

​
warnings
string[]

Advisory notes about the current version, returned by create and update (for example a tool policy that denies search_tools). Absent when there is nothing to flag.