Skip to main content

​
Base URL

All API endpoints are versioned under /v1: 
http://localhost:8000/v1
In production, replace with your deployed Pikarc API URL.

​
Authentication

Pikarc supports two authentication mechanisms:

​
API Key (SDK endpoints)

Used by the SDK for machine-to-machine communication. Pass the key as a Bearer token: 
curl -H "Authorization: Bearer lg_a1b2c3d4_e5f6a7b8..." \
  http://localhost:8000/v1/runs/
API key format: lg_<prefix>_<secret>
  • The prefix is used for fast database lookup
  • The secret is verified against a SHA256 hash
  • Keys are generated on registration and can be regenerated in the dashboard

​
JWT Token (Dashboard endpoints)

Used by the web dashboard. Obtained via the login endpoint: 
# Login
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Response: { "access_token": "eyJ...", "token_type": "bearer" }

# Use the token
curl -H "Authorization: Bearer eyJ..." \
  http://localhost:8000/v1/workspace/
JWT tokens expire after 24 hours by default.

​
Endpoint Auth Requirements

Auth TypeUsed ForEndpoints
API Key onlySDK write operationsPOST /v1/runs/, step creation, step updates
JWT or API KeyDashboard + SDK readRun listing, workspace config, usage, API keys
JWT onlyUser account operations/v1/auth/me, billing, password change
NonePublic/v1/auth/login, /v1/auth/register, /health

​
Error Responses

All errors return a JSON body with a detail field: 
{
  "detail": "No active API key"
}

​
Status Codes

CodeMeaning
400Bad request — invalid input
401Unauthorized — missing or invalid auth
403Forbidden — feature not available on your plan
404Not found
422Validation error — invalid request body
500Internal server error

​
Plan-Gated 403 Errors

Some operations are restricted by plan tier. For example, enabling the kill switch on a Basic or Pro plan returns: 
{
  "detail": "Kill switch is not available on the pro plan. Upgrade to Scale or Enterprise."
}
See Plan Tiers for which features are available on each plan.

​
Health Check

GET /health
Returns 200 OK with the API status. No authentication required.