API request and response examples

All examples below use placeholders such as $TOKEN, $API_BASE, $WORKSPACE_UUID, $PROJECT_UUID, $VERSION_KEY, $NODE_ID, and $WORKTYPE_ID. Replace them with values from your own environment and never publish real credentials in source control or client-side code.

This is the most common project-editing flow for an external integration:

choose the workspace,
choose an existing project,
create a new structure version,
read the current lock_version,
update a node,
assign or update estimates,
generate a share link for the client.

1. List workspaces

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/workspaces"

Example response:

{
  "workspaces": [
    {
      "uuid": "83bd8a7f-6af6-4fa3-930d-e1fcf2a0db30",
      "name": "Core Delivery",
      "created_at": "2026-05-01 09:30:00"
    }
  ]
}

2. List projects in the selected workspace

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/projects?workspace=$WORKSPACE_UUID&limit=50&page=1&sort=newest"

3. Create a new structure version from markdown

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version_name": "Client Review v3",
    "structure_markdown": "Service Planner\n===\n# Core\n* description | Core business capabilities.\n** worktypes | Backend, Frontend\n## Authentication\n* description | Login and session management.\n### Login\n* description | User sign-in flow.\n#### Validate credentials\n* description | Validate submitted credentials against the identity provider.\n- Backend: 6 h\n- Frontend: 2 h\n===\n===\n===\n==="
  }' \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures"

Example response:

{
  "project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "version_key": 4,
  "version_name": "Client Review v3",
  "lock_version": 0,
  "created": true
}

4. Read structure details to get the current `lock_version`

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures/$VERSION_KEY"

Example response:

{
  "project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "project_name": "Service Planner MVP",
  "project_status": "in_progress",
  "version_key": 4,
  "version_name": "Client Review v3",
  "version_order": 4,
  "lock_version": 12,
  "updated_at": "2026-05-18 08:30:00",
  "visible": true,
  "locked": false,
  "parser_version": "1.0.0",
  "metadata": {},
  "available": true
}

5. Read the structure tree to discover the target `node_id`

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures/$VERSION_KEY/tree"

Look for a node such as module_auth or feature_login, then use that identifier in mutation calls.

6. Rename a node

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "feature",
    "patch": {
      "name": "Sign-in flow"
    },
    "lock_version": 12
  }' \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures/$VERSION_KEY/nodes/$NODE_ID"

7. Assign a work type if the node does not have one yet

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "feature",
    "worktype_id": 1,
    "lock_version": 13
  }' \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures/$VERSION_KEY/nodes/$NODE_ID/worktypes"

8. Set the estimate for an assigned work type

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "feature",
    "estimate": {
      "time_min_h": 4,
      "time_avg_h": 6,
      "time_max_h": 8
    },
    "lock_version": 14
  }' \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/structures/$VERSION_KEY/nodes/$NODE_ID/worktypes/$WORKTYPE_ID/estimate"

Example response:

{
  "project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "version_key": 4,
  "node_id": "feature_login",
  "node_type": "feature",
  "worktype_id": 1,
  "estimate": {
    "time_min_h": 4,
    "time_avg_h": 6,
    "time_max_h": 8
  },
  "lock_version": 15
}

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/project/$PROJECT_UUID/sharelink?version_key=$VERSION_KEY"

Example response:

{
  "project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "project_name": "Service Planner MVP",
  "version_key": 4,
  "scope": "structure_version",
  "sharelink": "https://client.example.invalid/proposal/acme?v=4"
}

Integration notes for this flow

Always re-use the newest lock_version returned by the most recent successful mutation.
If you receive 409 Conflict, re-read structure details or tree and retry with the fresh lock_version.
The public patch contract for PATCH /nodes/{nodeId} currently focuses on renaming via patch.name.
You can only set an estimate after the work type has been assigned to the node.

Business flow: create a draft from markdown and move it toward review

This flow is useful when your integration starts from a brief and needs a new draft project instead of editing an existing one.

If you need the full syntax reference for structure_markdown, including valid and invalid examples, see Structure Markdown Format.

1. Validate the structure markdown before draft creation

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @draft-structure.json \
  "$API_BASE/api/project/ai/draft/validate"

Where draft-structure.json contains:

{
  "structure_markdown": "Service Planner\n===\n# Core\n* description | Core business capabilities of the platform.\n** worktypes | Backend, Frontend\n## Authentication\n* description | Login, registration and session management.\n### Login\n* description | User login flow.\n#### Validate credentials\n* description | Validate submitted credentials against identity provider.\n- Backend: 6 h\n- Frontend: 2 h\n===\n===\n===\n==="
}

2. Create the draft

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "'$WORKSPACE_UUID'",
    "requirements_summary": "Build a SaaS workspace for planning software delivery, including authentication, structure management, and export-ready estimates.",
    "project_type": "saas",
    "draft_name": "AI Draft - Service Planner",
    "structure_markdown": "Service Planner\n===\n# Core\n* description | Core business capabilities of the platform.\n** worktypes | Backend, Frontend\n## Authentication\n* description | Login, registration and session management.\n### Login\n* description | User login flow.\n#### Validate credentials\n* description | Validate submitted credentials against identity provider.\n- Backend: 6 h\n- Frontend: 2 h\n===\n===\n===\n==="
  }' \
  "$API_BASE/api/project/ai/draft/init"

Example response:

{
  "project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "draft_project_uuid": "8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "draft_url": "https://app.example.invalid/home/editor/project/8f9d0d4f-1f00-4a17-9dd5-f4a90d1f73c2",
  "ai_draft_status": "queued"
}

3. Poll draft status

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/project/ai/draft/$PROJECT_UUID/status"

4. Approve a draft section once it is ready

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"section_path":"Core > Authentication"}' \
  "$API_BASE/api/project/ai/draft/$PROJECT_UUID/approve"

Example markdown for `draft/init`

Use the following as a safe starting template when sending structure_markdown:

Service Planner
===

# Core

* description | Core business capabilities of the platform.
  ** worktypes | Backend, Frontend

## Authentication

* description | Login, registration and session management.

### Login

* description | User login flow.

#### Validate credentials

* description | Validate submitted credentials against identity provider.

- Backend: 6 h
- Frontend: 2 h
  ===
  ===
  ===
  ===

Minimum guidance:

the first line is the project name,
each opened hierarchy level must eventually be closed with a standalone ===,
work types belong at the section level,
estimates belong on the lowest level you use,
structure_markdown is preferred over the legacy draft_structure_markdown alias.

Example error envelope

{
  "status": 403,
  "error": "MCP access denied. Required scope: mcp:write, API key scope: mcp:read",
  "message": "MCP access denied. Required scope: mcp:write, API key scope: mcp:read"
}

Business flow: create a structure version, refine it, estimate it, and share it​

1. List workspaces​

2. List projects in the selected workspace​

3. Create a new structure version from markdown​

4. Read structure details to get the current lock_version​

5. Read the structure tree to discover the target node_id​

6. Rename a node​

7. Assign a work type if the node does not have one yet​

8. Set the estimate for an assigned work type​

9. Generate a structure-version share link​

Integration notes for this flow​

Business flow: create a draft from markdown and move it toward review​

1. Validate the structure markdown before draft creation​

2. Create the draft​

3. Poll draft status​

4. Approve a draft section once it is ready​

Example markdown for draft/init​

Example error envelope​

Business flow: create a structure version, refine it, estimate it, and share it

1. List workspaces

2. List projects in the selected workspace

3. Create a new structure version from markdown

4. Read structure details to get the current `lock_version`

5. Read the structure tree to discover the target `node_id`

6. Rename a node

7. Assign a work type if the node does not have one yet

8. Set the estimate for an assigned work type

9. Generate a structure-version share link

Integration notes for this flow

Business flow: create a draft from markdown and move it toward review

1. Validate the structure markdown before draft creation

2. Create the draft

3. Poll draft status

4. Approve a draft section once it is ready

Example markdown for `draft/init`

Example error envelope