# Use SuperCool from AI agents

> Give coding agents and AI apps what they need to use SuperCool. llms.txt, every docs page as Markdown, the OpenAPI spec, the MCP server and the CLI.

Source: https://supercool.com/docs/api/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://llmstxt.org)) | [`https://supercool.com/docs/llms.txt`](https://supercool.com/docs/llms.txt) |
| All docs in one Markdown file | [`https://supercool.com/docs/llms-full.txt`](https://supercool.com/docs/llms-full.txt) |
| Any page as Markdown | Add `.md` to its URL, like [`/docs/api/quickstart.md`](https://supercool.com/docs/api/quickstart.md) |
| OpenAPI 3.1 spec | [`/docs/api/openapi.json`](https://supercool.com/docs/api/openapi.json) or [`.yaml`](https://supercool.com/docs/api/openapi.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](https://modelcontextprotocol.io), 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](https://supercool.com/mcp). The server URL is `https://mcp.supercool.com/mcp`.

## Use the CLI

The [SuperCool CLI](https://supercool.com/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.