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

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

const response = await client.agents.startAgentRun({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  agentId: process.env.OCTOSPARK_AGENT_ID ?? "agentId",
  body: {},
})
{
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "chatSessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
idempotency-key
string

Reuse this key with the same request after a lost response. The run it admitted is returned instead of starting another.

Required string length: 1 - 200

Path Parameters

​
teamId
string
required

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

​
agentId
string
required

Managed agent id (UUID), as returned by the list/create agents endpoints.

Body

application/json
​
prompt
string

The user message the run starts from. Omit to run the version's instructions alone.

Required string length: 1 - 20000
​
overrides
object

Per-run overrides applied on top of the pinned version: a different curated model, a publish mode and/or a shorter time limit for this run only. Omit to run the version as published.

Response

Success

​
runId
string<uuid>
required

The agent_runs row; poll GET runs/{runId} for status and cost.

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}$
​
agentVersionId
string<uuid>
required

The version the run pinned.

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}$
​
chatSessionId
string<uuid>
required

The chat session hosting the run.

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}$
​
sessionId
string<uuid>
required

The client-facing session id the run streams under (agent session routes).

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}$