---
title: "Patch project document"
method: PATCH
path: "/api/v1/projects/{project_id}/document"
tags: ["Projects"]
---

# Patch project document

`PATCH /api/v1/projects/{project_id}/document`

## Request

- Base URL: `https://api.studio.kaitoi.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.studio.kaitoi.io/api/v1/projects/{project_id}/document`
- Auth: HTTP bearer

Applies ordered semantic document operations atomically using optimistic concurrency. The resulting document is validated and saved through the same path as PUT /document. Use Idempotency-Key so network retries can replay the saved response.

## Path parameters

- `project_id` string, required

## Headers

- `Idempotency-Key` string, nullable
- `authorization` string, nullable

## Request body

- PublicProjectDocumentPatchRequest
  - `expectedVersion` integer, required: Last project version observed by the client.
  - `operations` PublicProjectDocumentPatchOperation[], required: Ordered semantic document operations to apply atomically.
    - `op` string, required: Semantic operation name. updateNode.inputs replaces the node's public input map wholesale; use setNodeInput/unsetNodeInput for single-pin edits.

## Response `200`

The saved editable project document plus patch metadata.

- PublicProjectDocumentPatchResponse
  - `projectId` string, required: Stable project identifier.
  - `version` integer, required: Optimistic concurrency version for the project.
  - `name` string, required: Project display name.
  - `metadata` object: Developer-defined project metadata.
  - `externalId` string, nullable: Developer-provided external project/workspace identifier.
  - `externalUserId` string, nullable: Developer-provided end-user identifier.
  - `externalWorkspaceId` string, nullable: Developer-provided workspace/team identifier.
  - `document` PublicProjectDocumentBodyOutput, required
    - `graph` PublicEditableGraphOutput, required
      - `nodes` PublicEditableNode[]: Editable project nodes.
        - `id` string, required: Stable node instance identifier.
        - `type` string, required: Node type identifier.
        - `title` string, nullable: Node display title.
        - `inputs` object: Editable input values keyed by input pin name.
        - `position` PublicEditablePosition
          - `x` number, required: Node X position on the graph canvas.
          - `y` number, required: Node Y position on the graph canvas.
      - `connections` PublicEditableConnection[]: Editable project connections using from/to tuples.
        - `from` unknown[], required: Source node id and output pin name.
          - unknown
        - `to` unknown[], required: Target node id and input pin name.
          - unknown
  - `warnings` PublicProjectDocumentWarning[]: Non-fatal normalization warnings, such as redacted file inputs.
    - `code` string, required: Stable warning code.
    - `message` string, required: Human-readable warning message.
    - `path` string, required: Path to the affected public document field.
  - `createdAt` string, date-time, nullable: Project creation timestamp, when available.
  - `updatedAt` string, date-time, nullable: Most recent project update timestamp, when available.
  - `appliedOperations` integer, required: Number of semantic operations applied.

## Other responses

- `400`: A patch operation is invalid.
- `401`: Missing, malformed, expired, or revoked bearer token.
- `403`: The API key lacks the required scope or account capability.
- `404`: The project does not exist or is not owned by this user.
- `409`: The expected project version is stale.
- `422`: Validation Error
- `429`: The client or API key exceeded the REST API rate limit.
- `503`: The shared REST API rate limiter is temporarily unavailable.

---

[API](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api.md) · [All operations](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kaitoi/apis/kaitoi-rest-api/revisions/239a74aa2c64?raw)