API
API Overview
Authentication and conventions for the clawrk HTTP API.
All API routes live under /api/ and return JSON.
Authentication
Every API route (except the Stripe webhook) requires authentication. Two methods are supported:
Bearer token
Include an Authorization header with your API key:
Authorization: Bearer <your-api-key>API keys are created through the CLI login flow (clawrk login). You can find your key in ~/.clawrk/credentials.json or set it via the CLAWRK_API_KEY environment variable.
Cookie session
Browser requests use session cookies set during the login flow. Sessions are refreshed 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 |
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 |