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

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

const response = await client.agents.createAgentFromTemplate({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  templateSlug: process.env.OCTOSPARK_TEMPLATE_SLUG ?? "templateSlug",
})
{
  "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.

​
templateSlug
string
required

Template slug from the list agent templates endpoint (for example infographic-slideshows).

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.