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

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

const response = await client.agents.signalAgentRun({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  agentId: process.env.OCTOSPARK_AGENT_ID ?? "agentId",
  runId: process.env.OCTOSPARK_RUN_ID ?? "runId",
  body: {},
})
{
  "signalId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "runId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "duplicate": true
}

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 when retrying the same signal after a lost response; the original signal is returned and nothing is stored twice.

Required string length: 1 - 255

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.

​
runId
string
required

Agent run id (UUID), as returned by the start/list runs endpoints.

Body

application/json
​
data
any
required

Event data from your system. It reaches the agent as untrusted data inside RUN_CONTEXT, never as instructions.

Response

Success

​
signalId
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}$
​
runId
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}$
​
delivery
enum<string>
required

before_first_step: the run is queued and reads it before its first step. next_step: the run is working and reads it at its next step boundary. resuming: the run is paused and reads it as its first turn after it resumes.

Available options:
before_first_step,
next_step,
resuming
​
duplicate
boolean
required

True when this idempotency key was already used for this run; the original signal is returned.