The Octopus.do Public API lets you create and manage projects, sitemaps, workspaces, and folders from your own code — the same actions available in the app and to AI agents over MCP. This page mirrors the interactive reference; you can try any request live in the Swagger UI.
Base URL
https://openapi.octopus.doAll paths below are relative to this base — for example GET https://openapi.octopus.do/v1/my. Requests and responses are JSON.
Authentication
Every /v1 endpoint requires authentication. Two schemes are supported:
- API key — send an
X-API-Keyheader. Best for development and server-to-server clients. - OAuth 2.1 (Bearer) — send an
Authorization: Bearer <token>header. Used by ChatGPT and other MCP clients.
There are no separate public register/login REST endpoints — sign-up and sign-in for API consumers go through the OAuth 2.1 flow (/oauth/authorize handles registration and login).
Example request with an API key:
curl https://openapi.octopus.do/v1/my \
-H "X-API-Key: YOUR_API_KEY"Account
GET/v1/my
Returns your profile and every workspace you can access (personal and teams). No parameters.
Projects
POST/v1/projects/create
Creates a project in the target workspace. Returns 201.
| Field | Required | Type | Description |
|---|---|---|---|
workspace_id | Yes | string | Body — destination workspace — a team workspace uuid, or the literal my for your personal space. Required; an empty or omitted value is rejected with an error. |
folder_id | No | string | Body — folder id within the team workspace |
GET/v1/projects/{uuid}
Returns a project's full state — the sitemap tree, pages, blocks, colors, tags, symbols, and sharing/ownership info.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
action_id | No | number | Query — return the project state at a specific action revision |
format | No | string | Query — response format |
POST/v1/projects/{uuid}/duplicate
Duplicates a project into a new one.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
POST/v1/projects/{uuid}/archive
Archives a project.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
POST/v1/projects/{uuid}/unarchive
Restores an archived project.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
POST/v1/projects/{uuid}/move
Moves a project within a team workspace, or back to your personal space. To change the owner instead, use transfer.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
workspace_id | Yes | string | Body — destination workspace — a team workspace uuid, or the literal my for your personal space. Required; an empty value is rejected with an error. |
folder_id | No | string | Body — destination folder id; omit to place it at the team root |
POST/v1/projects/{uuid}/transfer
Transfers project ownership to another user by email.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
email | Yes | string | Body — recipient email; must be a registered, non-free-plan user |
Editing the sitemap
These project-scoped endpoints build and restructure a sitemap — pages (nodes), content blocks, tabs, sections, colors, symbols, tags, arrows, sticky notes, external links, and estimates. They mirror the tools available to AI agents over MCP.
Every write endpoint accepts an optional idempotency_key (string): a unique key that makes retries safe — a repeated request with the same key is applied only once. It is omitted from the tables below.
Batch
POST/v1/projects/{uuid}/batch
Apply several operations as one atomic change. Operations run in order and each sees the effect of the previous ones. Give a created entity a ref and reference it in later operations via *_ref fields (e.g. parent_ref) instead of an id.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
operations | Yes | array | Body — at least one operation (see below) |
dry_run | No | boolean | Body — validate and preview only; nothing is changed |
Each operation:
| Field | Required | Type | Description |
|---|---|---|---|
operation | Yes | string | Operation name, e.g. "nodes.create" |
ref | No | string | Local name for the created entity, referenced later via *_ref fields |
data | No | object | Operation payload — same fields as the matching standalone endpoint |
Operation names follow group.action:
| Group | Actions |
|---|---|
nodes | create, update, move, clone, collapse, delete |
blocks | create, update, move, clone, delete, link-symbol, unlink-symbol |
tabs | create, update, move-up, move-down, clone, delete |
sections | create, update, move-up, move-down, clone, collapse, delete |
colors | create, update, delete |
symbols | create, update, delete |
tags | create, update, delete, assign-node, unassign-node |
arrows | create, update, delete |
sticky-notes | create, update, clone, delete |
external-links | create, update, clone, delete |
estimates | update-settings, add-line-item, update-line-item, delete-line-item, set-value |
settings | update |
Nodes (pages)
POST/v1/projects/{uuid}/nodes/create
Create a node (page).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
parent_id | Yes | string | Body — Parent id — a tab, section or node. A tab parent places the node in its first section |
title | No | string | Body — Page title |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
color_id | No | string | Body — Project color id; defaults to the project's default color |
url | No | string | Body — Page URL/slug shown on the node |
variant | No | enum | Body — default | frame | ghost | stack |
index | No | number | Body — Position among the parent children; omit to append |
POST/v1/projects/{uuid}/nodes/update
Update node fields (title, color, url, variant, SEO notes).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Node id |
title | No | string | Body — New title |
color_id | No | string | Body — Project color id |
url | No | object | null | Body — Page URL/slug; pass null to clear |
variant | No | enum | Body — default | frame | ghost | stack |
notes | No | object | Body — SEO/notes fields to set (merged with existing): note, keywords, page_intent, seo_title, seo_description, seo_h1, seo_slug, seo_url |
POST/v1/projects/{uuid}/nodes/move
Move a node (with its subtree) to another parent.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Node id to move |
parent_id | Yes | string | Body — New parent — a tab, section or node (not the node itself or its subtree) |
index | No | number | Body — Position among the new parent children; omit to append |
POST/v1/projects/{uuid}/nodes/clone
Clone a node with its subtree and blocks.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/nodes/collapse
Collapse or expand a node subtree.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
collapsed | No | boolean | Body — true to collapse (default), false to expand |
POST/v1/projects/{uuid}/nodes/delete
Delete a node with its subtree and blocks.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Node id — deletes the node with its whole subtree and blocks |
Blocks
POST/v1/projects/{uuid}/blocks/create
Create a content block inside a node.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
node_id | Yes | string | Body — Node (page) id the block is created in |
title | No | string | Body — Block title |
content | No | string | Body — Block text content |
wireframes | No | array | Body — Wireframe names to render, e.g. ['header'], ['text', 'cta'] |
color_id | No | string | Body — Project color id; defaults to the project's default color |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
index | No | number | Body — Position within the node; omit to append |
POST/v1/projects/{uuid}/blocks/update
Update block fields (title, content, color, wireframes, flags).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Block id |
title | No | string | Body — New title |
content | No | string | Body — New text content |
color_id | No | string | Body — Project color id |
wireframes | No | array | Body — Wireframe names |
collapsed | No | boolean | Body — |
completed | No | boolean | Body — |
POST/v1/projects/{uuid}/blocks/move
Move a block to another node.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Block id to move |
node_id | Yes | string | Body — Destination node (page) id |
index | No | number | Body — Position within the destination node; omit to append |
POST/v1/projects/{uuid}/blocks/clone
Clone a block.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/blocks/delete
Delete a block.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Block id |
POST/v1/projects/{uuid}/blocks/link-symbol
Link a block to a symbol (it becomes an instance sharing the symbol content).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Monolithic block id to turn into a symbol instance |
symbol_id | Yes | string | Body — Symbol to link the block to |
POST/v1/projects/{uuid}/blocks/unlink-symbol
Detach a block from its symbol (it keeps a standalone copy of the content).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Tabs
POST/v1/projects/{uuid}/tabs/create
Create a tab (a page of the sitemap canvas).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
title | No | string | Body — Tab title |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
index | No | number | Body — Position; omit to append to the end |
POST/v1/projects/{uuid}/tabs/update
Rename a tab.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Tab id |
title | Yes | string | Body — New tab title |
POST/v1/projects/{uuid}/tabs/move-up
Move a tab one position up in the tab list.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/tabs/move-down
Move a tab one position down in the tab list.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/tabs/clone
Clone a tab with all its content.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/tabs/delete
Delete a tab with all its content.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Sections
POST/v1/projects/{uuid}/sections/create
Create a section inside a tab.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
tab_id | Yes | string | Body — Tab id the section is created in |
title | No | string | Body — Section title |
color_id | No | string | Body — Project color id; defaults to the project's default color |
text_size | No | enum | Body — Title text size — l | m | s |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
index | No | number | Body — Position; omit to append |
POST/v1/projects/{uuid}/sections/update
Update section fields (title, color, text size).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Section id |
title | No | string | Body — New title |
color_id | No | string | Body — Project color id |
text_size | No | enum | Body — l | m | s |
POST/v1/projects/{uuid}/sections/move-up
Move a section up within its tab.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/sections/move-down
Move a section down within its tab.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/sections/clone
Clone a section with its content.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/sections/collapse
Collapse or expand a section.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
collapsed | No | boolean | Body — true to collapse (default), false to expand |
POST/v1/projects/{uuid}/sections/delete
Delete a section with its nodes.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Colors
POST/v1/projects/{uuid}/colors/create
Add a color to the project palette.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
hex_code | No | string | Body — Hex color |
title | No | string | Body — Color name shown in the legend |
show_in_legend | No | boolean | Body — Show this color in the map legend |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
POST/v1/projects/{uuid}/colors/update
Update a palette color (name, hex, legend, order).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Color id |
title | No | string | Body — New name |
hex_code | No | string | Body — New hex value |
show_in_legend | No | boolean | Body — |
order | No | number | Body — Position in the palette |
POST/v1/projects/{uuid}/colors/delete
Delete a palette color, repainting everything with a replacement color.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Color id to delete |
replace_with_color_id | Yes | string | Body — Existing color that everything painted with the deleted color switches to |
Symbols
POST/v1/projects/{uuid}/symbols/create
Create a reusable symbol (optionally extracted from an existing block).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
title | No | string | Body — Symbol title |
content | No | string | Body — Symbol text content |
wireframes | No | array | Body — Wireframe names |
color_id | No | string | Body — Project color id; defaults to the project's default color |
from_block_id | No | string | Body — Extract the symbol from this monolithic block: the block content becomes the symbol and the block turns into its first instance |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
POST/v1/projects/{uuid}/symbols/update
Update a symbol — every linked block reflects the change.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Symbol id |
title | No | string | Body — New title |
content | No | string | Body — New text content |
color_id | No | string | Body — Project color id |
wireframes | No | array | Body — Wireframe names |
POST/v1/projects/{uuid}/symbols/delete
Delete a symbol; linked blocks are detached with a copy of the content.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Tags
POST/v1/projects/{uuid}/tags/create
Create a tag.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
title | No | string | Body — Tag title |
color_id | No | string | Body — Project color id; defaults to the project's default color |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
POST/v1/projects/{uuid}/tags/update
Update a tag (title, color, order).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Tag id |
title | No | string | Body — New title |
color_id | No | string | Body — Project color id |
order | No | number | Body — Position in the tag list |
POST/v1/projects/{uuid}/tags/delete
Delete a tag (nodes keep their other tags).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/tags/assign-node
Assign a tag to a node.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Tag id |
node_id | Yes | string | Body — Node id |
POST/v1/projects/{uuid}/tags/unassign-node
Remove a tag from a node.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Tag id |
node_id | Yes | string | Body — Node id |
Arrows
POST/v1/projects/{uuid}/arrows/create
Draw an arrow between two nodes.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
from_id | Yes | string | Body — Source node id |
to_id | Yes | string | Body — Target node id (must differ from from_id) |
type | No | enum | Body — grid | smooth | straight |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
POST/v1/projects/{uuid}/arrows/update
Change an arrow line style.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Arrow id |
type | Yes | enum | Body — Line style — grid | smooth | straight |
POST/v1/projects/{uuid}/arrows/delete
Delete an arrow.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Sticky notes
POST/v1/projects/{uuid}/sticky-notes/create
Place a sticky note on a tab canvas.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
tab_id | Yes | string | Body — Tab id the note is placed on |
content | No | string | Body — Note text |
color | No | enum | Body — Note color — the editor supports exactly three: yellow (#fefa6c), cyan (#c5f1ff), pink (#ffd2fb). Accepts a name or its hex value; default yellow — yellow | cyan | pink | #fefa6c | #c5f1ff | #ffd2fb |
x | No | number | Body — Canvas X position (default 40) |
y | No | number | Body — Canvas Y position (default 40) |
width | No | number | Body — Width in px (default 128, as in the editor) |
height | No | number | Body — Height in px (default 140, as in the editor) |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
index | No | number | Body — |
POST/v1/projects/{uuid}/sticky-notes/update
Update a sticky note (text, color, position, size).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Sticky note id |
content | No | string | Body — New text |
color | No | enum | Body — New color — yellow (#fefa6c), cyan (#c5f1ff) or pink (#ffd2fb); name or hex — yellow | cyan | pink | #fefa6c | #c5f1ff | #ffd2fb |
x | No | number | Body — |
y | No | number | Body — |
width | No | number | Body — |
height | No | number | Body — |
POST/v1/projects/{uuid}/sticky-notes/clone
Clone a sticky note.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/sticky-notes/delete
Delete a sticky note.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
External links
POST/v1/projects/{uuid}/external-links/create
Add an external link card to a tab canvas.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
tab_id | Yes | string | Body — Tab id the link card is placed on |
url | Yes | string | Body — Link URL (http/https) |
title | No | string | Body — Card title |
color_id | No | string | Body — Project color id; defaults to the project's default color |
x | No | number | Body — Canvas X position (default 40) |
y | No | number | Body — Canvas Y position (default 40) |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
index | No | number | Body — |
POST/v1/projects/{uuid}/external-links/update
Update an external link (url, title, color, position).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — External link id |
url | No | string | Body — New URL (http/https) |
title | No | string | Body — New card title |
color_id | No | string | Body — Project color id |
x | No | number | Body — |
y | No | number | Body — |
POST/v1/projects/{uuid}/external-links/clone
Clone an external link.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/external-links/delete
Delete an external link.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
Estimates
POST/v1/projects/{uuid}/estimates/update-settings
Update estimate settings (currency, units, tax, visibility).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
currency | No | string | Body — ISO 4217 code |
units | No | enum | Body — hours / days / weeks — h | d | w |
tax_enabled | No | boolean | Body — Apply tax on top of the total |
tax_value | No | number | Body — Tax percent |
hidden | No | boolean | Body — Hide estimates on the map |
POST/v1/projects/{uuid}/estimates/add-line-item
Add an estimate line item (e.g. Design at 50/unit).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
title | No | string | Body — Line item name |
rate | No | number | Body — Rate per unit (money) |
id | No | string | Body — Client-supplied id; omit to let the server generate one |
POST/v1/projects/{uuid}/estimates/update-line-item
Update an estimate line item (name, rate).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Line item id |
title | No | string | Body — New name |
rate | No | number | Body — New rate per unit |
POST/v1/projects/{uuid}/estimates/delete-line-item
Delete an estimate line item with its per-node values.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
id | Yes | string | Body — Entity id |
POST/v1/projects/{uuid}/estimates/set-value
Set a node's estimate value for a line item (creates it on first use).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
node_id | Yes | string | Body — Node (page) id the estimate belongs to |
line_item_id | Yes | string | Body — Line item id the value is for |
value | Yes | number | Body — Amount of units (e.g. hours) |
Settings
POST/v1/projects/{uuid}/settings/update
Update project settings (title, theme, layout, default color).
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — project uuid |
title | No | string | Body — Project title |
theme | No | enum | Body — blueprint | bold | dark | light |
tree | No | enum | Body — Tree layout — map | matrix |
frame | No | enum | Body — Node frame style — mobile | neutral | web |
mobile | No | boolean | Body — Mobile mode |
image_mode | No | boolean | Body — Show images on nodes |
legend_position | No | enum | Body — bottom | none | top |
default_color_id | No | string | Body — Default color id for new entities |
avatar | No | object | null | Body — Project avatar url; pass null to clear |
Workspaces
GET/v1/workspaces/{uuid}
Returns one workspace: info, members, projects, and folders.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — workspace uuid, or the literal my for your personal workspace. An empty value is rejected with an error. |
Folders
POST/v1/workspaces/{uuid}/folders
Creates a folder in a team workspace.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — workspace uuid |
title | Yes | string | Body — folder title |
PATCH/v1/workspaces/{uuid}/folders/{folder_id}
Renames a folder.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — workspace uuid |
folder_id | Yes | string | Path — folder id |
title | Yes | string | Body — new folder title |
DELETE/v1/workspaces/{uuid}/folders/{folder_id}
Deletes a folder.
| Field | Required | Type | Description |
|---|---|---|---|
uuid | Yes | string | Path — workspace uuid |
folder_id | Yes | string | Path — folder id |
OAuth 2.1
These endpoints implement the OAuth 2.1 / MCP authorization flow. They are called by MCP clients during sign-in — you rarely call them from your own code — and they require no prior authentication.
POST/oauth/token
Exchanges an authorization code for tokens, or rotates a refresh token. Body is application/x-www-form-urlencoded. Errors use the RFC 6749 shape ({ "error": "invalid_grant" }).
| Field | Required | Type | Description |
|---|---|---|---|
grant_type | Yes | enum | authorization_code | refresh_token |
client_id | Yes | string | OAuth client id |
code | No | string | authorization_code grant |
redirect_uri | No | string | authorization_code grant |
code_verifier | No | string | authorization_code grant (PKCE) |
refresh_token | No | string | refresh_token grant |
POST/oauth/register
Dynamic Client Registration (RFC 7591). Registers a public OAuth client; no secret is issued (token_endpoint_auth_method: none).
| Field | Required | Type | Description |
|---|---|---|---|
redirect_uris | Yes | string[] | Allowed redirect URIs |
client_name | No | string | Human-readable client name |
POST/oauth/revoke
Revokes an access or refresh token (RFC 7009). Always returns 200, even for unknown tokens.
| Field | Required | Type | Description |
|---|---|---|---|
token | Yes | string | The token to revoke |
GET/.well-known/oauth-authorization-server
Authorization-server metadata (RFC 8414): the OAuth 2.1 endpoints, supported scopes, grant types, and PKCE methods. Fetched automatically by MCP clients. No parameters.
GET/.well-known/oauth-protected-resource
Protected-resource metadata (MCP authorization spec): declares this API as a protected resource and points to its authorization server. No parameters.
Learn more
- Interactive API reference (Swagger UI): https://openapi.octopus.do/docs
- Use Octopus from AI agents (MCP): Octopus MCP
- Octopus.do: https://octopus.do/