API Overview

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 Type	Used For	Endpoints
API Key only	SDK write operations	`POST /v1/runs/`, step creation, step updates
JWT or API Key	Dashboard + SDK read	Run listing, workspace config, usage, API keys
JWT only	User account operations	`/v1/auth/me`, billing, password change
None	Public	`/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

Code	Meaning
`400`	Bad request — invalid input
`401`	Unauthorized — missing or invalid auth
`403`	Forbidden — feature not available on your plan
`404`	Not found
`422`	Validation error — invalid request body
`500`	Internal 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.

Getting Started

SDK

API Reference

Guides

Configuration

Base URL

Authentication

API Key (SDK endpoints)

JWT Token (Dashboard endpoints)

Endpoint Auth Requirements

Error Responses

Status Codes

Plan-Gated 403 Errors

Health Check

​Base URL

​Authentication

​API Key (SDK endpoints)

​JWT Token (Dashboard endpoints)

​Endpoint Auth Requirements

​Error Responses

​Status Codes

​Plan-Gated 403 Errors

​Health Check

Base URL

Authentication

API Key (SDK endpoints)

JWT Token (Dashboard endpoints)

Endpoint Auth Requirements

Error Responses

Status Codes

Plan-Gated 403 Errors

Health Check