API introduction - LaneSync

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)
MCP OAuth	Remote MCP connection	Browser workspace consent, PKCE, 15-minute bearer, rotating refresh token
Personal MCP key	MCP clients with custom headers	`Authorization: Bearer lsm_*` (hashed at rest, 30-day expiry; read scope by default)
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/reviews
/api/history
/api/projects
/api/team
/api/settings/api-keys
/api/settings/mcp-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 and GitHub App installation callbacks. Legacy /manifest-start, /manifest-callback, and /setup credential writes return HTTP 410.
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:

{ "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`	Release creation, scope/ownership, stage details, deploy gate, approval
Reviews	`/api/reviews`	Live reviewer eligibility and effective policy
History	`/api/history`	Recorded shipped releases and approval evidence
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
MCP	`/api/settings/mcp-keys` and `/api/mcp`	Personal key management and remote MCP protocol
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

Collection pagination

Supply page or pageSize to request a paginated collection. Pages start at 1; page defaults to 1 and accepts integers through 100000. pageSize defaults to 25 and accepts 10, 25 or 50. Invalid pagination values return 400. These session-protected GET endpoints support pagination:

/api/dashboard: search matches repository or release; outcome accepts all, blocked, needs_approval, ready_to_deploy or in_progress.
/api/repos: search matches organization or repository; results are returned in groups.
/api/projects: org selects an organization; search matches project details or linked repository/release names.
/api/reviews/pending: scope=mine (default) selects verified eligible reviews; scope=workspace includes other workspace reviews.
/api/history: repository=owner/repo, from=YYYY-MM-DD and to=YYYY-MM-DD filter recorded releases. UTC date boundaries are inclusive.
/api/quality: owner, repo, milestone, type and environment filter complete release groups in results.
/api/milestones/{owner}/{repo}: search matches release versions in that repository.

Search and filters apply before pagination on the endpoints that support them. Each paginated response includes:

{
  "pagination": { "page": 2, "pageSize": 25, "total": 61, "pages": 3 }
}

total counts all matching records or release groups, rather than the rows on the current page. pages is at least 1, including an empty collection. An out-of-range page can return an empty collection; use the returned metadata to select a valid page. Dashboard counts cover all active releases matching search, independently of the selected outcome and page. History also returns repository choices across its full collection. Quality exports include all matching release groups rather than the current page.

Paginated setup, readiness and review lists return stored observations while verification refreshes in the background. Pending or expired observations do not establish readiness or approval eligibility. Use the stage-details and release-review endpoints for current checks. If you omit both pagination parameters, the existing unpaginated response shape is retained; /api/repos returns an array rather than a groups envelope.

Deploy gate (CI)

CI pipelines check production readiness with CI auth:

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"

{
  "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.

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.

​Authentication

​Session-protected routes

​CI-authenticated routes

​Public routes (no auth)

​Content type

​Error format

​HTTP status codes

​Key endpoints by area

​Collection pagination

​Deploy gate (CI)

​Evidence upload (CI)

​OpenAPI specification

​Related

Authentication

Session-protected routes

CI-authenticated routes

Public routes (no auth)

Content type

Error format

HTTP status codes

Key endpoints by area

Collection pagination

Deploy gate (CI)

Evidence upload (CI)

OpenAPI specification

Related