Automatio API

Quickstart

Create a key on the Integrations page, then make your first call. This one pulls the full transcript of a YouTube video:

curl -X POST 'https://automatio.ai/api/v1/query' \
  -H 'Authorization: Bearer aut_yourkey' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"youtubeGetTranscript","params":{"videoId":"jNQXAC9IVRw"}}'

The tool's result is returned directly — there is no response envelope to unwrap:

{
  "videoId": "jNQXAC9IVRw",
  "segmentCount": 6,
  "wordCount": 39,
  "segments": [
    { "t": 1, "ts": "0:01", "text": "All right, so here we are, in front of the elephants" },
    { "t": 5, "ts": "0:05", "text": "the cool thing about these guys is that they have really..." }
  ]
}

Authentication

Every request takes the same bearer key, whichever endpoint you use. At creation a key can be scoped to specific tools, specific models, a lifetime credit budget, and a per-minute rate limit.

Authorization: Bearer aut_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scope keys narrowly when you hand one to an agent or a third party. A tool allowlist is not only a safety boundary — it also shrinks what an MCP client has to load, since tools/list returns only the granted subset.

REST endpoint

POST https://automatio.ai/api/v1/query

curl -X POST 'https://automatio.ai/api/v1/query' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"tool":"web_search","params":{"query":"hello world"}}'

MCP server

A stateless Model Context Protocol server (Streamable HTTP) at https://automatio.ai/api/v1/mcp. Point any MCP client at it with the same bearer key and the tools appear natively in your agent — tools/list returns exactly what the key is granted, so out-of-scope tools never enter the session at all.

claude mcp add --transport http automatio https://automatio.ai/api/v1/mcp \
  --header "Authorization: Bearer aut_yourkey"

# or commit it to the project — .mcp.json in the repo root:
{
  "mcpServers": {
    "automatio": {
      "type": "http",
      "url": "https://automatio.ai/api/v1/mcp",
      "headers": { "Authorization": "Bearer aut_yourkey" }
    }
  }
}

The shapes genuinely differ between clients — VS Code nests under servers rather than mcpServers, opencode uses mcp with type: "remote", and Codex is TOML whose bearer_token_env_var wants the NAME of an environment variable rather than the key. A config copied from the wrong client usually fails silently — the server simply never appears.

Discovery is free. Connecting, and listing tools, costs nothing — only an actual tools/call is billed, at the same per-tool credit price as REST. The legacy SSE transport is intentionally not supported.

For coding agents that would rather read one document than negotiate a protocol, the whole API is available as Markdown in a single request at /api/v1/catalog?format=md.

AI models (OpenAI-compatible)

Call any chat model through Automatio and have the tokens billed to your credits — no provider keys to manage. Your key needs the AI models scope. The endpoint is wire-compatible with the OpenAI Chat Completions API, so the official OpenAI SDK works unchanged — just point it at Automatio.

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://automatio.ai/api/v1',
  apiKey: 'aut_yourkey',
});

const res = await client.chat.completions.create({
  model: 'google/gemini-3-flash',
  messages: [{ role: 'user', content: 'Hello' }],
});

Streaming is supported (stream: true). A key can be restricted to specific models at creation.

Images (vision)

Models marked vision below accept image input — captioning, OCR, reading a screenshot or a chart. Send it exactly the way the OpenAI API does, as a content array with an image_url part (an https URL or a data: URI). Images are accepted only on user messages; sending one to a text-only model returns 400 naming the models that do accept them.

const res = await client.chat.completions.create({
  model: 'zai/glm-4.6v-flash',
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Caption this image.' },
      { type: 'image_url', image_url: { url: 'https://example.com/photo.jpg' } },
    ],
  }],
});

For a one-call version that picks the model for you, the image_analyze tool does the same job through /api/v1/query and MCP.

Agent runs

Give Automatio a goal and it does the work — routing to the right agents, calling tools, running multi-step — then returns the result. Your key needs the Agent runs scope. idempotencyKey is required: a run takes real actions, so a retry must never start a second one — the same key always returns the same job.

curl -X POST https://automatio.ai/api/v1/agent \
  -H "Authorization: Bearer aut_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Research the top 5 AI coding tools and summarize them",
    "idempotencyKey": "req-2026-07-29-001"
  }'

Returns 202 with a jobId. Poll it for status, result and spend (add "wait": true to block until it finishes instead):

curl https://automatio.ai/api/v1/agent/{jobId} \
  -H "Authorization: Bearer aut_yourkey"

# { "status": "running" | "awaiting_input" | "completed" | "failed" | "cancelled",
#   "result": "...", "creditsSpent": 126 }

Start a run with "mode": "interactive" and it can pause to ask you something. The job then reports awaiting_input along with the question, and you answer it — the same run continues, nothing is lost:

curl -X POST https://automatio.ai/api/v1/agent/{jobId}/answer \
  -H "Authorization: Bearer aut_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "feedback": "Keep it under 500 words"}'

Follow-ups. The start response returns a conversationId. Send it back on a later call — with a fresh idempotencyKey — and that turn runs in the same conversation, so the agent still has the earlier context. Omit it for a one-off.

curl -X POST https://automatio.ai/api/v1/agent \
  -H "Authorization: Bearer aut_yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Now dig deeper on the third one",
    "conversationId": "<the id from the first call>",
    "idempotencyKey": "req-2026-07-30-002"
  }'

One run per conversation at a time — a follow-up sent while a run is still going returns 409, and polling always reflects the latest turn. The credit limit on the key caps the whole job — counted across every turn of a conversation, not per turn — on top of your account balance. Once a conversation has spent its ceiling, the next turn is refused with 402 before it starts, and the response tells you both creditsSpent and ceilingCredits.

Long conversations. Every turn sends the whole conversation to the model, so cost grows as one gets longer. Pass historyTurnLimit to send only the most recent N turns. Leave it off — the default — and the agent sees everything, which is what makes follow-ups work; lower it only when the task genuinely does not reach further back.

Errors

Failures return a JSON body with an error string. Over MCP the same conditions come back as a tool result with isError: true rather than a transport-level failure.