SuperCoolDocs Get an API key
Menu

Get started

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.

View as Markdown

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, or get a webhook. When the message is final, its files hold signed download links.

Getting 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 and through the MCP server. 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.
  • 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)
Format JSON requests and responses
Request ids Every response has a Request-Id header (req_…)
Errors One shape: {"error", "message", "request_id", "docs"} (Errors)
Retries Idempotency-Key header (Idempotency)
Pricing The same credits as the app; talking to the agent is free (Credits)
Versioning The version is in the path (/v1). Changes are listed in the 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

Last updated