> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikarc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Authentication, base URL, and error handling for the Pikarc REST API.

## 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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "detail": "Kill switch is not available on the pro plan. Upgrade to Scale or Enterprise."
}
```

See [Plan Tiers](/guides/plan-tiers) for which features are available on each plan.

## Health Check

```
GET /health
```

Returns `200 OK` with the API status. No authentication required.