Projects

Patch project document

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.

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

Path parameters

project_idstring required

Headers

Idempotency-Keystring nullable
authorizationstring nullable

Request body

expectedVersioninteger required

Last project version observed by the client.

Example request

{
  "expectedVersion": 7,
  "operations": [
    {
      "node": {
        "id": "node_123",
        "inputs": {
          "inputPrompt": {
            "type": "string",
            "value": "A cinematic wide shot"
          }
        },
        "position": {
          "x": 120,
          "y": 240
        },
        "title": "Text Prompt",
        "type": "builtin/utils/text_prompt"
      },
      "op": "addNode"
    },
    {
      "from": [
        "node_123",
        "outputPrompt"
      ],
      "op": "connect",
      "to": [
        "node_456",
        "inputPrompt"
      ]
    }
  ]
}

Response

The saved editable project document plus patch metadata.

projectIdstring required

Stable project identifier.

versioninteger required

Optimistic concurrency version for the project.

namestring required

Project display name.

metadataobject

Developer-defined project metadata.

externalIdstring nullable

Developer-provided external project/workspace identifier.

externalUserIdstring nullable

Developer-provided end-user identifier.

externalWorkspaceIdstring nullable

Developer-provided workspace/team identifier.

createdAtstring date-time nullable

Project creation timestamp, when available.

updatedAtstring date-time nullable

Most recent project update timestamp, when available.

appliedOperationsinteger required

Number of semantic operations applied.

Example response

{
  "createdAt": "2026-05-21T14:21:52.152049+00:00",
  "document": {
    "graph": {
      "connections": [
        {
          "from": [
            "node_123",
            "text"
          ],
          "to": [
            "node_456",
            "prompt"
          ]
        }
      ],
      "nodes": [
        {
          "id": "node_123",
          "inputs": {
            "inputPrompt": {
              "type": "string",
              "value": "A cinematic wide shot"
            }
          },
          "position": {
            "x": 120,
            "y": 240
          },
          "title": "Text Prompt",
          "type": "builtin/utils/text_prompt"
        }
      ]
    }
  },
  "externalId": "workspace_123",
  "externalUserId": "user_789",
  "externalWorkspaceId": "team_456",
  "metadata": {
    "plan": "pro"
  },
  "name": "Machine",
  "projectId": "proj_123",
  "updatedAt": "2026-05-21T15:10:03.000000+00:00",
  "version": 7,
  "warnings": []
}

Changes

No recorded changes to this operation across all 1 revision of this API.