Run an agent

curl --request POST \
  --url https://api.sigmora.org/v1/agent/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "goal": "Turn this week’s lesson into a narrated video and a thumbnail for YouTube.",
  "projectId": "prj_9x2a4c",
  "capabilities": [
    "video.render",
    "image.thumbnail"
  ],
  "maxSteps": 2,
  "maxCredits": 600
}
'

import requests

url = "https://api.sigmora.org/v1/agent/runs"

payload = {
    "goal": "Turn this week’s lesson into a narrated video and a thumbnail for YouTube.",
    "projectId": "prj_9x2a4c",
    "capabilities": ["video.render", "image.thumbnail"],
    "maxSteps": 2,
    "maxCredits": 600
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    goal: 'Turn this week’s lesson into a narrated video and a thumbnail for YouTube.',
    projectId: 'prj_9x2a4c',
    capabilities: ['video.render', 'image.thumbnail'],
    maxSteps: 2,
    maxCredits: 600
  })
};

fetch('https://api.sigmora.org/v1/agent/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "goal": "<string>",
  "status": "done",
  "steps": [
    {}
  ],
  "creditsSpent": 123,
  "maxCredits": 123,
  "projectId": "<string>",
  "plan": "<unknown>"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

Run an agent

Describe an outcome; receive a bounded plan of capabilities, executed. An agentic endpoint over the priced catalogue. A planner composes steps from the capabilities you allowlist; EVERY step executes through the same metered path, at the same public prices, as a direct call — itemized in the response. Cost is bounded, not estimated: maxCredits is enforced before every step. Free to plan; each executed step bills exactly what that capability bills.

POST

agent

runs

Run an agent

curl --request POST \
  --url https://api.sigmora.org/v1/agent/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "goal": "Turn this week’s lesson into a narrated video and a thumbnail for YouTube.",
  "projectId": "prj_9x2a4c",
  "capabilities": [
    "video.render",
    "image.thumbnail"
  ],
  "maxSteps": 2,
  "maxCredits": 600
}
'

import requests

url = "https://api.sigmora.org/v1/agent/runs"

payload = {
    "goal": "Turn this week’s lesson into a narrated video and a thumbnail for YouTube.",
    "projectId": "prj_9x2a4c",
    "capabilities": ["video.render", "image.thumbnail"],
    "maxSteps": 2,
    "maxCredits": 600
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    goal: 'Turn this week’s lesson into a narrated video and a thumbnail for YouTube.',
    projectId: 'prj_9x2a4c',
    capabilities: ['video.render', 'image.thumbnail'],
    maxSteps: 2,
    maxCredits: 600
  })
};

fetch('https://api.sigmora.org/v1/agent/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "goal": "<string>",
  "status": "done",
  "steps": [
    {}
  ],
  "creditsSpent": 123,
  "maxCredits": 123,
  "projectId": "<string>",
  "plan": "<unknown>"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": "<string>",
  "code": "invalid_request",
  "details": "<unknown>",
  "requestId": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

A workspace API key.

Body

application/json

goal

string

required

The outcome you want, in prose. The planner composes catalogue capabilities toward it.

Required string length: 8 - 2000

projectId

string

required

Existing project that will own every step. Create it with POST /v1/projects first.

Required string length: 1 - 200

capabilities

enum<string>[]

required

The ONLY capabilities the planner may use, given with their request schemas. Required: an unbounded toolbox means an unbounded prompt and an unbounded bill.

Required array length: 1 - 6 elements

Available options:

video.analyze,

text.script,

text.adapt,

text.localize,

text.packaging,

text.article,

video.moments,

video.remix,

text.copywrite,

text.research,

text.paraphrase,

text.questions,

text.solve,

text.film,

image.thumbnail,

audio.music,

video.render,

video.shorts,

3d.from_text,

3d.from_image

maxCredits

integer

required

Hard bound on total credits this run may take. Checked before every step against the step's price for the arguments it was planned with (what the same direct call charges, e.g. a remix is priced per url source) plus actual spend so far; exceeding it stops the run with status: "capped" rather than overspending. A capability priced from inputs resolved during the call (such as a transcript fetched by assetId) is checked at its catalogue floor, so that one started step may exceed it.

Required range: 1 <= x <= 5000

maxSteps

integer

default:3

Maximum number of capabilities the planner may execute in this run. Defaults to 3 and may not exceed 5, keeping latency and credit spend bounded.

Required range: 1 <= x <= 5

Response

Success.

success

boolean

required

goal

string

required

status

enum<string>

required

Available options:

done,

capped,

empty_plan,

failed

steps

object[]

required

Show child attributes

creditsSpent

number

required

maxCredits

number

required

projectId

string

required

plan

any

{key}

any

Meta

Projects

Sessions

Assets

Jobs

Text

Video

UGC

Editing

3D

Image

Audio

Publishing

Webhooks

Workflows

Agents

Research

Themes

Signals

Discovery

Watchlist

Performance

Autopilot

Campaigns

Brands

Products

Run an agent

Authorizations

Body

Response