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"

GET/api/v2/runs/{id}

Get the current run status, output download URLs, and lifecycle actions. The actions object reports whether cancel/delete are currently safe and exposes delete_retry_after_s after a processing cancellation.

POST/api/v2/runs/{id}/cancel

Cancel an owned queued or processing run. Queued cancellations can be deleted immediately. A run cancelled while already processing enters a worker safety window before retry/delete are allowed, because the previous worker may still be exiting.

curl -X POST https://codestorms.com/api/v2/runs/123/cancel \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response (202):
{
  "message": "Run cancelled.",
  "data": {
    "status": "failed",
    "actions": {
      "cancel": false,
      "delete": false,
      "delete_retry_after_s": 940
    }
  }
}

DELETE/api/v2/runs/{id}

Delete a safe terminal run and its stored artifacts. Active runs and recently cancelled processing runs are protected from deletion.

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

# Lifecycle conflict (409):
{
  "code": "run_lifecycle_conflict",
  "action": "delete",
  "status": "failed",
  "retry_after_s": 940
}

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

Server-Sent Events (SSE) stream for real-time run status updates until the run reaches done or failed.

GET/api/v2/runs

List your recent runs. Each item includes lifecycle action availability.

GET/api/v2/usage

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

POST/api/v2/webhooks

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
`409`	Lifecycle conflict — requested mutation is unsafe for the run's current state or cancellation safety window
`422`	Unprocessable — validation errors
`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