REST API

Accounts, comments, and invitations#

Registration, sign-in, and recovery use the browser session endpoints. Canvas comments have their own revisions. Read threads at GET /api/projects/:id/comments, post a thread to the same path, reply at POST /api/projects/:id/comments/:commentId/replies, and update status with PATCH /api/projects/:id/comments/:commentId. The complete schemas are in OpenAPI.

Authentication#

In the workspace, open Connect agent and copy the setup instructions to your agent. It registers through POST /api/agent-setups/claimusing the setup token and its chosen name. Store the returned key as PROXIMAFORMA_API_KEY in your private environment, then send it in the Authorization header. The default base URL is http://127.0.0.1:4310/api.

Keys follow their configured canvas scope, permission, expiry, and account membership. Creating setup links and directly managing keys requires the owner’s browser session. Claiming a link needs only its one-time token; the agent cannot expand its access. Never embed a key in public frontend code.

1. Create a project#

curl http://127.0.0.1:4310/api/projects \
  -H "Authorization: Bearer $PROXIMAFORMA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"My application","template":"blank"}'

The response includes the project’s id and current revision. Replace PROJECT_ID in the next example with that returned ID.

2. Add a frame and its headline#

curl http://127.0.0.1:4310/api/projects/PROJECT_ID/operations \
  -H "Authorization: Bearer $PROXIMAFORMA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "revision": 0,
    "operations": [
      {"op":"add","element":{
        "id":"home","type":"frame","name":"Home",
        "width":1200,"height":800,"fill":"#ffffff"
      }},
      {"op":"add","element":{
        "id":"headline","type":"text","parentId":"home",
        "name":"Headline","text":"Your next idea",
        "x":64,"y":80,"width":650,"height":100,
        "fontSize":56,"fontWeight":700
      }}
    ]
  }'

Use the project’s current revision; the example uses 0 for a newly created blank project. The API returns the updated project.

The element model#

Supported types: frame, text, rectangle, ellipse, button, image, and path. Only type is required when adding an element; other properties have defaults.

• parentId: a containing frame’s ID, or null for the canvas.
• x, y, width, height: position relative to the parent and dimensions in design pixels.
• fill, color, stroke: hexadecimal colors. Fill and stroke also accept transparent.
• text, fontSize, fontWeight, textAlign: text content and typography.
• radius, opacity, rotation: appearance and rotation in degrees.
• src: an HTTPS image URL. Text is plain text, not executable HTML.

Vector paths and points#

Create a path through the standard element endpoint. Its vector field contains local width, height, closed, and an array of nodes. Each node has x and y, with optional in and out control points in the same coordinate system. Element width and height scale that geometry.

{
  "element": {
    "type": "path",
    "name": "Curve",
    "x": 40,
    "y": 80,
    "width": 200,
    "height": 100,
    "fill": "transparent",
    "stroke": "#293324",
    "strokeWidth": 3,
    "vector": {
      "width": 200,
      "height": 100,
      "closed": false,
      "nodes": [
        {
          "x": 0,
          "y": 100,
          "out": {
            "x": 60,
            "y": 0
          }
        },
        {
          "x": 200,
          "y": 100,
          "in": {
            "x": 140,
            "y": 0
          }
        }
      ]
    }
  }
}

Use PATCH /api/projects/:id/elements/:elementId/nodes/:index for an individual point, with a zero-based index and a body such as {"edit":{"action":"smooth"},"revision":1}. Actions are move, handles, smooth, corner, split, and delete. Move requires a position; handles accepts in/out coordinates or null to remove a handle. A split adds a midpoint on the outgoing segment while preserving its curve.

Paths require 2–256 anchors; closed paths require at least three. Coordinates and handles must be finite and within −20,000 to 20,000. The point endpoint uses the read revision when one is omitted. Agents can also use create_vector_path, create_vector_shape, and edit_vector_point over MCP.

Endpoint reference#

All paths below are relative to /api.

Revisions, errors, and limits#

Always send the latest revision with edits. A stale request returns 409. Read the project again and reapply the intended change. Invalid batches do not partially modify a design.

Limits: 100 projects, 500 elements per project, 200 operations per batch, 100 agent keys, and 2 MB per request.