Endpoint Reference
This page lists the shipped HTTP routes in apps/api. It separates external agent/API-key routes from recruiter UI routes and public participant routes.
The generated OpenAPI contract for customer and partner integrations is available at /openapi.json on the API host, with Swagger UI at /docs. That generated contract is intentionally scoped to the /v1/api API-key routes.
Auth models
| Auth | Used by | Headers |
|---|---|---|
| API key | External agents, partner systems, CLI reference workflow | Authorization: Bearer <key> or x-api-key: <key> |
| Clerk tenant session | Recruiter UI and tenant admin screens | Clerk session cookies/JWT handled by the app |
| Public token | Candidate intake, referee conversations, shared reports | Token in the path |
| None | Health and metadata | None |
Public API-key routes
Base path: /v1/api
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /reference-requests/:requestId | references:read | Read a reference request for the API-key tenant |
POST | /agent | references:read | Ask the OpenRouter-backed Veref workspace agent |
GET | /ops/feed | references:read | Read the tenant ops feed through an API key |
POST | /ops/messages | references:write | Create an ops coordination message through an API key |
POST | /reference-requests | references:write | Start a reference-check workflow |
POST | /reference-requests/:requestId/lifecycle | references:write | Advance reference-request lifecycle state |
POST | /reference-requests/:requestId/valuation/draft | valuations:write | Generate or preview valuation draft |
POST | /reference-requests/:requestId/valuation/approve | valuations:write | Approve valuation/report package |
POST | /reference-requests/:requestId/share | reports:write | Create a customer share link |
The API key actor supplies tenantId and recruiterId; callers should not rely on body-supplied identity fields.
API key management routes
Base path: /v1/tenants/:tenantId/api-keys
These routes require a recruiter Clerk tenant session.
| Method | Path | Purpose |
|---|---|---|
POST | / | Create a new API key and return the plaintext once |
GET | / | List API keys for the tenant |
DELETE | /:apiKeyId | Revoke an API key |
GET | /scopes | List supported API key scopes |
Recruiter tenant routes
Base path: /v1/tenants
These routes require a recruiter Clerk tenant session.
| Method | Path | Purpose |
|---|---|---|
GET | /:tenantId/workspace | Recruiter workspace snapshot |
GET | /:tenantId/candidates | List candidates |
POST | /:tenantId/candidates | Create candidate |
PATCH | /:tenantId/candidates/:candidateId/profile | Update candidate profile |
DELETE | /:tenantId/candidates/:candidateId | Soft-delete candidate |
GET | /:tenantId/candidates/:candidateId | Candidate workspace detail |
POST | /:tenantId/reference-requests | Create reference request from recruiter UI |
GET | /:tenantId/reference-requests/:requestId | Read reference request |
POST | /:tenantId/reference-requests/:requestId/lifecycle | Advance reference lifecycle |
GET | /:tenantId/reference-requests/:requestId/review | Review view for a request |
GET | /:tenantId/reference-requests/:requestId/activity | Request activity feed |
GET | /:tenantId/reference-requests/:requestId/milestones | Request milestone status |
GET | /:tenantId/reference-reports/:referenceRequestId | Report lifecycle state |
POST | /:tenantId/reference-reports/:referenceRequestId/draft | Draft report |
POST | /:tenantId/reference-reports/:referenceRequestId/approve | Approve report |
POST | /:tenantId/reference-reports/:referenceRequestId/share | Create share link |
POST | /:tenantId/reference-reports/:referenceRequestId/revoke | Revoke share link |
GET | /:tenantId/reference-reports/:referenceRequestId/pdf | Export approved PDF |
GET | /:tenantId/dashboard | Tenant dashboard preview |
PATCH | /:tenantId/trust-signals/:signalId | Review trust signal |
GET | /:tenantId/ops/feed | Tenant ops feed |
POST | /:tenantId/ops/messages | Create ops message |
POST | /:tenantId/ops/agent | Ask the recruiter workspace agent |
POST | /:tenantId/flags | Set tenant feature flag |
POST | /:tenantId/passport-reference-permissions | Ask a candidate to reuse collected reference details |
GET | /:tenantId/onboarding-status | Read onboarding status |
PATCH | /:tenantId/onboarding | Mark onboarding complete |
GET | /:tenantId/recruiters/:recruiterId/preferences | Read recruiter preferences |
PATCH | /:tenantId/recruiters/:recruiterId/preferences | Update recruiter preferences |
Public participant routes
These routes use path tokens issued by the reference workflow.
| Method | Path | Purpose |
|---|---|---|
GET | /v1/public/intake/:token | Resolve candidate intake token |
POST | /v1/public/intake/:token/messages | Stream candidate intake agent response over SSE |
POST | /v1/public/intake/:token/complete | Complete candidate intake |
POST | /v1/public/intake/:token/abandon | Abandon candidate intake |
GET | /v1/public/referee/:token | Resolve referee token |
POST | /v1/public/referee/:token/messages | Stream referee agent response over SSE |
POST | /v1/public/referee/:token/complete | Complete referee conversation |
POST | /v1/public/referee/:token/abandon | Abandon referee conversation |
GET | /v1/public/reference-reports/:token | Open shared reference report |
GET | /v1/public/reference-reports/:token/pdf | Download shared report PDF |
Integrations and webhooks
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST | /v1/webhooks/clerk | Clerk webhook signature | Clerk tenant/recruiter provisioning |
Health and metadata
| Method | Path | Auth | Purpose |
|---|---|---|---|
GET | /health | None | API health check |
GET | /v1/meta/stack | None | Stack/runtime metadata |
GET | /v1/onboarding/state | Clerk request auth | Public onboarding state |
Agent equivalence
The recruiter app chat, the local CLI, Claude, GPT, Codex, and partner agents should be treated as different clients for the same workflow:
- Start reference check through
POST /v1/api/reference-requestsorveref references start. - Use
launchMode: "candidate_intake"for candidate-led permission and referee collection, orlaunchMode: "manual_references"when referee contacts are already known. - Manual-reference contacts must include both email and phone; tenant defaults normalize local phone numbers to E.164.
- Candidate and referee participants continue through public token routes.
- Agent or recruiter advances lifecycle only when needed.
- Draft, approve, and share reports through the report endpoints.
- Use ops endpoints for coordination, not as workflow state.
Ops feed and message routes persist coordination messages in Prisma. They only return preview data when VEREF_ENABLE_PREVIEW_FALLBACK=1 is explicitly set for development.