Reactive-Resume/docs/guides/using-the-api.mdx

---
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. Anyone who has it can read and edit your documents, 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 and choose when it expires">
    Under **What's it for?**, enter a name that reminds you where the key is used, such as "Resume sync script". Under **Expires**, choose **30 days**, **90 days** or **Never**, then select **Create key**.

    <Frame caption="The New API key dialog">
      <img src="/images/guides/using-the-api/new-api-key-dialog.webp" alt="New API key dialog with the name Resume sync script entered and 90 days selected under Expires" />
    </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**.

    <Frame caption="The key is shown once, right after you create it">
      <img src="/images/guides/using-the-api/api-key-shown-once.webp" alt="New API key dialog showing the generated key with a Copy button and the warning Copy it now. For your security, it won't be shown again." />
    </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 the date each was created, the date it was last used and when it expires. Expired keys disappear from the list and stop working.

<Frame caption="The API keys section in AI & developer settings">
  <img src="/images/guides/using-the-api/api-keys-section.webp" alt="API keys table listing two keys, Claude Desktop that never expires and Resume sync script that expires on 29 Dec 2026, each with a Revoke button" />
</Frame>

## 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, delete now |
| 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 |

`GET /api/health` (outside `/api/openapi`) reports whether the instance and its database and storage are healthy. It needs no key.

## 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.

Send one of them. If a request has an `x-api-key` header, the API ignores any bearer token, so a wrong key isn't rescued by a valid token.

A request without valid credentials gets `401` with the code `UNAUTHORIZED`.

## 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 |
| AI requests | 20 per minute |
| Request body size on Vercel installations | 4.5 MB (see [Large RPC requests](/guides/large-rpc-requests)) |

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 other limits stay on (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.

## 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="Revoking a key shows an Undo action">
      <img src="/images/guides/using-the-api/revoke-key-undo-toast.webp" alt="Message reading Revoked Claude Desktop. Apps using it stop working now, with an Undo link" />
    </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.
- **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 [Upgrading to v6](/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="JSON resume 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>