> ## Documentation Index > Fetch the complete documentation index at: https://docs.sigmora.org/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /v1/agent/runs openapi: 3.1.0 info: title: Sigmora API version: 1.0.0 description: >- The priced, versioned public API. Every call authenticates with a workspace API key (`Authorization: Bearer sk_live_…`), names the project it files its output under, and reports what it cost. `GET /v1/capabilities` answers what this deployment can serve right now and at what price; anything it reports as unavailable answers 503 `capability_unavailable` rather than 404. servers: - url: https://api.sigmora.org security: - bearerAuth: [] tags: - name: Meta description: What this deployment serves, what it costs, and what you have spent. - name: Projects description: The container every capability files its output under. - name: Sessions description: Durable bindings between an external harness session and one project. - name: Assets description: 'Project media: direct-to-storage uploads, imports, ingest and transcripts.' - name: Jobs description: Where every asynchronous capability is collected, whatever produced it. - name: Text description: Scripts, research, articles, translation and question sets. - name: Video description: Narrated renders, footage edits, shorts and moment selection. - name: UGC description: >- Creator-led vertical videos: AI creators, their faces and voices, frames and clips. - name: Editing description: >- Sigma, the editor: conversational turns, granular transcript edits, approvals. - name: 3D description: Animated 3D renders from a description or a photograph. - name: Image description: Thumbnails, sized for the platform they are posted to. - name: Audio description: Generated music and audio engineering in Audiotool projects. - name: Publishing description: Connected destinations and queued posts. - name: Webhooks description: Signed, at-least-once delivery of job and publishing events. - name: Workflows description: Context snapshots, versioned recipes, costed proposals and their runs. - name: Agents description: Describe an outcome and let a bounded plan of capabilities run. - name: Research description: >- Observed hooks, creator outliers and production briefs from saved analyses. - name: Themes description: The canonical content taxonomy, and the niche profiles built on it. - name: Signals description: Evidence-backed trends and scored viral content. - name: Discovery description: Compiled watch plans, their runs, and source freshness. - name: Watchlist description: 'Accounts you watch: their usual reach and the posts that beat it.' - name: Performance description: Your own channels' videos against their usual, and fixes to live videos. - name: Autopilot description: The durable trend-to-distribution workflow and its checkpoints. - name: Campaigns description: Distribution records shared by the API, the dashboard and autopilot. - name: Brands description: >- Cross-platform identities with their own voice, rules and publishing commitments. - name: Products description: What a campaign promotes. paths: /v1/agent/runs: post: tags: - Agents summary: Run an agent description: >- 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. operationId: postAgentRuns requestBody: required: true content: application/json: schema: type: object properties: goal: type: string minLength: 8 maxLength: 2000 description: >- The outcome you want, in prose. The planner composes catalogue capabilities toward it. projectId: type: string minLength: 1 maxLength: 200 description: >- Existing project that will own every step. Create it with POST /v1/projects first. capabilities: minItems: 1 maxItems: 6 type: array items: type: string enum: - 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 description: >- The ONLY capabilities the planner may use, given with their request schemas. Required: an unbounded toolbox means an unbounded prompt and an unbounded bill. maxSteps: default: 3 description: >- 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. type: integer minimum: 1 maximum: 5 maxCredits: type: integer minimum: 1 maximum: 5000 description: >- 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: - goal - projectId - capabilities - maxCredits example: 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 responses: '200': description: Success. content: application/json: schema: type: object properties: success: type: boolean const: true goal: type: string status: type: string enum: - done - capped - empty_plan - failed steps: type: array items: type: object propertyNames: type: string additionalProperties: {} creditsSpent: type: number maxCredits: type: number projectId: type: string plan: {} required: - success - goal - status - steps - creditsSpent - maxCredits - projectId additionalProperties: {} '400': description: 'Failure. `code` is one of: invalid_request.' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 'Failure. `code` is one of: unauthorized.' content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: 'Failure. `code` is one of: insufficient_credits, budget_capped.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 'Failure. `code` is one of: forbidden, origin_not_allowed.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 'Failure. `code` is one of: not_found.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: 'Failure. `code` is one of: conflict.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: 'Failure. `code` is one of: payload_too_large.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: 'Failure. `code` is one of: rate_limited.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: 'Failure. `code` is one of: upstream_error, internal_error.' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- Failure. `code` is one of: capability_unavailable, upstream_unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object required: - success - error - code properties: success: const: false error: type: string description: >- Human-readable. Copy may change between releases — do not match on it. code: type: string enum: - invalid_request - unauthorized - forbidden - origin_not_allowed - not_found - conflict - payload_too_large - insufficient_credits - budget_capped - content_not_cleared - rate_limited - capability_unavailable - upstream_unavailable - upstream_error - internal_error description: Stable machine-readable cause. Branch on this. details: description: Optional structured context, e.g. the credits shortfall. requestId: type: string description: >- Identifies this request in our logs. Include it when you contact support. timestamp: type: string format: date-time description: When the failure was produced. securitySchemes: bearerAuth: type: http scheme: bearer description: A workspace API key. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.