API

The flow

Discover, price, render, get told. Each step is a separate call so you can stop after any of them.

1. 1

   Find the stories

   POST /stories with your columns and rows, or with text or a URL. Numbers go to the relational engine — thirteen scored relations over your fields. Prose goes to Arc, which finds the sequence. Two independent dials shape a prose story: angle is the stance (hype, proud, straight, skeptical, roast — which moments make the cut and who wins) and tone is the voice (how the lines sound). Roast needs selfSubject: true — your own film only. Both engines return a ranked list; you pick.

   Copy

   curl -X POST $BASE/stories \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{
       "business": "Freightline",
       "fields": [
         {"key":"deposits","role":"stock","unit":"usd","noun":"in deposits"},
         {"key":"sellers","role":"population","agents":"sellers"}
       ],
       "metrics": {"deposits": 48000, "sellers": 120}
     }'

2. 2

   Price it

   POST /estimate with a look and a fidelity. The number is a ceiling — the render bills min(quoted, actual), so a shot dropped by the prompt guard or a cached narration line makes it cheaper, never dearer.

   Copy

   curl -X POST $BASE/estimate \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{"fidelity":"standard","look":"noir"}'

3. 3

   Render it

   POST /render with the storyId you picked, on the monkeygun-story template. The film argues that exact story — the lines you read in step 1 are the lines it speaks, because the story is stored when you discover it rather than rebuilt when you film it. Pass a webhookUrl and we will tell you when it lands instead of making you poll.

   Copy

   curl -X POST $BASE/render \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{
       "template": "monkeygun-story",
       "storyId": "arc_9f2c1d40",
       "options": {"look":"noir","fidelity":"standard"},
       "webhookUrl": "https://yours.example/hook"
     }'

4. 3b

   Or film a chain

   Some films are formats rather than engine compositions. chain-metrics argues one ratio — stablecoins parked on a chain against TVL working in its DeFi, benchmarked against Ethereum. It reads two ways and both are true: a tight ratio says the money here works, a wide one says the capital is waiting for builders. Figures are pulled live from DefiLlama at render time and cited on screen with the date; if that read fails we refuse rather than ship last month's liquidity.

   Copy

   curl -X POST $BASE/render \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{"template":"chain-metrics","chainName":"aptos"}'

5. 3c

   Or cut it from your own footage

   Pull spans of your own video into a per-key clip library — POST /clips with attest: true per item, because we will not download footage you have not confirmed is yours. Label clips free at ingest or with a PATCH; or POST /clips/scan to have a model look and write the labels — quoted first (2 credits per ≤10s clip), spent only on confirm: true, and any label not written is refunded. For stills, GET /images/search answers from four pools — your library, your site, Pexels, the open web — each candidate carrying its license in plain words. Picked images ride into the render as a top-level assets object with rightsConfirmed: true; anything from the web pool also needs its own attest: true or the render refuses.

   Copy

   # find candidates across the four pools
   curl "$BASE/images/search?q=warehouse+robots&pools=library,site,pexels,web" \
     -H "authorization: Bearer $KEY"
   # → candidates tagged {pool, url, license, attribution?, requiresAttestation}
   
   # render with the images you picked — assets ride at the TOP LEVEL of the body
   curl -X POST $BASE/render \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{
       "template": "monkeygun-story",
       "storyId": "arc_9f2c1d40",
       "assets": {
         "assets": [
           {"url": "https://yours.example/product.jpg"},
           {"url": "https://found.example/shot.jpg", "source": "web", "attest": true}
         ],
         "rightsConfirmed": true
       }
     }'
   # rightsConfirmed must be the literal true, and every source:"web" image needs
   # its own attest: true — the render refuses otherwise, before any money moves

6. 4

   Buy credits

   Any amount from $10 to $5,000 per charge — the packs on /templates are quick-picks on the same ladder, not the only things for sale. Bonus tiers are published in the catalog so you never have to hardcode them: 10% from $15, 15% from $40, 25% from $100. Credits never expire.

   Copy

   curl -X POST $BASE/checkout \
     -H "authorization: Bearer $KEY" -H "content-type: application/json" \
     -d '{
       "kind": "credits",
       "usd": 250,
       "successUrl": "https://yours.example/ok",
       "cancelUrl": "https://yours.example/no"
     }'
   # → {"orderId":"...","checkoutUrl":"https://checkout.stripe.com/..."}

7. 5

   Publish it forever

   Register a feed, set a trigger, connect Buffer. When the feed changes and the condition fires, we discover a story from its latest numbers, film it, score it, and post it. Anything below the confidence threshold — or any feed you marked review-only — holds in /holds instead of publishing. PATCH a feed with {killed:true} to stop it dead.

   Copy

   # 1. the data source, and what its columns MEAN
   curl -X POST $BASE/feeds -H "authorization: Bearer $KEY" \
     -H "content-type: application/json" -d '{
       "url": "https://yours.example/metrics.json",
       "pollIntervalSec": 3600,
       "fieldMap": [{"key":"deposits","role":"stock","unit":"usd"}]
     }'
   
   # 2. what should make a film
   curl -X POST $BASE/feeds/fd_123/triggers -H "authorization: Bearer $KEY" \
     -H "content-type: application/json" -d '{
       "condition": {"key":"deposits","op":"increase_pct","value":20},
       "template": "monkeygun-story",
       "options": {"look":"noir","channelId":"YOUR_BUFFER_CHANNEL"}
     }'
   
   # 3. where it goes
   curl -X PUT $BASE/keys/me/buffer -H "authorization: Bearer $KEY" \
     -H "content-type: application/json" -d '{"token":"YOUR_BUFFER_TOKEN"}'
   curl $BASE/keys/me/buffer -H "authorization: Bearer $KEY"
   # → every channel the token reaches, with its service (twitter/linkedin/...)

8. 6

   Verify the webhook

   Every delivery carries X-Monkeygun-Signature as t=<unix>,v1=<hmac>. The HMAC is SHA-256 over `${t}.${rawBody}` with your webhook secret. The timestamp is inside the signed material, so a captured delivery cannot be replayed later. Compare in constant time and reject anything older than five minutes.

   Copy

   const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
   const expected = crypto.createHmac("sha256", secret)
     .update(t + "." + rawBody).digest("hex");
   const ok = crypto.timingSafeEqual(
     Buffer.from(expected, "hex"), Buffer.from(v1, "hex"),
   ) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Token films in one call

Token templates skip discovery — the subject is an address, not a story.

# 1) Catalog
curl -s https://api.monkeygun.com/v1/templates | jq '.templates[].id'

# 2) Card checkout (browser return URL)
curl -s -X POST https://api.monkeygun.com/v1/checkout \
  -H 'content-type: application/json' \
  -d '{
    "kind": "render",
    "template": "spotlight-clip",
    "chain": "solana",
    "tokenAddress": "<MINT>",
    "successUrl": "https://monkeygun.com/studio?order={ORDER_ID}",
    "cancelUrl": "https://monkeygun.com/studio"
  }'

# 3) Or with credits
curl -s -X POST https://api.monkeygun.com/v1/render \
  -H "authorization: Bearer sk_live_…" \
  -H 'content-type: application/json' \
  -d '{
    "template": "spotlight-clip",
    "chain": "solana",
    "tokenAddress": "<MINT>"
  }'