Zirkles

API

What it is

A web API for your own scripts and tools. It does what the MCP server does for your assistant, for your account: make a Drop, save a link, read your library, check a link. Your plan, your coins and your limits are the same as on the website.

It is for servers and scripts. It does not work from a web page in a browser.

Get a key

  1. Sign in and open Settings.
  2. Under API keys, give the key a name. Switch on writing only if the script needs to make or change things; the default is read only.
  3. Copy the key when it is shown. It is shown once; Zirkles only keeps a fingerprint of it. Revoke it in Settings if it leaks.

Your first request

Send the key as a Bearer token. The answer is JSON with the result as text:

export ZIRKLE_API=https://lsjimakbumovwrrxbxrj.supabase.co/functions/v1/api
export ZIRKLE_API_KEY=zk_your_key_here

curl -s "$ZIRKLE_API/v1/account" \
  -H "Authorization: Bearer $ZIRKLE_API_KEY"

Make a Drop

Writing routes take a JSON body and need a key that may write. A Drop costs Gold, as everywhere:

curl -s "$ZIRKLE_API/v1/drops" \
  -H "Authorization: Bearer $ZIRKLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-script-2026-11-06-a" \
  -d '{"urls": ["https://www.youtube.com/watch?v=VIDEO_ID"]}'

Read your library

Reading routes take their options in the address:

curl -s "$ZIRKLE_API/v1/library?limit=5" \
  -H "Authorization: Bearer $ZIRKLE_API_KEY"

Routes

  • GET /v1/account: your plan, coins and limits.
  • GET /v1/zirkles: your Zirkles.
  • GET /v1/library and POST /v1/library: read your Saves, save a link.
  • POST /v1/drops: make a Drop. GET /v1/drops: search published Drops. GET /v1/drops/ID: read one Drop.
  • POST /v1/analyses: analyze one video. GET /v1/runs/ID: the status of a run.
  • POST /v1/queue: your queued Drops and Saves, marked as picked up.
  • POST /v1/checks: check a link with Link pls.
  • POST /v1/ratings: rate a Drop or a check. Rating is free.
  • GET /v1/openapi.json: the full description of every route and field, for code generators. It needs no key.

Repeating a request safely

On a writing route, add an Idempotency-Key header (8 to 128 letters, digits, dashes or underscores). Send the same request again with the same key within 24 hours and you get the first answer back, with the header Idempotent-Replay: true, and nothing is charged twice. The same key with a different request is refused with 409.

Errors

An error is JSON with a code and a sentence, for example {"code": "no_credits", "error": "..."}.

  • 400 bad_request: the request is invalid; the message names the field.
  • 401 invalid_key: the key is missing, wrong or revoked.
  • 402 daily_limit or no_credits: not enough coins for this. Nothing was used.
  • 403 forbidden_scope: the key is read only, but the route changes things. 403 forbidden: the app or tool is switched off in Settings.
  • 404 not_found: there is no such item that you can see.
  • 409 idempotency_conflict: the Idempotency-Key was used for a different request, or the first request is still running.
  • 429 rate_limited: too many requests; wait the seconds in the Retry-After header.

Limits

Requests are limited per account and per key. A wrong key is also counted against the network it came from, so guessing keys does not get far.