Developers · Agents API

Give your service an agent.

Create Spiron agents and talk to them from any service over HTTPS at https://api.spiron.ai/v1. A message you send reaches the same agent, memory and inbox as its chat channels.

Base URL: https://api.spiron.ai/v1
Format: JSON over HTTPS
Authentication: Spiron API key
Contract: OpenAPI 3.1

On this page8 sections

01Overview
02Authentication
03Create an agent
04Send a message
05Webhooks
06MCP and A2A
07Retries and errors
08Read next

Overview

Agents, messages, tasks.

Every route, field and error is in the OpenAPI contract.

Agents: /v1/agents
Messages: /v1/agents/{id}/messages
Tasks: /v1/tasks/{id}
Interactions: /v1/interactions
Webhooks: /v1/webhooks
Contact directory: /v1/contact-directory/export

The contract is at https://api.spiron.ai/v1/openapi.json. Generate a client from it in any language.

Authentication

Send a Spiron API key with each request.

A key belongs to one workspace, holds the scopes it was made with, and acts with the standing of the person who made it.

API key scopes
Scope	Allows
`spiron:agents.read`	List and read agents, tasks, conversations and interactions
`spiron:agents.write`	Create, change and delete agents, send messages, manage webhooks
`spiron:approvals.decide`	Answer an agent's parked interactions
`spiron:approvals.withdraw`	Withdraw an agent's pending interaction without deciding it
`spiron:directory.read`	Export the whole contact directory. Only when named, never by default

Keep your key secret

Use the key only from your own server. Never put it in a web page, a mobile app, a screenshot, or a support ticket. Revoke a leaked key in Settings; it stops at once.

Create an agent

Name it and give it instructions.

An agent has a name, instructions (its system prompt), a model (or the workspace default), tools, and read-only channels.

create an agent

curl https://api.spiron.ai/v1/agents \
  -H "Authorization: Bearer $SPIRON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  --json '{"name": "Support", "instructions": "Answer billing questions briefly."}'

Send a message

Wait for the answer, stream it, or get it later.

A message opens a task. Name a conversation to keep a thread with the agent.

send and wait up to 60 seconds

curl https://api.spiron.ai/v1/agents/$AGENT_ID/messages \
  -H "Authorization: Bearer $SPIRON_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=60" \
  --json '{"conversation": "order-42", "content": "Has order 42 shipped?"}'

Ways to get the answer
Send	You get
`Prefer: wait=N`	The default (30 s, at most 120 s): 200 with the reply when the agent finishes in time, otherwise 202 with the task so far.
`Accept: text/event-stream`	Server-Sent Events: task.updated, message.completed, interaction.requested, interaction.resolved. Resume with Last-Event-ID at /v1/tasks/{id}/events.
`Prefer: respond-async`	202 at once. Read /v1/tasks/{id} later, or receive the replies at your webhooks.

Webhooks

Get replies pushed to your endpoint.

Subscribe an https endpoint. Every reply is POSTed as a Standard Webhook, signed with the secret you get once.

subscribe an endpoint

curl https://api.spiron.ai/v1/webhooks \
  -H "Authorization: Bearer $SPIRON_API_KEY" \
  --json '{"url": "https://example.com/spiron", "events": ["message.completed", "interaction.requested"]}'

Verify each delivery with any Standard Webhooks library and answer 2xx. A failed delivery is retried with the same webhook-id, so deduplicate on it.

MCP and A2A

Use your agents from other agents.

The same key works for both.

MCP server: https://api.spiron.ai/mcp
A2A Agent Card: https://api.spiron.ai/a2a/agents/{id}/.well-known/agent-card.json

Add the MCP server to any MCP client with an Authorization header, and its tools list your agents and message them. An A2A client reads an agent's card and sends it messages over JSON-RPC.

Retries and errors

Retry safely.

Errors are problem details (application/problem+json) with a stable code.

Common API errors
Status	What happened	What to do
`400`	The request was malformed	Fix the request. Retrying the same input will not help.
`401`	Missing, invalid or revoked key	Send a valid Spiron API key.
`403`	The key lacks a scope, or its creator lacks the standing	Use a key with the scope the error names.
`404`	Not found in your workspace	Check the id, and that it belongs to your workspace.
`409`	Conflicts with the current state, or the same Idempotency-Key is still running	Fetch the latest state, then decide whether to retry.
`422`	The Idempotency-Key was used for a different request	Use a new key for a new request.
`429`	Over the key’s rate: a burst of 60, then 10 requests a second	Wait for Retry-After, then retry.
`5xx`	A temporary problem on our side	Retry with backoff and the same Idempotency-Key.

Send an Idempotency-Key on every POST. A retry with the same key and body gets the first response back (with Idempotent-Replayed: true) for 24 hours, and a retried message reaches the agent once.

Keep building.

Next step

Create an API key.

A workspace owner or admin creates keys in Settings. The key is shown once.

Open Settings Start the quickstart