# The SuperCool API

> One agent, one endpoint. Send SuperCool a plain-language message and get back finished work, like videos, images, sites, decks and research.

Source: https://supercool.com/docs/api

Most AI APIs give you a model. You pick one, write the prompt for it, chain the steps and stitch the outputs together yourself. The SuperCool API gives you an agent instead.

You send it a message in plain language, like "a 15 second vertical ad for my candle shop", "research my top five competitors" or "build me a landing page". The agent plans the work, picks and runs the tools, checks the result and hands back the finished files. There's no model to choose and no pipeline to build.

```bash
curl https://api.supercool.com/v1/messages \
  -H "Authorization: Bearer $SUPERCOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "A 15 second vertical ad for my candle shop, warm and cozy"}'
```

```json
{
  "id": "msg_3f9a1c2e7b8d4e5f6a7b8c9d",
  "status": "processing",
  "reply": "On it. I'm making a 15 second vertical ad with warm candlelight shots.",
  "jobs": [{ "job_id": "exe_9b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e", "title": "Candle shop vertical ad", "status": "running" }],
  "files": []
}
```

A few minutes later, `GET /v1/messages/msg_3f9a…` returns `"status": "completed"` and a signed link to `candle_ad.mp4`.

## What it can make

Anything you can ask for in the SuperCool app, you can ask for over the API:

- **Video:** ads, explainers, talking heads, short-form clips, with music and voiceover.
- **Images:** product shots, social posts, thumbnails, logos, edits of images you send.
- **Websites:** landing pages and small sites, hosted and live at a link.
- **Decks and documents:** presentations, reports, spreadsheets, PDFs.
- **Research:** multi-step web research with sources, competitor and market scans.
- **Writing and audio:** copy, scripts, emails, voiceovers and music.

The agent decides how to do the work. You describe the outcome you want.

## How it works

1. **You send a message** to `POST /v1/messages`, with optional files. The call returns within about 30 seconds.
2. **The agent answers and starts work.** A quick question gets a finished answer right away (`completed`). Bigger jobs come back as `processing`, with a `jobs` list that has one entry for each piece of work the agent started.
3. **You get the result.** Poll `GET /v1/messages/{id}?wait=30`, read its [events](https://supercool.com/docs/api/results#events), or get a [webhook](https://supercool.com/docs/api/webhooks). When the message is `final`, its `files` hold signed download links.

[Getting results](https://supercool.com/docs/api/results) explains every status in detail.

## One agent, everywhere

The API talks to the same agent you use in the SuperCool app, by phone, on WhatsApp, in the [CLI](https://supercool.com/cli) and through the [MCP server](https://supercool.com/mcp). It has the same memory, the same chats and the same credits.

- Work you start over the API shows up in the app, and every job has a `link` to its chat.
- Work you start in the app is visible to the API through [`GET /v1/work`](https://supercool.com/docs/api/work).
- You can follow up the way you would in a chat. "Make it 9:16 and add captions" continues the same work.

## The basics

| | Details |
|---|---|
| Base URL | `https://api.supercool.com/v1` |
| Auth | `Authorization: Bearer sc_key_…` ([Authentication](https://supercool.com/docs/api/authentication)) |
| Format | JSON requests and responses |
| Request ids | Every response has a `Request-Id` header (`req_…`) |
| Errors | One shape: `{"error", "message", "request_id", "docs"}` ([Errors](https://supercool.com/docs/api/errors)) |
| Retries | `Idempotency-Key` header ([Idempotency](https://supercool.com/docs/api/idempotency)) |
| Pricing | The same credits as the app; talking to the agent is free ([Credits](https://supercool.com/docs/api/credits)) |
| Versioning | The version is in the path (`/v1`). Changes are listed in the [changelog](https://supercool.com/docs/api/changelog). |

API keys are server-side secrets. The API sends no CORS headers, so it can't be called from a web page. Call it from your server, a script or a job.

## Next steps

- [Quickstart](https://supercool.com/docs/api/quickstart): send your first message and download the result.
- [Sending messages](https://supercool.com/docs/api/messages): files, follow-ups and questions from the agent.
- [Webhooks](https://supercool.com/docs/api/webhooks): skip polling and get told when work is done.
- [API reference](https://supercool.com/docs/api/reference): every endpoint and field.