Projects

Replace project document

Replaces the editable project document using optimistic concurrency. The public document graph is validated, translated into Studio's internal bundle shape, and saved as a normal project. Use Idempotency-Key so network retries can replay the saved response.

put/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.

namestring nullable
metadataobject nullable
externalIdstring nullable
externalUserIdstring nullable
externalWorkspaceIdstring nullable

Example request

{
  "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"
        }
      ]
    }
  },
  "expectedVersion": 7,
  "metadata": {
    "plan": "pro"
  },
  "name": "Machine"
}

Response

The saved editable project document.

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.

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.