API Reference

Create, read, update, and delete your Brain Boards via the API.

Create a board

Creates a new Brain Board owned by the key's user.

curl -X POST https://api.wovea.ai/v1/boards \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Summer Campaign", "mode": "campaign" }'

{
  "board": {
    "id":        "b1a2c3d4-...",
    "name":      "Summer Campaign",
    "mode":      "campaign",
    "createdAt": "2026-06-30T12:00:00.000Z"
  }
}

Get full board context

Returns everything needed to reconstruct the board: metadata, every collection (with its member file ids and agent notes), every non-deleted file, thought notes, semantic object links, and canvas node positions. Only boards owned by the key's user are accessible. Not paginated — document bodies (private R2 content) are intentionally excluded from files; fetch those via the documents endpoint.

curl https://api.wovea.ai/v1/boards/b1a2c3d4-... \
  -H "Authorization: Bearer wovea_sk_..."

# AI-consumption view — drops agent notes, thought notes, and
# context-toggled-off files
curl "https://api.wovea.ai/v1/boards/b1a2c3d4-...?context=true" \
  -H "Authorization: Bearer wovea_sk_..."

{
  "board": {
    "id": "b1a2c3d4-...", "name": "Summer Campaign", "mode": "campaign",
    "aiEnabled": true, "customCardLabels": null, "canvasMode": false,
    "createdAt": "2026-06-30T12:00:00.000Z", "updatedAt": "2026-06-30T12:00:00.000Z"
  },
  "collections": [
    {
      "id": "c1...", "name": "The Big Idea", "cardType": "core_concept", "layout": "grid",
      "meta": { "description": "...", "hideAgentNotes": false },
      "fileIds": ["f1...", "f2..."],
      "agentNotes": ["Replay test — confirming notes persist."]
    }
  ],
  "files": [
    {
      "id": "f1...", "name": "hero.jpg", "folder": "media", "mimeType": "image/jpeg",
      "url": "https://images.wovea.ai/...", "width": 1600, "height": 900, "size": 240931,
      "title": null, "cardType": null, "tags": null,
      "muxAssetId": null, "muxPlaybackId": null, "videoStatus": null,
      "createdAt": "2026-06-30T12:00:00.000Z"
    }
  ],
  "thoughtNotes": [
    { "id": "n1...", "text": "Remember to...", "tint": "amber", "pinned": false,
      "rotation": -1.8, "authorName": "Lamont", "createdAt": "2026-06-30T12:00:00.000Z" }
  ],
  "objectLinks": [
    { "sourceType": "file", "sourceId": "f1...", "targetType": "file", "targetId": "f2...",
      "label": null, "relation": "supports" }
  ],
  "canvasNodes": [
    { "nodeType": "collection", "objectId": "c1...", "x": 120, "y": 40,
      "width": 392, "height": 320, "zIndex": 0 }
  ]
}

Update a board

Update the board's name or vocabulary mode. At least one field required. Switching to custom seeds labels from the story vocabulary.

curl -X PATCH https://api.wovea.ai/v1/boards/b1a2c3d4-... \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "mode": "custom" }'

{
  "board": { "id": "b1a2c3d4-...", "name": "Summer Campaign", "mode": "custom" }
}

Delete a board

Soft-deletes the board. Permanently removed after 24 hours. Only the board owner can delete.

curl -X DELETE https://api.wovea.ai/v1/boards/b1a2c3d4-... \
  -H "Authorization: Bearer wovea_sk_..."

{ "ok": true }

Scaffold typed collections onto a board. Use the batch variant to create all collections in one request.

Create a collection

Adds a typed collection to a board you own.

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Key Messages", "cardType": "core_concept" }'

{
  "collection": { "id": "c1a2...", "name": "Key Messages", "cardType": "core_concept" }
}

Create collections (batch)

Scaffold multiple collections in a single request by passing { collections: [...] }" instead of a single object.

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "collections": [
      { "name": "Event overview", "cardType": "core_concept" },
      { "name": "Run of show",    "cardType": "context"      },
      { "name": "Speakers",       "cardType": "audience"     }
    ]
  }'

{
  "collections": [
    { "id": "c1a2...", "name": "Event overview", "cardType": "core_concept" },
    { "id": "c2b3...", "name": "Run of show",    "cardType": "context"      },
    { "id": "c3c4...", "name": "Speakers",       "cardType": "audience"     }
  ]
}

Get a collection

Returns one collection with its full member files (not just ids) and agent notes. Use this when you only need a single collection's content rather than the whole board via GET /v1/boards/{boardId}.

curl https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections/c1a2c3d4-... \
  -H "Authorization: Bearer wovea_sk_..."

{
  "collection": {
    "id": "c1a2...", "name": "Key Messages", "cardType": "core_concept", "layout": "grid",
    "meta": { "description": "...", "hideAgentNotes": false },
    "agentNotes": ["Replay test — confirming notes persist."],
    "files": [
      {
        "id": "f1...", "name": "hero.jpg", "folder": "media", "mimeType": "image/jpeg",
        "url": "https://images.wovea.ai/...", "width": 1600, "height": 900, "size": 240931,
        "title": null, "cardType": null, "tags": null,
        "muxAssetId": null, "muxPlaybackId": null, "videoStatus": null,
        "createdAt": "2026-06-30T12:00:00.000Z"
      }
    ]
  }
}

Add file(s) to a collection

Attaches an existing board file to a collection — useful for a file that's currently uncollected, or already sitting in a different collection. This is additive: a file can belong to multiple collections at once (the in-app UI is a per-collection checkbox, not an exclusive move), so this never removes any other membership the file already has. Idempotent — adding a file already in the collection is a no-op for it.

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections/c1a2c3d4-.../files \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "f1a2b3c4-..." }'

{
  "collectionId": "c1a2c3d4-...",
  "fileIds": ["f1a2b3c4-..."]
}

Remove a file from a collection

Drops the file from this collection only — the file itself is untouched and stays on the board (and in any other collection it belongs to), same as removing a file from a collection in the app.

curl -X DELETE https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections/c1a2c3d4-.../files/f1a2b3c4-... \
  -H "Authorization: Bearer wovea_sk_..."

{ "ok": true }

List, import, and upload the images, videos, and PDFs attached to a board. Listing is newest-first and paginated.

List assets

curl "https://api.wovea.ai/v1/boards/b1a2c3d4-.../assets?limit=20&offset=0" \
  -H "Authorization: Bearer wovea_sk_..."

{
  "assets": [
    {
      "id":            "f1a2b3c4-...",
      "name":          "hero.jpg",
      "mimeType":      "image/jpeg",
      "url":           "https://images.wovea.ai/tapestry/users/.../hero.jpg",
      "width":         3840,
      "height":        2160,
      "size":          2097152,
      "title":         "Golden hour rooftop shoot",
      "muxAssetId":    null,
      "muxPlaybackId": null,
      "videoStatus":   null,
      "createdAt":     "2026-06-30T12:00:00.000Z"
    },
    {
      "id":            "f2b3c4d5-...",
      "name":          "intro.mp4",
      "mimeType":      "video/mp4",
      "url":           null,
      "width":         1920,
      "height":        1080,
      "size":          null,
      "title":         null,
      "muxAssetId":    "abc123xyz",
      "muxPlaybackId": "playback456",
      "videoStatus":   "ready",
      "createdAt":     "2026-06-29T09:00:00.000Z"
    }
  ],
  "total":  42,
  "limit":  20,
  "offset": 0
}

Import asset from URL

Fetches a remote image, PDF, or video URL and stores it on the board. Useful for AI agents that find a web resource and want to pin it. HEIC is not supported — convert to JPEG/PNG first.

curl -X POST "https://api.wovea.ai/v1/boards/b1a2c3d4-.../assets/from-url" \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/photo.jpg","name":"Inspiration photo"}'

{
  "id":           "f1a2b3c4-...",
  "name":         "Inspiration photo",
  "mimeType":     "image/jpeg",
  "url":          "https://images.wovea.ai/tapestry/users/.../media/f1a2b3c4-...",
  "size":         204800,
  "boardId":      "b1a2c3d4-...",
  "collectionId": null,
  "createdAt":    "2026-06-30T12:00:00.000Z"
}

Upload file bytes

POST raw file bytes as the request body. Set Content-Type to the file's MIME type. Suitable for AI agents that generate or hold file bytes locally. HEIC is not supported.

curl -X POST "https://api.wovea.ai/v1/boards/b1a2c3d4-.../assets/upload" \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: image/jpeg" \
  -H "X-File-Name: mood-shot.jpg" \
  --data-binary @/path/to/photo.jpg

{
  "id":           "f1a2b3c4-...",
  "name":         "mood-shot.jpg",
  "mimeType":     "image/jpeg",
  "url":          "https://images.wovea.ai/tapestry/users/.../media/f1a2b3c4-...",
  "size":         409600,
  "boardId":      "b1a2c3d4-...",
  "collectionId": null,
  "createdAt":    "2026-06-30T12:00:00.000Z"
}

Add sticky-note style thought cards to a board. Notes appear on the Spatial canvas at the given coordinates.

Create a thought note

Creates a note and places it on the board canvas. All fields are optional — an empty body creates a blank amber note at (0, 0).

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../notes \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "Don\'t forget the hero image", "tint": "sky", "x": 240, "y": 160 }'

{
  "id":           "n1a2b3c4-...",
  "canvasNodeId": "cn1a2b3c-...",
  "text":         "Don't forget the hero image",
  "tint":         "sky",
  "pinned":       false,
  "x":            240,
  "y":            160,
  "createdAt":    "2026-06-30T12:00:00.000Z"
}

Append markdown notes to a specific collection. Notes are agent-authored only — the UI renders them as a semi-transparent watermark behind the collection's card grid so the agent can surface context to the user without polluting the AI context window. Users can hide the watermark per collection via the collection info panel.

Append an agent note

Creates a new note for the collection. Notes accumulate — each POST appends; they are never auto-replaced.

curl -X POST "https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections/c1a2b3c4-.../notes" \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "content": "These shots all lean warm — consider a cooler hero for contrast." }'

{
  "id":           "n1a2b3c4-...",
  "collectionId": "c1a2b3c4-...",
  "content":      "These shots all lean warm — consider a cooler hero for contrast.",
  "createdAt":    "2026-06-30T12:00:00.000Z"
}

List agent notes

Returns all agent notes for the collection, oldest first. Useful for agents that want to avoid duplicating prior observations.

curl "https://api.wovea.ai/v1/boards/b1a2c3d4-.../collections/c1a2b3c4-.../notes" \
  -H "Authorization: Bearer wovea_sk_..."

{
  "notes": [
    {
      "id":        "n1a2b3c4-...",
      "content":   "These shots all lean warm — consider a cooler hero for contrast.",
      "createdAt": "2026-06-30T12:00:00.000Z"
    }
  ]
}

Create plain-text or Markdown documents on a board. Documents are stored in a private R2 bucket and are immediately openable in the Wovea editor at /editor/[id].

Create a document

Creates a document and attaches it to the board. Pass collectionId to place it inside a specific collection.

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../documents \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":     "Creative Brief",
    "content":  "# Objective\n\nLaunch the summer campaign across three channels.",
    "mimeType": "text/markdown"
  }'

{
  "id":           "f1a2b3c4-...",
  "name":         "Creative Brief",
  "mimeType":     "text/markdown",
  "boardId":      "b1a2c3d4-...",
  "collectionId": null,
  "createdAt":    "2026-06-30T12:00:00.000Z"
}

A design kit is a brand-identity manifest — colors, fonts, and voice — attached to a board. It renders as a special collection (name "Design Kit") with a card per color/font plus a "Brand Voice" note, and is what buildOutputBriefing falls back to when generating Collection Outputs. Creating a kit always replaces any existing one on the board — there's only one design kit per board.

Create or replace the design kit

Persists a manifest to the board. Any existing design kit on the board is replaced — only the design kit's own generated cards are removed, never other files. Logo upload isn't supported via this endpoint; attach a logo image separately via the assets API if needed.

curl -X POST https://api.wovea.ai/v1/boards/b1a2c3d4-.../design-kit \
  -H "Authorization: Bearer wovea_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "manifest": {
      "version": "1.0",
      "name": "Summer Campaign",
      "colors": [
        { "name": "Primary Orange", "hex": "#FF7A00", "role": "primary" },
        { "name": "Deep Teal",      "hex": "#004B66", "role": "accent"  }
      ],
      "fonts": [
        { "name": "Spectral", "role": "display", "weightHint": "600" },
        { "name": "DM Sans",  "role": "body",    "weightHint": "400" }
      ],
      "voice": "Warm, direct, a little irreverent."
    }
  }'

{
  "collectionId": "c1a2...",
  "manifest": {
    "version": "1.0", "name": "Summer Campaign",
    "colors": [
      { "name": "Primary Orange", "hex": "#FF7A00", "role": "primary" },
      { "name": "Deep Teal",      "hex": "#004B66", "role": "accent"  }
    ],
    "fonts": [
      { "name": "Spectral", "role": "display", "weightHint": "600" },
      { "name": "DM Sans",  "role": "body",    "weightHint": "400" }
    ],
    "voice": "Warm, direct, a little irreverent."
  }
}

Get the design kit

Returns the board's design kit manifest, or { "designKit": null } if none has been created yet.

curl https://api.wovea.ai/v1/boards/b1a2c3d4-.../design-kit \
  -H "Authorization: Bearer wovea_sk_..."

{
  "collectionId": "c1a2...",
  "designKit": {
    "version": "1.0", "name": "Summer Campaign",
    "colors": [ { "name": "Primary Orange", "hex": "#FF7A00", "role": "primary" } ],
    "fonts":  [ { "name": "Spectral", "role": "display", "weightHint": "600" } ],
    "voice": "Warm, direct, a little irreverent."
  }
}