RatioAI

RatioAI API.

Reference documentation for an optional server backend. Server tools use bearer authorization and follow this flow: presigned upload → enqueue job → poll status → presigned download.

The guest workspace does not issue API tokens. These examples require a configured backend URL and a token supplied by its administrator.
# Set RATIOAI_API_URL to your backend base URL and
# RATIOAI_API_TOKEN to a token issued by your backend administrator.
# The guest workspace does not issue tokens.
API="$RATIOAI_API_URL"
TOKEN="$RATIOAI_API_TOKEN"

# 1) Request an upload URL.
curl -s -X POST "$API/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"input.pdf","mime_type":"application/pdf","size_bytes":1234567}' \
  > presigned.json

# 2) Upload the file directly to the returned storage URL.
curl -s -X PUT \
  "$(jq -r '.data.upload_url' presigned.json)" \
  -H 'Content-Type: application/pdf' \
  --data-binary @input.pdf

# 3) Enqueue a job.
curl -s -X POST "$API/v1/jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tool":"compress_heavy","input_file_id":"'$(jq -r '.data.file_id' presigned.json)'","params":{"quality":70}}'

Request and response shape

Successful responses are wrapped in { data: ... }. Errors are wrapped in { error: { code, message, request_id } }.Treat code as the contract; message may change.

# Success
{ "data": { "id": "fil_01J...", "name": "input.pdf", ... } }

# Error
{ "error": { "code": "validation", "message": "size_bytes must be > 0", "request_id": "req_01J..." } }

Bearer auth: Authorization: Bearer <jwt>. Token availability and session policies are managed by your backend. Idempotency: Idempotency-Key header on POST /v1/jobs.

Common errors

  • unauthorized — missing or rejected token.
  • invalid_credentials — wrong email or password.
  • email_taken — email already registered.
  • validation — request body failed validation.
  • too_large — file exceeds the 10GB upload cap.
  • unknown_tool — server tool slug not recognized.
  • not_found — file or job missing or not yours.

Backend authentication

POST/v1/auth/register

Create a backend user, if registration is enabled by the backend operator.

Body
  • emailstring
  • passwordstring ≥ 8
  • namestring (optional)
Response
201: { token, expires_at, user }
POST/v1/auth/login

Sign in with email and password.

Body
  • emailstring
  • passwordstring
Response
200: { token, expires_at, user }
401: { error: { code: "invalid_credentials" } }
POST/v1/auth/logoutauthed

Revoke the current session.

Response
204
GET/v1/meauthed

Return the current user.

Response
200: { id, email, name, plan }

Files

POST/v1/filesauthed

Mint a presigned upload URL for direct-to-R2 PUT.

Body
  • namestring
  • mime_typestring
  • size_bytesinteger (≤ 10GB)
Response
201: { file_id, upload_url, expires_at, method, headers }
GET/v1/files/{id}authed

Return file metadata + a presigned GET URL.

Response
200: { id, name, size_bytes, mime_type, storage_tier, expires_at, created_at, download_url }
DELETE/v1/files/{id}authed

Soft-delete a file.

Response
204

Jobs

POST/v1/jobsauthed

Enqueue a server-side tool against an uploaded file.

Body
  • tool"compress_heavy" | "office_to_pdf" | "ocr"
  • input_file_idstring (from POST /v1/files)
  • paramsobject (tool-specific)
Response
201: { id, tool, status, progress, input_file_id, params }
GET/v1/jobs/{id}authed

Poll job status until terminal (succeeded | failed | canceled).

Response
200: { id, tool, status, progress, output_file_id?, error_code?, error_message? }

Billing

POST/v1/billing/checkoutauthed

Stripe Checkout session for a Pro subscription.

Body
  • cycle"monthly" | "yearly"
Response
200: { url }
POST/v1/billing/portalauthed

Stripe Customer Portal session for an existing subscriber.

Response
200: { url }
POST/v1/billing/webhookwebhook

Stripe webhook receiver. Verifies signature; updates user plan.

Response
200: { received: true }

Public API status

This frontend provides free browser tools without an account. It does not provide public API keys or anonymous access to server tools. The endpoint reference applies only to a compatible backend configured by your deployment administrator; availability depends on that backend.

To work with a PDF now, open the browser workspace.