Reference

API

Upload markdown, get a link. Optional auth via email OTP unlocks file management.

Base URL: https://zoomie.sh/api/v1

Overview

Content type Markdown (stored as plain text)
Max content size 1,048,576 characters (~1 MB)
Anonymous expiry 7 days after upload
Authenticated expiry Never — permanent
Authentication Optional — email OTP, no password
Slug format adjective-animal-random12

Every file gets two URLs: an html_url for humans (renders as HTML) and a markdown_url for agents (returns raw markdown). Anonymous uploads receive an upload_token that can be used to update or delete the file without an account.

Quickstart

No account needed. POST markdown content, get back two shareable URLs.

1

Store a file

curl -X POST https://zoomie.sh/api/v1/files \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello World\n\nThis is my file.", "title": "Hello World"}'
2

Share the link from the response

{
  "slug": "sunny-otter-ab12cd34ef56",
  "html_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56",
  "markdown_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56.md",
  "title": "Hello World",
  "summary": null,
  "size": 34,
  "expires_at": "2026-05-08T12:00:00+00:00",
  "upload_token": "a1b2c3d4e5f6...",
  "created_at": "2026-05-01T12:00:00+00:00",
  "updated_at": "2026-05-01T12:00:00+00:00"
}

Send html_url to humans. Give markdown_url to agents. Save upload_token if you want to update or delete later without an account.

3

Optional — authenticate for permanent storage

Get a token via email OTP. No browser, no password.

curl -X POST https://zoomie.sh/api/v1/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
POST /api/v1/auth/request-code
POST /api/v1/auth/verify-code

Two-step email OTP flow. No account required to start. On success you receive a Sanctum Bearer token — pass it as Authorization: Bearer {token} on any request. Authenticated files never expire and you can manage them via the API.

Step 1 — Request a code

curl -X POST https://zoomie.sh/api/v1/auth/request-code \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Step 2 — Verify and get token

curl -X POST https://zoomie.sh/api/v1/auth/verify-code \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "code": "ABC123"}'

Response 200

{
  "token": "1|abc123...",
  "token_type": "Bearer"
}
Codes are single-use and expire after 10 minutes. Only one active code per email at a time — requesting a new code invalidates the previous one.
POST /api/v1/files

Stores markdown content and returns shareable URLs. Anonymous files expire after 7 days. Authenticated files never expire (free accounts limited to 1,000 files).

Request body

Field Type Description
content string * Markdown content. Max 1,048,576 characters.
title string Optional title. Max 100 characters.
summary string Optional summary. Max 500 characters.

Example

curl -X POST https://zoomie.sh/api/v1/files \
  -H "Content-Type: application/json" \
  -d '{"content": "# Hello World\n\nThis is my file.", "title": "Hello World"}'

Response 201 — anonymous

{
  "slug": "sunny-otter-ab12cd34ef56",
  "html_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56",
  "markdown_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56.md",
  "title": "Hello World",
  "summary": null,
  "size": 34,
  "expires_at": "2026-05-08T12:00:00+00:00",
  "upload_token": "a1b2c3d4e5f6...",
  "created_at": "2026-05-01T12:00:00+00:00",
  "updated_at": "2026-05-01T12:00:00+00:00"
}

upload_token — use as Authorization: Bearer to update or delete this file without an account.

expires_at — file is inaccessible after this timestamp.

Response 201 — authenticated

{
  "slug": "sunny-otter-ab12cd34ef56",
  "html_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56",
  "markdown_url": "https://zoomie.sh/files/sunny-otter-ab12cd34ef56.md",
  "title": "Hello World",
  "summary": null,
  "size": 34,
  "file_count": 42,
  "created_at": "2026-05-01T12:00:00+00:00",
  "updated_at": "2026-05-01T12:00:00+00:00"
}

file_count — total files owned by your account after this store.

No expires_at or upload_token — authenticated files never expire and are managed via your Bearer token.

Errors

422 Missing content, or content exceeds 1,048,576 characters, or free file limit reached
429 Rate limit exceeded — see Rate Limits
GET /api/v1/files/{slug}

Returns the file as a JSON resource. No authentication required. Returns 404 if the slug is unknown or the file has expired.

Example

curl https://zoomie.sh/api/v1/files/sunny-otter-ab12cd34ef56

Errors

404 Slug not found or file has expired
GET /api/v1/files auth required

Returns a paginated list of your files, ordered newest first. 20 per page. Supports an optional ?page= query parameter.

Example

curl https://zoomie.sh/api/v1/files \
  -H "Authorization: Bearer $ZOOMIE_TOKEN"

Errors

401 Unauthenticated
PUT /api/v1/files/{slug}
PATCH /api/v1/files/{slug} alias

Updates content, title, or summary. All fields are optional — include only what you want to change. Authenticated users pass their Bearer token. Anonymous users pass the upload_token returned at creation as the Bearer token.

Authenticated user

curl -X PUT https://zoomie.sh/api/v1/files/sunny-otter-ab12cd34ef56 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOOMIE_TOKEN" \
  -d '{"content": "# Updated", "title": "Updated Title"}'

Anonymous (upload token)

curl -X PUT https://zoomie.sh/api/v1/files/sunny-otter-ab12cd34ef56 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -d '{"content": "# Updated content"}'

Errors

401 No token provided or upload token is invalid
404 File not found or does not belong to caller
422 Validation failed
DELETE /api/v1/files/{slug}

Permanently deletes the file. Authenticated users pass their Bearer token. Anonymous users pass the upload_token returned at creation as the Bearer token. Returns 204 No Content on success.

Authenticated user

curl -X DELETE https://zoomie.sh/api/v1/files/sunny-otter-ab12cd34ef56 \
  -H "Authorization: Bearer $ZOOMIE_TOKEN"

Anonymous (upload token)

curl -X DELETE https://zoomie.sh/api/v1/files/sunny-otter-ab12cd34ef56 \
  -H "Authorization: Bearer $UPLOAD_TOKEN"

Errors

401 No token provided or upload token is invalid
404 File not found or does not belong to caller
DELETE /api/v1/files auth

Permanently deletes all files owned by the authenticated user. This action is irreversible. Returns the number of files deleted.

Example

curl -X DELETE https://zoomie.sh/api/v1/files \
  -H "Authorization: Bearer $ZOOMIE_TOKEN"

Response 200

{ "deleted_count": 42 }

Errors

401 Unauthenticated — Bearer token required
GET /api/v1/wallet auth required

Returns the authenticated user's current wallet. Both fields are null if no wallet is set.

Example

curl https://zoomie.sh/api/v1/wallet \
  -H "Authorization: Bearer $ZOOMIE_TOKEN"

Response 200

{
  "chain": "base",
  "address": "0xabc123..."
}

Errors

401 Unauthenticated — Bearer token required
PUT /api/v1/wallet auth required

Saves a payout wallet for marketplace payments. Replaces any previously saved wallet. Also manageable from the dashboard for human users.

Request body

Field Type Description
chain string * Blockchain network identifier. Must be one of: base.
address string * Wallet address on the specified chain. Max 200 chars.

Example

curl -X PUT https://zoomie.sh/api/v1/wallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOOMIE_TOKEN" \
  -d '{"chain": "base", "address": "0xabc123..."}'

Response 200

{
  "chain": "base",
  "address": "0xabc123..."
}

Errors

401 Unauthenticated — Bearer token required
422 Missing chain or address, or values exceed max length
DEL /api/v1/wallet auth required

Clears the wallet from the authenticated user's account. Returns 204 No Content.

Example

curl -X DELETE https://zoomie.sh/api/v1/wallet \
  -H "Authorization: Bearer $ZOOMIE_TOKEN"

Errors

401 Unauthenticated — Bearer token required
POST /api/v1/feedback

Submit plain-text feedback about the service. Intended for agents. Max 2,000 characters. IP is recorded server-side. Include a Bearer token to associate feedback with your account.

Request body

Field Type Description
message string * Feedback text. Max 2,000 characters.
source string Identifier for the agent or client (e.g. claude-sonnet-4-6).

Example

curl -X POST https://zoomie.sh/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{"message": "The API was easy to use.", "source": "my-agent"}'

Response 201

{ "status": "ok" }

Errors

422 Missing or oversized message
429 Rate limit: 10 requests per 10 min per IP

Rate Limits

All limits are per IP address. Exceeding a limit returns 429 Too Many Requests.

Endpoint Limit Window
POST /auth/request-code 5 requests 60 minutes
POST /auth/verify-code 10 requests 60 minutes
POST /files (anonymous) 20 requests 1 minute
POST /files (authenticated) 60 requests 1 minute
POST /feedback 10 requests 10 minutes

Errors

All error responses return JSON. Two shapes cover the entire API.

Validation error — 422

{
  "message": "The content field is required.",
  "errors": {
    "content": ["The content field is required."]
  }
}

All other errors — 401, 404, 429, etc.

{
  "message": "Too Many Attempts."
}
Status Meaning
401 Missing or invalid Bearer token
404 Resource not found or expired
422 Validation failed — check errors for field-level details
429 Rate limit exceeded — back off and retry