Tokokino Developer Portal

Quickstart

Tokokino edits and exports entirely in the browser, so most of the product needs no API at all. The API covers the server-backed features: public share links, cloud drafts, custom presets, preferences, and a few media proxies.

Create a share by POSTing raw image bytes with a personal access token:

create-share.sh

curl -X POST https://tokokino.com/api/share \
  -H "Content-Type: image/png" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  --data-binary @screenshot.png

The response carries the public share URL, the stored image URL, and your remaining storage quota. The full request and response schemas live in the OpenAPI specification.

Authentication

API requests are authenticated with a personal access token. To create one:

1Sign in with Google at tokokino.com/login.
2Open the editor, click your profile icon at the bottom of the left sidebar, and choose Settings.
3Go to the Developer tab and click New token. Name it, and give it an expiry if you want one.
4Copy the token — it is shown once — and send it with your requests. Every example on this page shows where it goes.

A token acts as your account, so treat it like a password. You can revoke one at any time from the same screen.

Browser-based callers can use a better-auth session cookie instead: sign in at /login and send the resulting better-auth.session_token cookie with each request.

The authentication guide is published as Markdown for agent and MCP clients.

OpenAPI specification

The machine-readable contract is published at /openapi.json (also served at /api/openapi.json). It is OpenAPI 3.1, sent as application/json with Access-Control-Allow-Origin: *, so it can be loaded directly by generators and agents.

Endpoints

The most-used endpoints are listed here. The specification is the complete reference.

POST/api/share

Create a share link from image bytes

request.sh

curl -X POST https://tokokino.com/api/share \
  -H "Content-Type: image/png" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  --data-binary @screenshot.png

GET/api/share

List your shares and storage usage

request.sh

curl "https://tokokino.com/api/share" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

DELETE/api/share/{id}

Delete one share

request.sh

curl -X DELETE "https://tokokino.com/api/share/abc123" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

POST/api/share/uploads

Open a multipart upload for a video share

request.sh

curl -X POST "https://tokokino.com/api/share/uploads" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"contentType": "video/mp4", "sizeBytes": 104857600}'

POST/api/share/uploads/{id}/complete

Finalise a video share

request.sh

curl -X POST "https://tokokino.com/api/share/uploads/abc123/complete" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

Drafts

GET/api/drafts

List saved drafts

request.sh

curl "https://tokokino.com/api/drafts?limit=20" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

POST/api/drafts

Save a new draft

request.sh

curl -X POST "https://tokokino.com/api/drafts" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"name": "Landing hero", "state": {"schemaVersion": 1, "present": {"canvases": [{"id": "canvas-1"}]}}}'

GET/api/drafts/{id}

Fetch a draft with its full editor state

request.sh

curl "https://tokokino.com/api/drafts/abc123" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

PATCH/api/drafts/{id}

Rename a draft

request.sh

curl -X PATCH "https://tokokino.com/api/drafts/abc123" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"name": "Landing hero v2"}'

DELETE/api/drafts/{id}

Delete a draft

request.sh

curl -X DELETE "https://tokokino.com/api/drafts/abc123" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

Presets and preferences

GET/api/presets

List custom style presets

request.sh

curl "https://tokokino.com/api/presets" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

POST/api/presets

Create a custom style preset

request.sh

curl -X POST "https://tokokino.com/api/presets" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"name": "Hero split", "type": "style", "geometry": {"canvasTilt": {"rx": 0, "ry": 0, "rz": 0}, "canvasScale": 100, "slots": []}}'

GET/api/preferences

Read editor preferences

request.sh

curl "https://tokokino.com/api/preferences" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

PUT/api/preferences

Update editor preferences

request.sh

curl -X PUT "https://tokokino.com/api/preferences" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"exportFilenameFormat": "tokokino_export_{SCALE}_{DATE}"}'

Tokens

GET/api/tokens

List your personal access tokens

request.sh

curl "https://tokokino.com/api/tokens" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

POST/api/tokens

Generate a new personal access token

request.sh

curl -X POST "https://tokokino.com/api/tokens" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"name": "CI upload script", "expiresAt": null}'

DELETE/api/tokens/{id}

Revoke a personal access token

request.sh

curl -X DELETE "https://tokokino.com/api/tokens/abc123" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

Media

POST/api/screenshot

Capture a screenshot of a public URL

request.sh

curl -X POST "https://tokokino.com/api/screenshot" \
  -H "Authorization: Bearer tk_<your-personal-access-token>" \
  -H "Content-Type: application/json" \
  --data '{"url": "https://example.com", "width": 1920, "aspectRatio": "16:9"}'

GET/api/tweet

Fetch an X or Bluesky post for a mockup

request.sh

curl "https://tokokino.com/api/tweet?url=https://x.com/acme/status/123456789" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

GET/api/unsplash/search

Search Unsplash backgrounds

request.sh

curl "https://tokokino.com/api/unsplash/search?q=mountains" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

GET/api/export/image

CORS proxy for external images

request.sh

curl "https://tokokino.com/api/export/image?url=https://example.com/photo.jpg" \
  -H "Authorization: Bearer tk_<your-personal-access-token>"

Error format

Every API error is JSON — including unmatched /api/* paths, which answer with a JSON 404 rather than an HTML error page. Errors carry a stable machine-readable code, a human message, and a hint describing how to resolve it.

error.json

{
  "error": "Sign in required",
  "code": "unauthorized",
  "message": "Sign in required",
  "hint": "Generate a personal access token in Settings → Developer and send it as an Authorization: Bearer header, or sign in at https://tokokino.com/login and send the session cookie. See https://tokokino.com/auth.md.",
  "docs": "https://tokokino.com/developers#errors"
}

The error field repeats message so that existing clients reading a plain string keep working.

unauthorized401

No valid token or session cookie was sent.

forbidden403

The account may not perform this action.

not_found404

No such path, or the resource is not yours.

invalid_request400

Body or query parameters failed validation.

unsupported_media_type415

The Content-Type is not accepted here.

payload_too_large413

The upload exceeds a size cap or quota.

rate_limited429

Too many requests in the current window.

internal_error500

Something failed server-side. Retry shortly.

Code	Status	Meaning
unauthorized	401	No valid token or session cookie was sent.
forbidden	403	The account may not perform this action.
not_found	404	No such path, or the resource is not yours.
invalid_request	400	Body or query parameters failed validation.
unsupported_media_type	415	The Content-Type is not accepted here.
payload_too_large	413	The upload exceeds a size cap or quota.
rate_limited	429	Too many requests in the current window.
internal_error	500	Something failed server-side. Retry shortly.

Limits and quotas

A single share image may be up to 40 MB; video shares upload in 8 MB parts up to 1 GB. Each account has 1 GB of total share storage. Draft bodies are capped at 15 MB and presets at 1 MB. Write and capture endpoints are rate limited per account or IP, and answer with rate_limited when a window is exhausted.

Agent and MCP resources

Tokokino publishes its capabilities for automated clients at predictable, well-known URLs.

OpenAPI 3.1 specification — Every documented endpoint, schema, and error response.
Authentication guide — How to generate a personal access token and send it with requests.
llms.txt — Product summary and machine-readable resource index for AI agents.
ARD capability manifest — Agentic Resource Discovery catalogue of everything listed here.
MCP server card — Model Context Protocol descriptor. The server is not live yet — /mcp answers 503 with a coming-soon payload until it ships.
Agent skills index — Skill documents for the share, drafts, and presets workflows.
API catalog — RFC 9727 linkset of published machine interfaces.

Support

Tokokino is open source under AGPL-3.0. Report a bug, request an endpoint, or ask a question on GitHub or through the contact page.

Quickstart

Authentication

OpenAPI specification

Endpoints

Shares

Drafts

Presets and preferences

Tokens

Media

Error format

Limits and quotas

Agent and MCP resources

Support