A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!
TypeScript agent-skillsaidsh-pluginhacktoberfestjavascriptmcp-serverreactresume-builderself-hostedtypescript
---
title: "Using the API"
description: "Create a Reactive Resume API key, send authenticated REST requests to read and edit your resumes, and revoke keys you no longer need."
---
The Reactive Resume REST API lets your own scripts, extensions and automations read and change your documents and job applications. You authenticate with an API key that you create in Settings. This guide walks you through creating a key, making your first request and revoking the key when you're done.
## Before you start
- You need a Reactive Resume account. The examples use the hosted instance at `https://rxresu.me`. If you self-host, replace it with your own address.
- An API key acts as you with the access you choose when you create it. A **Read only** key can read your whole account; a **Read, write and delete** key can also change and delete it. Anyone who has a key can use it, so treat it like a password.
## Create an API key
<Steps>
<Step title="Open AI & developer settings">
Select your name at the bottom of the sidebar, choose **Settings**, then open **AI & developer**. You can also press <kbd>⌘</kbd> <kbd>K</kbd> (<kbd>Ctrl</kbd> <kbd>K</kbd> on Windows and Linux) and type "API keys".
</Step>
<Step title="Start a new key">
In the **API keys** section, select **New key**.
</Step>
<Step title="Name the key, choose its access and expiration">
Under **What's it for?**, enter a name that reminds you where the key is used, such as "Resume sync script". Under **Access**, choose **Read only** unless the tool needs to change your documents; **Read, write and delete** lets it change and delete them too. Under **Expires**, choose **30 days**, **90 days** or **Never**, then select **Create key**. If you signed in more than a day ago, you're asked to sign in again first.
<Frame caption="Name a key and choose its access and expiration">
<img src="/images/guides/using-the-api/new-api-key-dialog.webp" alt="New API key dialog with Resume sync script entered, Read only selected under Access with the note that it can't change or delete anything, 30 days selected under Expires, and Create key" />
</Frame>
</Step>
<Step title="Copy the key">
Select **Copy**, store the key somewhere safe (a password manager or your deployment's secret store), then select **Done**. New keys start with `rr_`, so secret scanners can spot one that leaks into a repository. Send the key in the `x-api-key` header. For an MCP client, **Copy MCP config** copies a ready-to-paste server entry with this instance's address and the key in its header.
<Frame caption="Copy a new key once; example value hidden">
<img src="/images/guides/using-the-api/api-key-shown-once.webp" alt="New API key dialog with the one-time key value hidden for the example, Copy, a reminder to send it in the x-api-key header, Copy MCP config, and Done" />
</Frame>
<Warning>
Reactive Resume shows the key only once. If you lose it, revoke it and create a new one.
</Warning>
</Step>
</Steps>
Your keys are listed in the **API keys** table with their access (**Read only** or **Full access**), the date each was created, the date it was last used and when it expires. The mobile app shows the same details under **Settings → Account → API keys**. Expired keys disappear from the list and stop working.
<Frame caption="Manage API keys from settings">
<img
src="/images/guides/using-the-api/api-keys-section.webp"
alt="API keys table with fictional Resume sync script and Claude Desktop keys, their Read only and Full access levels, creation and expiration dates, last use and Revoke"
/>
</Frame>
## Public sharing settings
Sharing controls belong to resume metadata, outside the resume's `data` object:
| Field | Meaning |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isPublic` | Publishes or unpublishes the web page. Publishing a page that was not public makes the resume primary when the account has no primary resume and the request doesn't set `isPrimary`. |
| `showDownloadButtons` | Allows visitors to download the public PDF. The owner keeps download access. |
| `showInSearchEngines` | Opts a published, non-password-protected resume into search indexing. Defaults to `false`. |
| `hideContactDetails` | Redacts dedicated contact fields from public representations. Defaults to `false`. |
| `isPrimary` | Selects the account's resume for `/<username>` and its verified domain. Only a published resume can become primary. |
New or changed `slug` values must be 1–64 characters: Latin letters a–z and numbers separated by single dashes.
An invalid value returns `INVALID_SLUG` (HTTP 400). Reads and updates that retain an unchanged legacy slug remain
supported. Renames preserve an old address for 30 days.
A slug generated at creation after this change follows the resume's name while the resume has never been published: a
rename or a blank resume's new headline moves it, with no redirect, since nobody has been sent it. Publishing the resume
or setting `slug` keeps the slug from then on. Generated slugs skip addresses that another resume's old address still
redirects from. A headline or name with no writable characters (for example CJK-only or emoji-only text) keeps the
neutral `resume` address, or the next free `resume-N`.
Slugs generated before this change never follow the name. Renaming such a resume keeps its address.
Authenticated custom-domain operations live under `/api/openapi`: `GET /custom-domain`, `PUT /custom-domain` with
`{ "hostname": "resume.example.com" }`, `POST /custom-domain/verify`, and `DELETE /custom-domain`.
The status includes the DNS target, ownership TXT name/value, verification status and last check time. These routes
return `PRECONDITION_FAILED` (HTTP 412) when the operator hasn't enabled custom domains. Use the
API Reference tab for full request and response schemas, and
[Sharing domains](/self-hosting/sharing-domains) for server prerequisites.
Public resume reads, pages and PDFs enforce visibility and password access and omit hidden content and
private notes. The signed-in owner is exempt from their own public password challenge. Visitor PDFs also enforce
the download setting. Downloading the file and recording an explicit visitor download are separate operations;
fetching a PDF alone doesn't record a download event.
Owner-generated preview links are a separate, temporary way to review the public rendering before publication.
Anyone holding that preview link can open it during its 15-minute lifetime, so keep it private.
## Make your first request
The REST API lives under `/api/openapi` on your instance. Send your key in the `x-api-key` header.
```bash
curl "https://rxresu.me/api/openapi/resumes" \
-H "x-api-key: YOUR_API_KEY"
```
The response is a JSON array of your resumes, without their full content:
```json
[
{
"id": "01a0efa5-6529-745e-950a-521ef5b8afc7",
"name": "Game Developer Resume",
"slug": "game-developer-resume",
"tags": ["games"],
"isPublic": false,
"showDownloadButtons": true,
"isLocked": false,
"createdAt": "2026-09-30T00:09:49.101Z",
"updatedAt": "2026-09-30T00:09:49.101Z"
}
]
```
Fetch one resume with its full data, using an ID from the list:
```bash
curl "https://rxresu.me/api/openapi/resumes/01a0efa5-6529-745e-950a-521ef5b8afc7" \
-H "x-api-key: YOUR_API_KEY"
```
For request bodies, send JSON with `Content-Type: application/json`. For example, create a resume filled with sample content:
```bash
curl -X POST "https://rxresu.me/api/openapi/resumes" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Product Designer Resume", "tags": ["design"], "withSampleData": true }'
```
The response is the new resume's ID as a JSON string.
<Tip>
To change a few fields in a resume without sending the whole document, use [JSON Patch](/guides/using-the-patch-api).
</Tip>
## Find the endpoint you need
Every endpoint, with its parameters, request body and responses, is listed in the **API Reference** tab of these docs. Your own instance also serves the machine-readable OpenAPI document at `/api/openapi/spec.json` (for example `https://rxresu.me/api/openapi/spec.json`). Use the spec from the version you run when you generate a client.
| Area | Paths | What you can do |
| ------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Resumes | `/resumes`, `/resumes/{id}` | List, read, create, import, update, patch, lock, duplicate, move to Trash, set a sharing password, download a PDF, read version history and statistics |
| Cover letters | `/cover-letters` | List, read, create, update, duplicate, export and import letters, restore versions, refresh their design from a resume |
| Documents | `/documents` | Work across resumes and letters: rename, tag, lock, link to an application, move to Trash, restore or delete selected documents, empty Trash |
| Applications | `/applications` | Track job applications: stages, notes, interviews, attached PDFs, bulk changes, import, statistics |
| AI | `/ai-providers`, `/ai`, `/agent` | Manage your AI providers, run AI tools such as resume import from PDF, work with assistant conversations |
| Account | `/auth/account/export`, `/auth/account` | Export your account data, delete your account |
Additional app workflows have REST endpoints:
| Workflow | Endpoint |
| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| PDF, JSON Resume, Reactive Resume v4/current, LinkedIn imports | `POST /resumes/file-imports` |
| PDF, Word, OpenDocument, Markdown and JSON exports | `GET /resumes/{id}/exports/{format}`, `GET /cover-letters/{id}/exports/{format}` |
| Editor content checks and job-term matching | `GET /resumes/{id}/checks`, `POST /resumes/{id}/job-matches` |
| Public PDF readability checker | `POST /pdf-checks` |
| File uploads and deletion | `POST /files`, `DELETE /files` |
| Web search integration settings and connection tests | `/integrations/web-access` |
| Sign-in, sessions, profile, passwords, two-factor authentication, passkeys and API keys | `/api/auth/*` (outside `/api/openapi`) |
Authentication workflows use Better Auth's native HTTP API and its own error contract. Your instance publishes their specification at `/api/auth/open-api/generate-schema`; use that specification for the enabled authentication methods. Browser interactions such as zoom, print dialogs and local undo do not require separate server endpoints: use document changes, versions and exports for the corresponding data workflows.
`GET /api/health` (outside `/api/openapi`) reports whether the instance and its database and storage are healthy. It needs no key.
## Imports and exports
File imports accept a multipart form. The format is one of `PDF`, `REACTIVE_RESUME`, `REACTIVE_RESUME_V4`, `JSON_RESUME` or `LINKEDIN`; the maximum file size is 10 MiB. PDF imports read the text layer without AI. AI-assisted PDF and Word parsing remain available under `/ai/pdf-parses` and `/ai/docx-parses`; save the resulting data through `/resumes/imports`.
```bash
curl "https://rxresu.me/api/openapi/resumes/file-imports" \
-H "x-api-key: YOUR_API_KEY" \
-F "format=JSON_RESUME" -F "[email protected]"
curl "https://rxresu.me/api/openapi/resumes/RESUME_ID/exports/docx" \
-H "x-api-key: YOUR_API_KEY" -o resume.docx
```
Exports accept `pdf`, `docx`, `md` or `json` and return a downloadable file. They enforce document ownership. The public checker accepts a multipart `file` (PDF, maximum 25 MB) and optional `jobDescription` text. It stores nothing, examines at most 30 pages and reports truncation or skipped checks. Parsing has a 45-second deadline. Hosting-provider request limits still apply.
## Pagination and partial updates
Collection endpoints support `limit` (1–100) and `offset` (zero-based). For existing array responses, omitting both preserves the complete array for compatibility. Supplying only `offset` selects a page size of 20. The `X-Total-Count` header reports the total before slicing; paginated responses also include `X-Limit` and `X-Offset`. The cover-letter list retains its existing `{ items, total }` response and default pagination.
Applications also expose `GET /applications/summary` for list views. It accepts the same `status`, `tags`, `limit` and `offset` parameters as `GET /applications`, but returns only lightweight list fields and stage/interview activity; job descriptions, notes, requirements, AI metadata and uploaded document fields are omitted. Use `GET /applications/{id}` when you need one application's full details. The original `/applications` response remains unchanged for integrations that need the complete application object.
Set `includeInitialDetails` (0–6) to attach full `initialDetail` objects for the first few applications in the web and mobile default list orders. A value of N includes the union of each client's first N rows, so at most 2N rows receive full details; closed applications are excluded unless explicitly selected with `status`. Omit the parameter to keep the response entirely lightweight.
```bash
curl "https://rxresu.me/api/openapi/resumes?limit=20&offset=20" \
-H "x-api-key: YOUR_API_KEY" -i
```
Use `PATCH` for partial application, interview, timeline-entry and cover-letter updates. Resume content uses JSON Patch at `/resumes/{id}`; metadata uses `PATCH /resumes/{id}/metadata`. Resource-oriented paths such as `/resumes/{id}/copies` and `/documents/{type}/{id}/trash` are preferred for new integrations. Existing verb-based routes, partial `PUT` routes, response shapes and enum values remain supported.
Application cover-letter drafts at `POST /applications/{id}/ai/message-drafts` retain `text` and `coverLetterId`, and add `reviewRequired: true`, recorded `aiOperationIds` and `aiUsage`. The new linked letter's body stays empty: show the text for approval before saving it with `PATCH /cover-letters/{coverLetterId}`, the letter's current `expectedRevision`, and those operation IDs. Convert approved plain text to escaped HTML paragraphs for `content`. Do not treat the returned ID as acceptance of generated text. Follow-up mode still returns text without creating or sending a letter.
`POST /applications/{id}/ai/tailored-resumes` retains `resumeId` and `name`, but generated content is now pending review. It creates an unchanged private copy using the normal copy-for-job rules, then calls the existing assistant with the resume and posting, without private notes, Knowledge or web access. `reviewRequired: true` identifies that boundary. `conversation` contains the canonical pending proposals or clarifying questions and their original model/request references. Open `/builder/{resumeId}?assistant={conversation.thread.id}` to review them in the app, or use the existing guarded resume patch and proposal receipts after explicit approval. Saved applications may link to the copy; submitted document links are preserved. A failed reply returns `generationStatus: "interrupted"` with the unchanged copy and any available conversation. A cancelled request can also leave that copy in Documents. Read before retrying; repeating this operation can create another copy. Creating or accepting a proposal never submits an application.
## Retries
State-changing operations do not implement `Idempotency-Key`. Treat mutations as unsafe to retry automatically, including requests that timed out: the change might already have happened. Read the current resource before deciding whether to repeat a write. Repeating create, copy, import or AI operations can create duplicates or incur provider charges.
Two creates take an optional `newId`, a UUID you choose: creating an application and copying a resume for a job. Repeating the same request with the same `newId` returns what the first one saved, without saving it again. The same `newId` with a different request, one already used by a resume or application, or one whose copy or job has since been deleted or moved to Trash returns `409` (`CONFLICT`) and changes nothing.
`PATCH /applications` bulk moves take optional `expectedStages`: each application's stage, and the ID of its latest stage change, when you chose the move. An application that has changed since is left as it is. The response lists each moved application's stage as saved, with its latest stage change, to send as the expected stage of a later move. Marking an application as applied (`POST /career/workspace/{applicationId}/submit`) and applying a message's changes (`POST /career/saved/{id}/apply`) answer the same way, with `stages`. When `expectedStages` carries a stage change ID, the lane isn't compared: a lane-only move adds a stage change, and a removed stage's applications moving to its replacement isn't a move.
## Authentication methods
The API accepts three kinds of credentials:
1. `x-api-key: <key>`: an API key from Settings. Use this for scripts and servers.
2. `Authorization: Bearer <token>`: an OAuth access token, which MCP clients get when you connect them with OAuth. See [Using the MCP server](/guides/using-the-mcp-server).
3. The session cookie of a signed-in browser.
OAuth clients must send `resource=<instance origin>` (for example `resource=https://rxresu.me`) on authorization, token exchange and refresh requests. Discover the exact resource at `/.well-known/oauth-protected-resource`. Authorization without `resource` is refused with `invalid_target` before sign-in. The error goes to the client's redirect address when the client is enabled and the address exactly matches its registration; otherwise the server answers `400` directly. Guest accounts must create an account before connecting.
Send one credential. When several are present, the server tries API key, bearer token, then session cookie, using the first valid credential. Cookie-authenticated requests with a foreign `Origin` or cross-site fetch metadata are rejected; explicit API keys and bearer tokens do not rely on browser cookies.
Account deletion (`DELETE /auth/account`) requires a browser session; API keys and OAuth tokens receive `403 FORBIDDEN`. Delete your account in **Settings → Account**.
A private request without valid credentials gets `401` with the code `UNAUTHORIZED`. Public operations are marked with `security: []` in the OpenAPI specification. Public resumes still enforce visibility, trash status and sharing passwords, and redact private data.
Replacing or removing an existing application PDF attachment requires `api:delete` as well as `api:write`. Write-only integrations can attach the first file but cannot delete an earlier one by replacing it.
REST data responses use `Cache-Control: no-store`. Uploaded profile images are public; other uploaded files require the owner's credentials, including conditional download requests. Assistant attachments are not exposed through the uploads URL. Unknown and unauthorized file URLs return `404`.
## Limits
| Limit | Value |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Requests per API key | 1,000 per hour |
| Changes to one resume, document or application (create, update, patch, lock, duplicate, delete) | 300 per minute |
| PDF downloads of one resume (`GET /resumes/{id}/pdf`) | 5 per minute |
| PDF downloads across all your resumes | 30 per minute |
| Public PDF checks per client address | 5 per minute |
| REST request body size (before endpoint-specific limits) | 40 MiB |
| AI requests per account (voice transcription and speech count separately) | 20 per minute |
| Request body size on Vercel installations | 4.5 MB (see [Large RPC requests](/guides/large-rpc-requests)) |
Procedure limits apply in production. When you hit a limit, the API responds with `429`. On a self-hosted installation, `FLAG_DISABLE_API_RATE_LIMIT` turns off the per-key limit together with the sign-in limits; the procedure limits also turn off (see [Environment variables](/self-hosting/environment-variables)).
## Errors
Errors come back as JSON with a machine-readable `code`, the HTTP `status` and a `message`. Validation errors also include the failing fields in `data.issues`.
```json
{ "defined": false, "code": "NOT_FOUND", "status": 404, "message": "Not Found" }
```
Branch on `code` rather than on the message text. Invalid input uses `400`, missing authentication `401`, forbidden actions `403`, missing or inaccessible resources `404`, conflicts `409`, oversized requests `413`, rate limits `429`, and unexpected failures `500`. Unexpected failures do not expose internal exception details.
## Revoke a key
<Steps>
<Step title="Find the key">
Open **Settings**, then **AI & developer**. In the **API keys** table, find the key you want to stop.
</Step>
<Step title="Revoke it">
Select **Revoke**. The key stops working at once, and a message confirms which key you revoked.
<Frame caption="Revoke a key you no longer need">
<img src="/images/guides/using-the-api/revoke-key-undo-toast.webp" alt="API key revocation message with Undo for the fictional Resume sync script key, with another key still listed in current settings with standalone Profile navigation" />
</Frame>
</Step>
<Step title="Undo if you revoked the wrong key">
Select **Undo** in the message to turn the key back on. When the message closes, the key is deleted for good.
</Step>
</Steps>
## The RPC endpoint
The web app talks to the server through oRPC at `/api/rpc`, using the same procedures, authorization and validation as the REST API. It uses oRPC's own wire format, and its procedure names follow the app's source code rather than a published contract. For integrations, use the REST API under `/api/openapi`, which has a documented, generated specification.
## Changes from v5
If you built against the v5 API, check these changes:
- **Structured dates.** Dated entries have a `dates` object (`start`, `end`, `present`). The text fields `period` and `date` are still returned, but the server rewrites them from `dates` on every save, so writing only the text has no effect. See [Using the patch API](/guides/using-the-patch-api#dates).
- **Cover letters are their own documents.** Resumes no longer hold cover letters. Use the `/cover-letters` endpoints. If you send a resume that still contains a cover-letter section (for example an old export), the server saves each letter as a separate cover letter and removes the section from the resume.
- **Application link.** `GET /resumes/{id}` includes `applicationId` for a tailored resume. Trash and automatic naming remain managed through the documents API.
- **No cover-letter PDF from resumes.** `GET /resumes/{id}/pdf` only accepts `target=resume` (or no target). Old signed download links that ask for a cover letter return `404`.
- **Delete moves to Trash.** `DELETE /resumes/{id}` and `DELETE /cover-letters/{id}` move the document to Trash for 30 days. Use the `/documents/restore` and `/documents/purge` endpoints to bring it back or delete it at once.
- **Application stages.** The `rejected` stage and the `archived` flag are gone. Close an application with the `closed` stage and a `closedReason` (`not-selected`, `withdrew`, `accepted-other` or `no-response`).
- **Resume versions.** Versions have a `kind` and an optional `name` instead of a free-text label.
Self-hosters upgrading an installation can read [Migrating from v5](/self-hosting/upgrading-to-v6).
## Related guides
<CardGroup cols={2}>
<Card title="Using the patch API" href="/guides/using-the-patch-api">
Change individual fields of a resume with JSON Patch.
</Card>
<Card title="Using the MCP server" href="/guides/using-the-mcp-server">
Let AI clients such as Claude or Cursor work with your documents.
</Card>
<Card title="Reactive Resume JSON schema" href="/guides/json-resume-schema">
The structure of resume data, for validation and code generation.
</Card>
<Card title="Large RPC requests" href="/guides/large-rpc-requests">
How large request bodies reach Vercel installations.
</Card>
</CardGroup>
Stage events may include a server-assigned `writeSequence`. It records write order independently of the editable `at` date; older events may omit it. Career submission and message-apply `stages` answers acknowledge only the stage written by that call. Accepted repeats return an empty array, so they cannot acknowledge a later move from another device. Reload before making another move after a lost response.
`POST /applications/{id}/ai/prepare` returns one review containing pending canonical assistant proposals, an unsaved canonical letter draft and drafts for up to five pasted form questions (2,000 characters each). Approve through the existing guarded resume/letter/workspace writes. `POST /applications/{id}/ai/evidence-proposal` requires an active owned Knowledge fact explicitly mapped to Fit evidence. These routes never submit applications. Numeric match-score results retain their integer contract with additive operation IDs and provider/model request provenance; the qualitative Fit review stays separate.