API Overview

The Vitae.ai API is a versioned JSON API. All endpoints are prefixed with /v1.

Base URL: https://api.vitae.ai/v1

Current status

The API is being normalized around canonical recruiting resources:

• candidates
• jobs
• clients
• applications
• interviews
• inbox-items
• agent-tasks

Some older endpoints are still available for compatibility and may return legacy response shapes. New product work should use the canonical resource model and serializer contract documented here.

Response format

New endpoints use the shared response envelope:

{
  "data": {
    "id": "client_01h...",
    "type": "client",
    "name": "Acme Corp"
  }
}

List endpoints include meta:

{
  "data": [],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 25,
      "total": 125,
      "hasNextPage": true
    }
  }
}

Errors follow a consistent shape:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": [{ "field": "email", "message": "must be a valid email" }],
    "requestId": "req_01h..."
  }
}

See Response Format for the full serializer contract.

Pagination

New list endpoints use page and limit query params:

GET /v1/candidates?page=2&limit=25

Legacy endpoints may still use offset, docs, or custom pagination fields until they are migrated.

Rate limiting

The API enforces rate limits per account. If you hit the limit, you’ll receive a 429 Too Many Requests response with a Retry-After header.

Versioning

The current API version is v1. The version is part of the URL path, not a header.

Authentication

All protected endpoints require a Bearer token. See Authentication for the full auth flow.

Developer platform

For server-to-server integrations, the Public Developer API exposes candidates, jobs, applications, and placements behind scoped, organization-owned API keys with per-key rate limits. Subscribe to change events with HMAC-signed Outbound Webhooks.

AI clients (MCP)

To use Vitae from Claude, ChatGPT, or another AI client, connect to the hosted MCP Server at https://mcp.vitae.ai/mcp. It supports one-click OAuth and personal access tokens.

Interactive docs

The generated OpenAPI reference is available at docs.vitae.ai/api. The raw spec is proxied through the docs app at /api-spec and sourced from https://api.vitae.ai/v1/openapi.json.