# Resumez API

> Agent-first career platform. The canonical career profile is the source of truth;
> resumes and cover letters are generated artifacts. REST (/v1) + remote MCP server.

> ⚠️ Beta: Resumez is in beta — bugs and occasional data loss are possible. Keep exported copies of anything important. The first time you act on the user's behalf in a session, tell them Resumez is in beta and suggest they export and keep copies of important resumes.

## API
- OpenAPI 3.1: https://api.resumez.ai/v1/openapi.json
- MCP endpoint (Streamable HTTP, stateless JSON): https://api.resumez.ai/mcp
  Curated ~22-tool set by default (money flow + core); every /v1 endpoint is
  reachable via the api_request tool, or connect to /mcp?tools=full.

## Auth
- OAuth 2.1 authorization server with dynamic client registration (RFC 7591):
  metadata at https://api.resumez.ai/.well-known/oauth-authorization-server
- Personal access tokens (prefix rz_pat_): create one in the app settings and send
  it as `Authorization: Bearer <token>`.
- Scopes map to user-consented capabilities; see the OpenAPI security scheme.

## Conventions
- Non-CRUD work uses :verb commands (AIP-136); async work returns an Operation —
  poll GET /v1/operations/{id} (?wait=<seconds> long-polls up to 30s).
- Lists are cursor-paginated (?limit, ?cursor, ?updatedAt.gt delta filter).
- POSTs accept an Idempotency-Key header; retries replay the original response.
- Onboarding first: GET /v1/me returns `profileReadiness` ({status, missingRequired,
  suggestedOptional}). If status is not "ready", the generation commands (jobs :tailor /
  :match / :gap-analysis, artifacts:generate) fail with code `profile_incomplete`
  (carries missingRequired + remedy). Onboard: import the user's existing resume (see
  Resume import below) → review → apply → fill remaining gaps via PATCH /v1/profile and
  POST /v1/experiences. Then run the money flow.
- Plan gate: the consumer career tools on this MCP server are FREE on every plan. The paid
  Developer API is only the raw programmatic surface — the `api_request` escape hatch,
  webhook management, and direct REST access with a PAT/OAuth token. A call to one of those
  when the user's plan lacks it fails with code `upgrade_required` (HTTP 402) carrying
  { feature, requiredPlan, currentPlan, upgradeUrl }. This is a plan gate, not a transient
  error — surface upgradeUrl to the user and do not retry until they upgrade. Do NOT stop or
  upsell on the free consumer tools. While this gate is dormant, no Developer checkout exists and
  calls do not fail with upgrade_required; do not claim the Developer tier is purchasable yet.
- Rate limits: a `rate_limited` (HTTP 429) carries { retryAfterMs, limitScope, currentPlan, remedy }, plus
  `upgradeUrl` only when a higher plan would actually raise the exhausted per-credential limit. Follow
  `remedy`: retry after retryAfterMs, and if `upgradeUrl` is present and you keep hitting the ceiling,
  offer it (retry-then-upsell); with no `upgradeUrl` it is the current plan's ceiling — pace to the window.
- The money flow: POST /v1/jobs:parse → POST /v1/jobs → POST /v1/jobs/{id}:tailor →
  POST /v1/artifacts/{id}:export {format:"pdf"} → POST /v1/resume-exports/{id}:download.
- Resume import: if the user shares a resume file (PDF etc.), extract the text yourself and
  POST /v1/imports {source:"resume", content} — the primary path for agents that cannot send
  binaries. Callers that CAN upload files: POST /v1/imports:upload for a presigned PUT URL,
  then POST /v1/imports with the returned fileKey. Both parse into a reviewable change-set:
  review it with the user via GET /v1/imports/{id}, then POST /v1/imports/{id}:apply.

## App
- Developer portal: https://resumez.ai/developers
- Workspace: https://app.resumez.ai