Use SuperCool from AI agents

These docs are written to be read by AI agents as well as people. Point your coding agent at them, or skip the HTTP entirely and connect SuperCool as a tool.

#Docs for LLMs

Resource	URL
Index of every page (llms.txt)	`https://supercool.com/docs/llms.txt`
All docs in one Markdown file	`https://supercool.com/docs/llms-full.txt`
Any page as Markdown	Add `.md` to its URL, like `/docs/api/quickstart.md`
OpenAPI 3.1 spec	`/docs/api/openapi.json` or `.yaml`

Every page also has a Copy page as Markdown button at the top, and a <link rel="alternate" type="text/markdown"> tag pointing to its Markdown version.

#Connect SuperCool as a tool (MCP)

If your agent speaks the Model Context Protocol, connect SuperCool directly: no API key or HTTP code needed. Claude, ChatGPT, Cursor and other MCP clients sign in with your SuperCool account and get tools to message your agent, wait for results and read work.

Setup for each client is on the MCP page. The server URL is https://mcp.supercool.com/mcp.

#Use the CLI

The SuperCool CLI gives terminal agents (and you) the same agent from a shell:

bash

curl -fsSL https://supercool.com/install.sh | sh
supercool login
supercool ask "A 15 second vertical ad for my candle shop" --wait

It also installs with brew install famous-labs/tap/supercool or npm i -g @famous-labs/supercool-cli.

#A prompt snippet for coding agents

Paste this into your agent's system prompt, rules file or AGENTS.md when it builds on the SuperCool API:

text

You can use the SuperCool API: one AI agent behind one endpoint that makes finished work
(videos, images, websites, decks, research, writing) from a plain-language request.

Docs (Markdown): https://supercool.com/docs/llms.txt (index), https://supercool.com/docs/llms-full.txt (everything)
OpenAPI: https://supercool.com/docs/api/openapi.json

Essentials:
- Base URL https://api.supercool.com/v1. Auth header: "Authorization: Bearer $SUPERCOOL_API_KEY".
  The key is a server-side secret: read it from the environment, never hard-code it or send it to a browser.
- Send work: POST /v1/messages {"message": "..."} with a fresh "Idempotency-Key" header
  (reuse it on retries). Returns within ~30 s: 201 with a message {id, status, final, reply, jobs, files}.
- Follow it: GET /v1/messages/{id}?wait=30 in a loop until "final" is true
  (or use webhooks: POST /v1/webhooks, verify Standard Webhooks signatures).
- Statuses: processing, completed, needs_input (answer with a new message), blocked
  (reason out_of_credits: not an HTTP error; if "resume": "add_credits", don't resend),
  partial, failed, expired.
- Files: message.files[] has {file_id, name, content_type, size, url}; url is a signed, expiring link.
  Refresh with GET /v1/files/{file_id}. A 412 on download means the file changed: refresh.
- Errors: {"error": code, "message", "request_id", "docs"}. Branch on "error". Retry 429/500/503
  with backoff (honor Retry-After). Max 5 running jobs per account: beyond that the message still
  succeeds, but new work comes back as a blocked job with reason too_many_running and a "running" list.
- Don't pick models or chain tools: describe the outcome and let the SuperCool agent do the work.

#Tips for agents calling the API

Describe outcomes, not steps. "A 30 second teaser from this footage, upbeat, with captions" works better than instructions for which tool to use. The agent picks the tools.
Poll with wait, not in a tight loop. ?wait=30 returns as soon as something changes.
Stop on final. Don't resend a message that is blocked with resume: "add_credits": it resumes by itself once credits are added.
Answer questions. On needs_input, relay question to the user (or answer it) with a new message.
Keep the request_id from errors and the Request-Id header when you report a problem.