# The Scribble Thing Agent API > The Scribble Thing by Boring Stuff Club turns a user-provided PNG or JPEG line-art image into an MP4 scribe animation. The API can use an optional natural-language drawing order and can include a drawing hand. - API version: v1 - Base URL: https://scribble.boringstuff.club/agent/v1 - OpenAPI: https://scribble.boringstuff.club/agent/v1/openapi.json - MCP endpoint: https://scribble.boringstuff.club/mcp - Agent skill: https://scribble.boringstuff.club/.well-known/agent-skills/the-scribble-thing/SKILL.md - Agent skill discovery: https://scribble.boringstuff.club/.well-known/agent-skills/index.json - HTML guide: https://scribble.boringstuff.club/docs/agent-api - Terms version: 2026-08-23.1 - Session-file retention: up to 24 hours - Watermarked preview: free - Clean-video unlock: $5 for one animation ## MCP and agent skill For an MCP-capable agent, connect the Streamable HTTP endpoint at `https://scribble.boringstuff.club/mcp`. It exposes tools to inspect current service policy, create an animation from base64 PNG or JPEG bytes, poll status, obtain a download URL, redeem a user-provided unlock code, and delete an animation. The installable skill at `https://scribble.boringstuff.club/.well-known/agent-skills/the-scribble-thing/SKILL.md` teaches the safe end-to-end workflow and declares the MCP dependency. A deterministic ZIP package and its SHA-256 digest are published through the discovery index. Use the REST workflow below when an MCP host cannot provide the image as base64. ## Recommended workflow 1. Read and accept the current Terms of Use and 24-hour file-retention notice. 2. POST multipart form data to `/agent/v1/animations` with an image and a unique `Idempotency-Key` header. 3. Store the returned `animation_id` and per-animation `access_token` securely. 4. Poll `status_url` every 3–5 seconds using `Authorization: Bearer ACCESS_TOKEN` until `status` is `completed` or `failed`. 5. Download the free watermarked MP4 from `preview_url`. 6. Give `manage_url` to the user for private browser review and optional purchase or entry of an unlock code. 7. When `unlocked` becomes true, download the clean MP4 from `clean_url`. 8. DELETE the animation when it is no longer needed. All session content otherwise expires within 24 hours. ## Create an animation `POST https://scribble.boringstuff.club/agent/v1/animations` Content type: `multipart/form-data` Required form fields: - `image`: PNG or JPEG bytes, up to 10 MB and 4096 by 4096 pixels. - `accept_retention=true` - `accept_terms=true` - `terms_version=2026-08-23.1` - `client_name`: a short, non-personal integration label. Optional form fields: - `order_text`: natural-language component order, maximum 2,000 characters. Blank selects an automatic natural order. - `show_hand`: `true` or `false`; default `false`. - `speed`: `slow`, `normal`, or `fast`; default `normal`. - `client_version`: calling integration version. - `marketplace`: agent-directory or integration-source label. Required header: - `Idempotency-Key`: a unique, non-personal retry key, 8–200 characters. Recommended header: - `X-Agent-Installation-Id`: a stable, non-personal installation identifier. The service retains only a one-way hash. The initial response is HTTP 202. An identical replay returns HTTP 200 and `idempotent_replay: true`. Reusing the key with different input returns HTTP 409. ## Authorization The create response returns an `access_token` scoped to one animation. It is not an account or general API key. Send it as: ```text Authorization: Bearer ANIMATION_CAPABILITY ``` Do not put bearer capabilities in model prompts, analytics, logs, URLs other than the returned `manage_url`, or requests to third-party storage hosts. ## Poll status `GET /agent/v1/animations/{animation_id}` Statuses are `queued`, `running`, `completed`, and `failed`. The response includes progress, expiration time, download availability, `preview_url`, `clean_url`, and `manage_url`. A failed response contains a safe error code and message. ## Preview, unlock, and clean video - `GET /agent/v1/animations/{animation_id}/preview`: completed watermarked MP4. - Recommended unlock: give the returned `manage_url` to the user. The user can review the result and buy or enter a code without giving payment details to the agent. - Direct trusted-client unlock: `POST /agent/v1/animations/{animation_id}/unlock` with JSON `{ "code": "UNLOCK-XXXX-XXXX-XXXX" }`. - `GET /agent/v1/animations/{animation_id}/clean`: completed clean MP4 after unlock. Unused purchase codes expire after 30 days. Each code unlocks one animation and is consumed atomically. ## Delete `DELETE /agent/v1/animations/{animation_id}` immediately removes the active session and its files. The capability is required. ## Error behavior - 400: invalid upload, consent, terms version, or unlock code. Correct the request. - 401: missing or malformed bearer capability. - 403: clean video is locked. Give `manage_url` to the user. - 404: animation, capability pairing, or video not found. - 409: video not ready or idempotency-key conflict. - 410: animation expired or was deleted. - 422: request does not match the schema. - 429: generation or unlock-attempt limit reached. Respect `Retry-After` when present. - 503: capacity or temporary storage/dispatch failure. Retry with the same idempotency key. Direct unlock failures are limited over 15 minutes: 5 per animation, 20 per source-IP hash, and 100 globally. ## Privacy and safety - Artwork, instructions, intermediate files, plans, and videos are retained for no more than 24 hours. - Do not place names, emails, filenames, prompts, secrets, or other personal information in client labels, installation identifiers, idempotency keys, or logs. - Users must own or have permission to process submitted content. - AI output may be incomplete or inaccurate and should be reviewed. ## Authoritative links - FAQ: https://scribble.boringstuff.club/faq - Terms of Use: https://scribble.boringstuff.club/terms - Privacy Policy: https://scribble.boringstuff.club/privacy - Contact: https://scribble.boringstuff.club/contact?feature=general