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

# API introduction

> LaneSync REST API — authentication, base URL, error model, and endpoint overview.

The LaneSync REST API powers the dashboard, CI evidence upload, and deploy gates. Hosted SaaS base URL:

```
https://lanesync.dev
```

Self-hosted customers use their own API URL. Set `SDLC_API_URL` in CI workflows accordingly.

## Authentication

| Model                | Used by                         | Mechanism                                          |
| -------------------- | ------------------------------- | -------------------------------------------------- |
| **Session (OAuth)**  | Dashboard, protected routes     | GitHub OAuth + session cookie                      |
| **GitHub OIDC**      | CI evidence upload, deploy gate | Short-lived JWT from Actions (`audience=lanesync`) |
| **LaneSync API key** | Non-GitHub CI, fallback         | `Authorization: Bearer lsk_*` (hashed at rest)     |
| **Webhook HMAC**     | `POST /api/webhook`             | `X-Hub-Signature-256`                              |

### Session-protected routes

Require authenticated GitHub OAuth session:

* `/api/dashboard`
* `/api/repos`
* `/api/milestones` (most routes)
* `/api/sync`
* `/api/quality`
* `/api/projects`
* `/api/team`
* `/api/settings/api-keys`
* `/api/config/repo-warnings`
* `/api/events`
* `/api/debug`

| Status | Condition                          |
| ------ | ---------------------------------- |
| `401`  | Missing session                    |
| `403`  | No tenant / not a workspace member |

### CI-authenticated routes

Require `Authorization: Bearer` with GitHub OIDC JWT or LaneSync API key:

* `POST /api/evidence/upload`
* `POST /api/evidence/upload-report`
* `GET /api/milestones/check`

Tenant is derived from the verified token (`repository_owner` for OIDC) or API key scope — **not** from an unauthenticated body field.

### Public routes (no auth)

* `GET /api/health`
* `GET /api/auth/*`
* `GET /api/config/status`, `/manifest-start`, install callbacks
* `POST /api/webhook` (HMAC verified)
* `POST /api/config/setup` (first-run only)

## Content type

JSON endpoints return `Content-Type: application/json` unless noted. Multipart used for `/api/evidence/upload-report`.

## Error format

Errors return a JSON body with an `error` field:

```json theme={null}
{ "error": "Human-readable message" }
```

Internal details are logged server-side; production responses use generic messages for 500 errors.

## HTTP status codes

| Code          | Use                                    |
| ------------- | -------------------------------------- |
| `200` / `201` | Success / created                      |
| `202`         | Webhook accepted (async processing)    |
| `302`         | OAuth redirect                         |
| `400`         | Validation error                       |
| `401`         | Authentication required                |
| `403`         | Forbidden                              |
| `404`         | Not found                              |
| `409`         | Conflict (e.g. bootstrap already done) |
| `413`         | Payload too large                      |
| `422`         | Unprocessable                          |
| `429`         | Rate limit exceeded                    |
| `500`         | Server error                           |

## Key endpoints by area

| Area       | Base path                | Notes                                   |
| ---------- | ------------------------ | --------------------------------------- |
| Health     | `/api/health`            | Liveness probe                          |
| Auth       | `/api/auth`              | OAuth login, callback, workspace picker |
| Dashboard  | `/api/dashboard`         | Org milestone summary                   |
| Repos      | `/api/repos`             | Bootstrap, config, detection            |
| Milestones | `/api/milestones`        | Stage details, deploy gate, approval    |
| Sync       | `/api/sync`              | Manual and background sync triggers     |
| Quality    | `/api/quality`           | Scorecards and exports                  |
| Evidence   | `/api/evidence`          | CI upload (OIDC or API key)             |
| Settings   | `/api/settings/api-keys` | CI API key management                   |
| Projects   | `/api/projects`          | Multi-repo roll-ups                     |
| Team       | `/api/team`              | Invites and roles                       |
| Events     | `/api/events`            | SSE sync notifications                  |
| Webhook    | `/api/webhook`           | GitHub App events                       |

## Deploy gate (CI)

CI pipelines check production readiness with CI auth:

```bash theme={null}
TOKEN=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
  "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=lanesync" | jq -r .value)

curl -H "Authorization: Bearer $TOKEN" \
  "https://lanesync.dev/api/milestones/check?version=v1.0.0&repo=my-repo"
```

```json theme={null}
{
  "version": "v1.0.0",
  "current_stage": "DEPLOYMENT",
  "evidence_pr_approved": true,
  "tests_passing": true,
  "can_deploy": true
}
```

## Evidence upload (CI)

```
POST /api/evidence/upload
Authorization: Bearer <OIDC JWT or lsk_* key>
```

See [CI evidence upload](/guides/ci-evidence-upload).

## OpenAPI specification

The **API Reference** tab auto-generates interactive endpoint documentation from `openapi.json`. Use it for request/response schemas and try requests against your instance.

## Related

* [Multi-tenancy](/concepts/multi-tenancy)
* [Enterprise security](/enterprise/security)