Using the patch API

The patch endpoint lets you make small, targeted changes to a resume's content without sending the whole document. You send a list of JSON Patch (RFC 6902) operations, and the server applies them together and returns the updated resume. This is the same mechanism the MCP server's apply_resume_patch tool uses.

Before you startCopy Anchor Link

• Create an API key and try a first request, as described in Using the API.
• Find the resume's ID with GET /api/openapi/resumes, then fetch its current content with GET /api/openapi/resumes/{id}. Paths in your operations point into the data object of that response.
• Keep the JSON resume schema at hand. It lists every field, its type and which fields a new item needs.

Choose PATCH or PUTCopy Anchor Link

PATCH only changes the resume's data. The name, slug, tags and public setting sit outside data, so change them with PUT, which updates only the fields you send.

Send a patchCopy Anchor Link

PATCH /api/openapi/resumes/{id}
x-api-key: YOUR_API_KEY
Content-Type: application/json

The body holds the operations, and optionally the version of the resume you based them on:

{
  "expectedUpdatedAt": "2026-09-30T00:10:08.197Z",
  "operations": [{ "op": "replace", "path": "/basics/headline", "value": "Senior Game Developer" }]
}

Each operation has these properties:

A successful patch returns 200 with the full updated resume, including its new updatedAt.

ExamplesCopy Anchor Link

Replace basic fieldsCopy Anchor Link

curl -X PATCH "https://hireway.dev/api/openapi/resumes/YOUR_RESUME_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "op": "replace", "path": "/basics/name", "value": "David Kowalski" },
      { "op": "replace", "path": "/basics/headline", "value": "Senior Game Developer" }
    ]
  }'

Add an experience entryCopy Anchor Link

A new entry must be a complete item: include every required field of that item type, a unique id (a UUID) and "hidden": false. Set its dates in dates and leave period empty; the server fills it in.

curl -X PATCH "https://hireway.dev/api/openapi/resumes/YOUR_RESUME_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "add",
        "path": "/sections/experience/items/0",
        "value": {
          "id": "019a0000-0000-7000-8000-000000000001",
          "hidden": false,
          "company": "Northwind Games",
          "position": "Senior Gameplay Engineer",
          "location": "Remote",
          "period": "",
          "dates": { "start": "2024-01", "end": null, "present": true },
          "website": { "url": "", "label": "" },
          "description": "<p>Leading the combat systems team.</p>",
          "roles": []
        }
      }
    ]
  }'

A numeric index inserts at that position (0 puts the entry first). The special index - appends to the end, as in /sections/skills/items/-.

Remove an entryCopy Anchor Link

Remove the second skill:

{ "operations": [{ "op": "remove", "path": "/sections/skills/items/1" }] }

Move an entry within a sectionCopy Anchor Link

Move the first experience entry to the third position:

{ "operations": [{ "op": "move", "from": "/sections/experience/items/0", "path": "/sections/experience/items/2" }] }

Change the designCopy Anchor Link

Switch the template and the primary color:

{
  "operations": [
    { "op": "replace", "path": "/metadata/template", "value": "bronzor" },
    { "op": "replace", "path": "/metadata/design/colors/primary", "value": "rgba(37, 99, 235, 1)" }
  ]
}

Hide a sectionCopy Anchor Link

{ "operations": [{ "op": "replace", "path": "/sections/interests/hidden", "value": true }] }

DatesCopy Anchor Link

Experience (and its roles), education, projects and volunteer entries, and awards, certifications and publications, have a structured dates object:

"dates": { "start": "2022-03", "end": null, "present": true }

Write dates, not the text. Each entry also has a text field, period (ranges) or date (single dates). On every save, the server rewrites that text from dates, in the resume's language and date format (/metadata/page/dateFormat: short, long, numeric or iso). A patch that changes only period or date is overwritten, and the resume keeps its old dates.

To change an entry's dates, replace the whole object:

{
  "operations": [
    {
      "op": "replace",
      "path": "/sections/experience/items/0/dates",
      "value": { "start": "2021", "end": "2024-06", "present": false }
    }
  ]
}

With the long date format, that entry's period becomes "2021 – June 2024". An entry sent without dates (for example from an older export) gets them read from its text.

Avoid overwriting other editsCopy Anchor Link

Someone might edit the resume in the browser between your read and your write. Two tools protect you:

expectedUpdatedAt rejects the whole patch if the resume changed after you read it. Send the updatedAt value from your last read:

{
  "expectedUpdatedAt": "2026-09-30T00:10:08.197Z",
  "operations": [{ "op": "replace", "path": "/basics/headline", "value": "Lead Game Developer" }]
}

If the resume has moved on, you get 409 with the code RESUME_VERSION_CONFLICT and the current updatedAt in data. Read the resume again, rebuild your operations and retry.

test checks a value before the other operations run. If it doesn't match, nothing is applied:

{
  "operations": [
    { "op": "test", "path": "/basics/name", "value": "David Kowalski" },
    { "op": "replace", "path": "/basics/name", "value": "Dave Kowalski" }
  ]
}

What happens when a patch is appliedCopy Anchor Link

• All or nothing. The operations run in order inside one transaction. If any operation fails, or the result doesn't match the resume schema, none of them are saved.
• Validation. The patched resume must pass the same validation as any other save. For example, /metadata/template must be one of the available templates. Rich-text fields such as description and /summary/content are HTML strings, so send HTML (<p>…</p>) rather than plain text or Markdown.
• History. Each successful patch saves a version in the resume's history. It appears as AI edit, described as "from the assistant or API", and you can restore an earlier version from the editor. See Undoing changes and version history.
• Cover letters leave the resume. If a patch adds a section of type cover-letter, the server saves its letter as a separate cover letter linked to the resume and removes the section. Manage letters with the /cover-letters endpoints instead.
• Public resumes update at once. If the resume is public, the change is visible on its public page straight away.

ErrorsCopy Anchor Link

Related guidesCopy Anchor Link

• Using the API: keys, authentication and the other endpoints.
• JSON resume schema: every path and value type you can patch.
• Using the MCP server: let an AI client write these patches for you.