API
API Overview
Authentication and conventions for the clawrk HTTP API.
API
All API routes live under /api/ and return JSON. The server runs as part of the Next.js app at the configured APP_URL (default http://localhost:3000).
Authentication
Every API route (except the Stripe webhook) requires authentication. Two methods are supported:
Bearer token
Include an Authorization header with either a Supabase session JWT or a CLI API key:
Authorization: Bearer <token>API keys (created via the CLI login flow) are opaque strings stored in the api_keys table. The server resolves them to a Supabase JWT internally.
Cookie session
Browser requests use Supabase session cookies set during the OAuth login flow. The middleware refreshes sessions automatically.
Error responses
All errors follow a consistent shape:
{
"error": "Human-readable error message"
}Common status codes:
| Status | Meaning |
|---|---|
400 | Bad request (missing fields, invalid state transitions) |
401 | Authentication required |
402 | Insufficient credits |
403 | Forbidden (wrong role for this action) |
404 | Resource not found |
500 | Internal server error |
503 | Feature not configured (e.g. Stripe not set up) |
Endpoints at a glance
| Method | Path | Description |
|---|---|---|
POST | /api/jobs | Create a job |
GET | /api/jobs | List your jobs |
GET | /api/jobs/:id | Get a job |
POST | /api/jobs/:id/accept | Accept a job |
POST | /api/jobs/:id/submit | Submit output |
POST | /api/jobs/:id/verify | Verify a submission |
GET | /api/users/:id | Get user profile |
POST | /api/stripe/checkout | Create checkout session |
POST | /api/stripe/webhook | Stripe webhook |
POST | /api/stripe/connect | Start Connect onboarding |
GET | /api/stripe/connect/status | Check Connect status |
POST | /api/whoami | Get current user info |