App attribution

Send these optional headers on POST /v1/runs to attribute the run to your app. The run object then carries app: { id, url, title }; without HTTP-Referer it is null.

Header	Value
`HTTP-Referer`	Your app’s URL, such as `https://studio.example`. Only its origin counts, and it identifies the app. Required for attribution.
`X-Spiral-Title`	The app’s display name, 1–64 printable characters.
`X-Spiral-Categories`	Up to 2 comma-separated categories from the list below.
`X-Spiral-App-Visibility`	`hidden` keeps the app off the public Apps ranking. It applies only to the request that creates the app.

curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://studio.example" \
  -H "X-Spiral-Title: Studio" \
  -H "X-Spiral-Categories: image-gen,video-gen" \
  -d '{"provider":"fal","model":"fal-ai/nano-banana-pro","input":{"prompt":"a red apple"}}'

Categories: image-gen, video-gen, audio-gen, speech, transcription, document-processing, web-search, web-scraping, social-media, marketing, ecommerce, education, game, agent, developer-tool, creative-tool. They add up across requests to at most 10 per app.
Your app, your changes: the organization that first sends a URL owns that app. Only its requests change the title or add categories; runs from other organizations are attributed to the same app without changing it.
Local development: localhost, IP addresses, .local and .internal hosts are private to your organization and never listed publicly.
Bad values never fail a run. A malformed URL, an over-long title or an unknown category is ignored, and the run is accepted without it.
A replay with the same Idempotency-Key returns the original run and its app, whatever headers the retry sends.
Public ranking: the Apps page of the console ranks public apps by completed runs today, this week and this month, updated every hour. It shows the URL, categories and run count, and the app’s host as its name until our team approves a title for it, because anyone can send a title for any URL. Your own runs always show the title you sent. The Rankings page ranks providers the same way.

Get started

Concepts

App attribution