API Reference

Automate your file processing workflows with the CodeStorms Tools REST API.

Overview

The CodeStorms Tools API lets you run any tool programmatically — upload files, trigger processing, and retrieve results. Runs are asynchronous: you submit a job and poll or stream for its status.

Base URL: https://codestorms.com/api/v2
All requests must be authenticated with a Bearer token.
Responses are JSON. File uploads use multipart/form-data.
API access requires a Pro or Team plan.

Authentication

Generate an API token from your account page. Pass the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Tokens can have optional expiry dates and can be rotated or revoked from your account page at any time.

Rate limits

Plan	API rate limit	Runs/day
Pro	60 req/min	500
Team	120 req/min	2 000

Rate-limited responses return HTTP 429 Too Many Requests. Retry after the Retry-After header value (seconds).

Endpoints

GET /api/v2/tools

Returns a list of all available tools with their slugs, names, and categories.

curl https://codestorms.com/api/v2/tools \
  -H "Authorization: Bearer YOUR_TOKEN"

POST /api/v2/tools/{slug}

Submit a file processing run. Returns 202 Accepted with a run id and status_url.

Upload files using files[] form fields. Pass tool-specific settings as additional form fields.

curl -X POST https://codestorms.com/api/v2/tools/image-compressor \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files[]=@photo.jpg" \
  -F "quality=80"

# Response (202):
{
  "id": "run_abc123",
  "status": "queued",
  "status_url": "https://codestorms.com/api/v2/runs/run_abc123"
}

GET /api/v2/runs/{id}

Get the current status and output download URLs for a run. Poll this endpoint until status === "done" or "failed".

curl https://codestorms.com/api/v2/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response when done:
{
  "id": "run_abc123",
  "status": "done",
  "tool": "image-compressor",
  "outputs": [
    { "filename": "photo-compressed.jpg", "url": "...", "size_bytes": 42300 }
  ]
}

GET /api/v2/runs/{id}/stream

Server-Sent Events (SSE) stream for real-time run status updates. The connection stays open until the run reaches a terminal state (done or failed).

curl -N https://codestorms.com/api/v2/runs/run_abc123/stream \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

# Stream events:
data: {"status":"processing","progress":45}
data: {"status":"done","outputs":[...]}

GET /api/v2/runs

List your recent runs. Supports ?limit= and ?cursor= query parameters for pagination.

GET /api/v2/usage

Returns your current plan, daily run count, and limits.

{
  "plan": "pro",
  "runs_today": 12,
  "runs_per_day": 500,
  "api_rate_limit": 60
}

POST /api/v2/webhooks

Register a webhook URL to receive run.completed and run.failed events. Each webhook receives a JSON payload with the full run object.

curl -X POST https://codestorms.com/api/v2/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.com/hooks/codestorms", "events": ["run.completed"]}'

Error codes

HTTP status	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid API token
`403`	Forbidden — your plan does not include API access
`404`	Not found — unknown tool slug or run ID
`422`	Unprocessable — validation errors (see `errors` field)
`429`	Too many requests — rate limit exceeded
`500`	Internal server error — processing failed

Ready to get started?

API access is available on Pro and Team plans. Generate your token from the account page.

Get your API token View pricing