{ "openapi": "3.1.0", "info": { "title": "Madless API", "version": "1.0.0", "description": "Multi-space SaaS platform API. Provides RESTful endpoints for canvas (knowledge graph), drive, calendar, circle, webhooks, and more.\n\n**For AI agents:** Fetch https://madless.com/llms.txt for workflow recipes, authentication details, and step-by-step guides for common tasks.", "contact": { "name": "Madless API Support", "url": "https://madless.com/docs" } }, "servers": [ { "url": "https://{space}.madless.com", "description": "Production space API", "variables": { "space": { "description": "Your space subdomain", "default": "demo" } } } ], "paths": { "/api/v1/uploads/sign": { "post": { "operationId": "postUploadsSign", "tags": ["Drive: Files"], "summary": "Get a signed upload URL", "security": [ { "bearerAuth": ["drive.upload"] } ], "responses": { "200": { "description": "Get a signed upload URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true, "description": "Signed upload URL (PUT to this URL to upload the file)" }, "object_path": { "type": "string", "description": "GCS object path to pass to POST /drive/files after upload" }, "expires_in": { "type": "string", "description": "URL expiry time in seconds" } } } }, "required": ["data"] }, "example": { "data": { "url": "https://storage.googleapis.com/...", "object_path": "spaces/s_abc/drive/file_xyz", "expires_in": 900 } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["drive.upload"], "x-entitlements": ["drive"], "x-rate-limit": "upload.sign", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "Name of the file to upload (required, 1-500 chars)", "example": "report.pdf" }, "mime": { "type": "string", "description": "MIME type of the file (optional, auto-detected if omitted)", "example": "application/pdf" }, "drive_id": { "type": "string", "description": "Target drive ID (required)", "example": "drv_personal" }, "size": { "type": "integer", "description": "File size in bytes (optional, max 20MB)", "example": 1048576 } }, "required": ["filename", "mime", "drive_id", "size"] }, "example": { "filename": "report.pdf", "mime": "application/pdf", "drive_id": "drv_personal", "size": 1048576 } } } }, "description": "Generates a signed Google Cloud Storage URL for direct file upload. Upload the file using a PUT request to the returned URL, then register it with POST /drive/files to complete the process. URLs expire after 15 minutes." } }, "/api/v1/drive/files": { "get": { "operationId": "getDriveFiles", "tags": ["Drive: Files"], "summary": "List files", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "List files", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriveFile" } } } } ] }, "example": { "data": [ { "id": "file_xyz", "name": "report.pdf", "ext": "pdf", "mime": "application/pdf", "size": 1048576, "status": "active", "drive_id": "drv_personal", "created_by": "usr_abc", "owner_name": "Jane Doe", "created_at": "2026-02-10T14:00:00Z", "updated_at": "2026-02-10T14:00:00Z", "is_starred": false } ], "next_cursor": "file_xyz" } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a paginated list of files with cursor-based pagination. Supports filtering by view (all, starred, deleted, trash), drive ID, and text search via the `q` parameter.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "name": "view", "in": "query", "schema": { "type": "string" }, "description": "Response view mode (e.g. minimal, full)" }, { "name": "drive_id", "in": "query", "schema": { "type": "string" }, "description": "Drive identifier" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query string" }, { "name": "deleted", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Include soft-deleted items" }, { "name": "starred", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Filter by starred status" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Field to sort by" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] }, "description": "Sort direction" } ] }, "post": { "operationId": "postDriveFiles", "tags": ["Drive: Files"], "summary": "Register an uploaded file", "security": [ { "bearerAuth": ["drive.upload"] } ], "responses": { "201": { "description": "Uploaded file created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "file_id": { "type": "string", "description": "ID of the registered file" }, "drive_id": { "type": "string", "description": "ID of the drive the file was registered to" } } } }, "required": ["data"] }, "example": { "data": { "file_id": "file_xyz", "drive_id": "drv_personal" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Registers a file that has already been uploaded to cloud storage via a signed URL, or creates a file record from an external URL. Provide either `object_path` (for signed-URL uploads) or `url` (for external links) -- exactly one is required.", "x-scopes": ["drive.upload"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "File display name (1-255 chars, required)", "example": "report.pdf" }, "mime": { "type": "string", "description": "MIME type of the file", "example": "application/pdf" }, "size": { "type": "integer", "description": "File size in bytes (required, max 20MB)", "example": 1048576 }, "checksum": { "type": "string", "description": "Optional SHA-256 checksum for integrity verification" }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "External URL for link-based files. Required if `object_path` is not provided", "example": "https://example.com/report.pdf" } } }, "example": { "name": "report.pdf", "mime": "application/pdf", "size": 1048576, "drive_id": "drv_personal", "object_path": "spaces/s_abc/drive/file_xyz" } } } } } }, "/api/v1/drive/files/{file_id}": { "parameters": [ { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File identifier" } ], "get": { "operationId": "getDriveFilesByFileId", "tags": ["Drive: Files"], "summary": "Get a file", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "File", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DriveFile" } }, "required": ["data"] }, "example": { "data": { "id": "file_xyz", "name": "report.pdf", "ext": "pdf", "mime": "application/pdf", "size": 1048576, "status": "active", "drive_id": "drv_personal", "created_by": "usr_abc", "owner_name": "Jane Doe", "created_at": "2026-02-10T14:00:00Z", "updated_at": "2026-02-10T14:00:00Z", "is_starred": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files", "description": "Retrieves the full metadata for a single file by its ID, including name, size, MIME type, drive association, starred status, and deletion state." }, "patch": { "operationId": "patchDriveFilesByFileId", "tags": ["Drive: Files"], "summary": "Update a file", "security": [ { "bearerAuth": ["drive.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DriveFile" } }, "required": ["data"] }, "example": { "data": { "id": "file_xyz", "name": "report.pdf", "ext": "pdf", "mime": "application/pdf", "size": 1048576, "status": "active", "drive_id": "drv_personal", "created_by": "usr_abc", "owner_name": "Jane Doe", "created_at": "2026-02-10T14:00:00Z", "updated_at": "2026-02-10T14:00:00Z", "is_starred": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates the metadata of an existing file. Supports renaming, starring/unstarring, and soft-delete toggling. Only the provided fields are modified.", "x-scopes": ["drive.write"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated file name (1-255 chars)", "example": "renamed-report.pdf" }, "starred": { "type": "boolean", "description": "Set to true to star, false to unstar", "example": true }, "deleted": { "type": "integer", "description": "Set to true for soft-delete, false to restore", "example": false } } }, "example": { "name": "renamed-report.pdf" } } } } }, "delete": { "operationId": "deleteDriveFilesByFileId", "tags": ["Drive: Files"], "summary": "Delete a file", "security": [ { "bearerAuth": ["drive.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Deletes a file. First call soft-deletes (moves to trash with configurable retention). Calling delete on an already-trashed file permanently removes it from storage.", "x-scopes": ["drive.write"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "permanent", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Permanently delete (bypass trash)" } ] } }, "/api/v1/storage/info": { "get": { "operationId": "getStorageInfo", "tags": ["Drive: Files"], "summary": "Get storage quota info", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "Storage quota info", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "limit_bytes": { "type": "integer" }, "used": { "type": "string", "description": "Current storage used in bytes" }, "percentage": { "type": "string", "description": "Utilization percentage (0-100)" }, "remaining": { "type": "string", "description": "Remaining storage capacity in bytes" } } } }, "required": ["data"] }, "example": { "data": { "limit_bytes": 26843545600, "used": 52428800, "percentage": 0, "remaining": 26791116800 } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the storage quota limit, current usage, remaining capacity, and utilization percentage. Use this to display storage meters and warn users approaching their quota.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "storage.info" } }, "/api/v1/agent": { "post": { "operationId": "postAgent", "tags": ["Agent"], "summary": "Create agent", "security": [ { "bearerAuth": ["agent.use", "ai.use"] } ], "responses": { "201": { "description": "Agent created", "content": { "application/json": { "schema": { "type": "object", "description": "Response for POST /api/v1/agent", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Starts a DurableAgent workflow for Ask Madless.\nReturns a UIMessageChunk stream with x-workflow-run-id header.", "x-scopes": ["agent.use", "ai.use"], "x-entitlements": ["agent"], "x-rate-limit": "agent.ask", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["messages"], "properties": { "messages": { "type": "array", "items": { "type": "string" } }, "auto_approve": { "type": "string" } } } } } } } }, "/api/v1/agent/{run_id}/stream": { "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "run identifier" } ], "get": { "operationId": "getAgentByRunIdStream", "tags": ["Agent"], "summary": "Get agent stream", "security": [ { "bearerAuth": ["agent.use"] } ], "responses": { "200": { "description": "Agent stream", "content": { "application/json": { "schema": { "type": "object", "description": "Response for GET /api/v1/agent/{runId}/stream", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["agent.use"], "x-entitlements": ["agent"], "x-rate-limit": "agent.ask", "parameters": [ { "name": "start_index", "in": "query", "schema": { "type": "string" }, "description": "Filter or control parameter" } ] } }, "/api/v1/agent/history": { "get": { "operationId": "getAgentHistory", "tags": ["Agent"], "summary": "List agent history", "security": [ { "bearerAuth": ["agent.use"] } ], "responses": { "200": { "description": "List agent history", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" }, "next_cursor": { "type": "string", "nullable": true } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "List agent conversation history for the current user (cursor-paginated).", "x-scopes": ["agent.use"], "x-entitlements": ["agent"], "x-rate-limit": "agent.history", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] } }, "/api/v1/agent/history/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier" } ], "delete": { "operationId": "deleteAgentHistoryById", "tags": ["Agent"], "summary": "Delete agent history", "security": [ { "bearerAuth": ["agent.use"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Delete a single agent history item (ownership-checked).", "x-scopes": ["agent.use"], "x-entitlements": ["agent"], "x-rate-limit": "agent.history", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/agent/hooks": { "post": { "operationId": "postAgentHooks", "tags": ["Agent"], "summary": "Create agent hooks", "security": [ { "bearerAuth": ["agent.write"] } ], "responses": { "201": { "description": "Agent hooks created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["agent.write"], "x-entitlements": ["agent"], "x-rate-limit": "agent.approve", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tool_call_id", "approved"], "properties": { "tool_call_id": { "type": "string", "description": "Unique identifier" }, "approved": { "type": "string" }, "reason": { "type": "string" } } } } } } } }, "/api/v1/calendar/calendars": { "get": { "operationId": "getCalendarCalendars", "tags": ["Calendar: Calendars"], "summary": "List all calendars", "security": [ { "bearerAuth": ["calendar.read"] } ], "responses": { "200": { "description": "List all calendars", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Calendar" } } } } ] }, "example": { "data": [ { "id": "cal_team", "name": "Team Calendar", "color": "#4F46E5", "time_zone": "Europe/London", "visibility": "shared", "archived": false, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } ], "next_cursor": "cal_team" } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all calendars accessible to the current user, including personal and shared team calendars. Supports cursor-based pagination and ETag-based conditional requests for cache efficiency.", "x-scopes": ["calendar.read"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.calendars.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] }, "post": { "operationId": "postCalendarCalendars", "tags": ["Calendar: Calendars"], "summary": "Create a calendar", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "201": { "description": "Calendar created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" }, "time_zone": { "type": "string" }, "visibility": { "type": "string" }, "archived": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "string" } }, "required": [ "id", "name", "color", "time_zone", "visibility", "archived", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "cal_team", "name": "Team Calendar", "color": "#4F46E5", "time_zone": "Europe/London", "visibility": "shared", "archived": false, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new calendar with the specified name, color, time zone, and visibility. Each calendar acts as a container for events and can be shared across the space. Requires an Idempotency-Key header to safely retry without creating duplicates.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Calendar display name (1-200 chars)", "example": "Team Calendar" }, "color": { "type": "string", "nullable": true, "description": "Hex color for UI display (e.g. \"#4F46E5\")", "example": "#4F46E5" }, "visibility": { "type": "string", "description": "Access level: \"private\" (default) or \"shared\"", "example": "shared" } } }, "example": { "name": "Team Calendar", "color": "#4F46E5", "time_zone": "Europe/London", "visibility": "shared" } } } } } }, "/api/v1/calendar/calendars/{calendar_id}": { "parameters": [ { "name": "calendar_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Calendar identifier" } ], "get": { "operationId": "getCalendarCalendarsByCalendarId", "tags": ["Calendar: Calendars"], "summary": "Get a calendar by ID", "security": [ { "bearerAuth": ["calendar.read"] } ], "responses": { "200": { "description": "Calendar by ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Calendar" } }, "required": ["data"] }, "example": { "data": { "id": "cal_team", "name": "Team Calendar", "color": "#4F46E5", "time_zone": "Europe/London", "visibility": "shared", "archived": false, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Retrieves the full details of a specific calendar including its color, time zone, visibility, and archive status. Returns 404 if the calendar does not exist or is not accessible.", "x-scopes": ["calendar.read"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.calendars.read" }, "patch": { "operationId": "patchCalendarCalendarsByCalendarId", "tags": ["Calendar: Calendars"], "summary": "Update a calendar", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Calendar" } }, "required": ["data"] }, "example": { "data": { "id": "cal_team", "name": "Team Calendar", "color": "#4F46E5", "time_zone": "Europe/London", "visibility": "shared", "archived": false, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Partially updates a calendar's properties. Only the provided fields are modified; omitted fields remain unchanged. Supports If-Match concurrency control via ETag to prevent conflicting updates.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.calendars.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated calendar name (1-200 chars)", "example": "Team Calendar" }, "color": { "type": "string", "description": "Updated hex color", "example": "#10B981" }, "visibility": { "type": "string", "description": "Updated access level: \"private\" or \"shared\"", "example": "shared" }, "time_zone": { "type": "string", "description": "Updated IANA time zone", "example": "America/New_York" } } }, "example": { "name": "Team Calendar", "color": "#10B981", "visibility": "shared", "time_zone": "America/New_York" } } } } }, "delete": { "operationId": "deleteCalendarCalendarsByCalendarId", "tags": ["Calendar: Calendars"], "summary": "Delete a calendar", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently deletes a calendar. Returns 409 Conflict if the calendar still contains events; delete or move all events first. This action cannot be undone.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.calendars.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/calendar/events": { "get": { "operationId": "getCalendarEvents", "tags": ["Calendar: Events"], "summary": "List events with date range", "security": [ { "bearerAuth": ["calendar.read"] } ], "responses": { "200": { "description": "List events with date range", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } } } } ] }, "example": { "data": [ { "id": "evt_sprint", "calendar_id": "cal_team", "title": "Sprint Review", "description": "End of sprint demo", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" }, "concept_id": null, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } ], "next_cursor": "evt_sprint" } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns events within an optional date range, filtered by calendar ID, status, or other criteria. Supports cursor-based pagination ordered by start time. Use the `start` and `end` query parameters (epoch milliseconds) to constrain the window.", "x-scopes": ["calendar.read"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "name": "calendar_id", "in": "query", "schema": { "type": "string" }, "description": "Calendar identifier", "required": true }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of date range (ISO 8601)" }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of date range (ISO 8601)" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Field to sort by" }, { "name": "order", "in": "query", "schema": { "type": "string", "enum": ["asc", "desc"] }, "description": "Sort direction" } ] }, "post": { "operationId": "postCalendarEvents", "tags": ["Calendar: Events"], "summary": "Create an event", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "201": { "description": "Event created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "calendar_id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "start": { "type": "object", "properties": { "ts": { "type": "integer" }, "tz": { "type": "string" } }, "required": ["ts", "tz"] }, "end": { "type": "object", "properties": { "ts": { "type": "integer" }, "tz": { "type": "string" } }, "required": ["ts", "tz"] }, "concept_id": { "type": "string", "nullable": true }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "string" } }, "required": [ "id", "calendar_id", "title", "description", "start", "end", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "evt_sprint", "calendar_id": "cal_team", "title": "Sprint Review", "description": "End of sprint demo", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" }, "concept_id": null, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new calendar event linked to a specific calendar. Events support start/end times with timezone awareness. Use `concept_id` to associate the event with a Canvas concept for spaced-repetition reminders. Requires an Idempotency-Key header.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Event title (1-200 chars)", "example": "Sprint Review" }, "description": { "type": "string", "description": "Event description (up to 10,000 chars)", "example": "End of sprint demo" }, "start": { "type": "string", "description": "Start time object: `{ ts (epoch ms), tz (IANA timezone) }`", "example": { "ts": 1709000000000, "tz": "Europe/London" } }, "end": { "type": "string", "description": "End time object: `{ ts (epoch ms), tz (IANA timezone) }`. Must be after start", "example": { "ts": 1709003600000, "tz": "Europe/London" } } } }, "example": { "calendar_id": "cal_team", "title": "Sprint Review", "description": "End of sprint demo", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" } } } } } } }, "/api/v1/calendar/events/{event_id}": { "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Calendar event identifier" } ], "get": { "operationId": "getCalendarEventsByEventId", "tags": ["Calendar: Events"], "summary": "Get an event by ID", "security": [ { "bearerAuth": ["calendar.read"] } ], "responses": { "200": { "description": "Event by ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" } }, "required": ["data"] }, "example": { "data": { "id": "evt_sprint", "calendar_id": "cal_team", "title": "Sprint Review", "description": "End of sprint demo", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" }, "concept_id": null, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Retrieves the full details of a specific event including its time range, description, and linked Canvas concept. Returns 404 if the event does not exist.", "x-scopes": ["calendar.read"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.get" }, "patch": { "operationId": "patchCalendarEventsByEventId", "tags": ["Calendar: Events"], "summary": "Update an event", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CalendarEvent" } }, "required": ["data"] }, "example": { "data": { "id": "evt_sprint", "calendar_id": "cal_team", "title": "Sprint Review", "description": "End of sprint demo", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" }, "concept_id": null, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-01T12:00:00Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Partially updates an event's properties. Only the provided fields are modified; omitted fields remain unchanged. Supports If-Match concurrency control via ETag to prevent conflicting updates.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "calendar_id", "in": "query", "schema": { "type": "string" }, "description": "Filter or control parameter" }, { "name": "calendar_id", "in": "query", "schema": { "type": "string" }, "description": "Calendar identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Updated event title (1-200 chars)", "example": "Sprint Review (Updated)" }, "start": { "type": "object", "properties": { "ts": { "type": "integer" }, "tz": { "type": "string" } }, "description": "Updated start time: `{ ts (epoch ms), tz (IANA timezone) }`", "example": { "ts": 1709000000000, "tz": "Europe/London" } }, "end": { "type": "object", "properties": { "ts": { "type": "integer" }, "tz": { "type": "string" } }, "description": "Updated end time: `{ ts (epoch ms), tz (IANA timezone) }`", "example": { "ts": 1709003600000, "tz": "Europe/London" } } } }, "example": { "title": "Sprint Review (Updated)", "start": { "ts": 1709000000000, "tz": "Europe/London" }, "end": { "ts": 1709003600000, "tz": "Europe/London" } } } } } }, "delete": { "operationId": "deleteCalendarEventsByEventId", "tags": ["Calendar: Events"], "summary": "Delete an event", "security": [ { "bearerAuth": ["calendar.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently deletes a calendar event. This action cannot be undone. Returns 204 No Content on success.", "x-scopes": ["calendar.write"], "x-entitlements": ["calendar"], "x-rate-limit": "calendar.events.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "calendar_id", "in": "query", "schema": { "type": "string" }, "description": "Filter or control parameter" }, { "name": "calendar_id", "in": "query", "schema": { "type": "string" }, "description": "Calendar identifier" } ] } }, "/api/v1/canvas": { "get": { "operationId": "getCanvas", "tags": ["Canvas: Concepts"], "summary": "List concepts", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "List concepts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "description": "Concept title" }, "description": { "type": "string", "nullable": true }, "favicon": { "type": "string", "nullable": true }, "added_at": { "type": "integer" } }, "required": ["title"] }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } } }, "required": ["data"] }, "example": { "data": [ { "id": "con_abc123", "title": "The Art of Fermentation", "visibility": "private", "label_ids": ["lbl_cooking"], "links": [ { "url": "https://example.com", "title": "Reference", "description": null, "favicon": null, "added_at": 1711900800000 } ], "color": "#4A9EFF", "absorb_count": 0, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1711987200000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all concepts for the authenticated space with optional filtering by label, trash status, and semantic text search. When the `q` parameter is provided, concepts are ranked by semantic similarity using OpenAI embeddings -- use `sensitivity` and `mode` to tune precision vs. recall. Responds with ETag for conditional requests; send `If-None-Match` to avoid re-downloading unchanged data.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query string" }, { "name": "label_id", "in": "query", "schema": { "type": "string" }, "description": "Label identifier" }, { "name": "filter", "in": "query", "schema": { "type": "string", "enum": ["active", "trash"] }, "description": "Filter mode (e.g. active, trash)" }, { "name": "sensitivity", "in": "query", "schema": { "type": "string", "enum": ["precise", "balanced", "broad"] }, "description": "Semantic search sensitivity" }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["threshold", "topk"] }, "description": "Search mode" } ] }, "post": { "operationId": "postCanvas", "tags": ["Canvas: Concepts"], "summary": "Create concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "The created concept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "description": "Concept title" }, "description": { "type": "string", "nullable": true }, "favicon": { "type": "string", "nullable": true }, "added_at": { "type": "integer" } }, "required": ["title"] }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "con_abc123", "title": "The Art of Fermentation", "visibility": "private", "label_ids": ["lbl_cooking"], "links": [ { "url": "https://example.com", "title": "Reference", "description": null, "favicon": null, "added_at": 1711900800000 } ], "color": "#4A9EFF", "absorb_count": 0, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1711987200000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new concept and triggers async embedding generation for semantic search. The concept appears in your Canvas immediately; embeddings become available within seconds. Title is optional but recommended -- untitled concepts are harder to find in search. Links are objects with a required `url` and optional `title`, `description`, and `favicon`. Use Pages for rich-text content beyond simple links.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Concept title", "example": "Distributed Consensus Algorithms" }, "label_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" }, "description": "Label IDs to assign (max 20)", "example": ["lbl_research"] }, "links": { "type": "array", "description": "Up to 50 external links. Each is an object: { url (required), title?, description?, favicon? }", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Link URL (required)" }, "title": { "type": "string", "description": "Display title", "nullable": true }, "description": { "type": "string", "description": "Link description", "nullable": true }, "favicon": { "type": "string", "format": "uri", "description": "Favicon URL", "nullable": true } }, "required": ["url"] } }, "color": { "type": "string", "nullable": true, "description": "Display color (hex)", "example": "#6366f1" }, "visibility": { "type": "string", "description": "Access level: \"private\" (default) or \"released\" (shared to Circle)", "example": "private" }, "attached_file_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" }, "description": "Drive file IDs to attach (max 50). Upload files via Drive first." } } }, "example": { "title": "Distributed Consensus Algorithms", "label_ids": ["lbl_research"], "links": [ { "url": "https://raft.github.io/", "title": "The Raft Consensus Algorithm", "description": null, "favicon": "https://raft.github.io/favicon.ico" } ], "visibility": "private", "attached_file_ids": [] } } } } } }, "/api/v1/canvas/{concept_id}": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "get": { "operationId": "getCanvasByConceptId", "tags": ["Canvas: Concepts"], "summary": "Get concept by ID", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "Concept by ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "description": "Concept title" }, "description": { "type": "string", "nullable": true }, "favicon": { "type": "string", "nullable": true }, "added_at": { "type": "integer" } }, "required": ["title"] }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "con_abc123", "title": "The Art of Fermentation", "visibility": "private", "label_ids": ["lbl_cooking"], "links": [ { "url": "https://example.com", "title": "Reference", "description": null, "favicon": null, "added_at": 1711900800000 } ], "color": "#4A9EFF", "absorb_count": 0, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1711987200000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a single concept by ID including all fields, links, labels, attached files, and embedding status. Supports ETag for conditional requests; send `If-None-Match` to receive 304 when unchanged.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.get" }, "patch": { "operationId": "patchCanvasByConceptId", "tags": ["Canvas: Concepts"], "summary": "Update concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "description": "Concept title" }, "description": { "type": "string", "nullable": true }, "favicon": { "type": "string", "nullable": true }, "added_at": { "type": "integer" } }, "required": ["title"] }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "con_abc123", "title": "Consensus in Distributed Systems", "visibility": "private", "label_ids": ["lbl_cooking"], "links": [ { "url": "https://example.com", "title": "Reference", "description": null, "favicon": null, "added_at": 1711900800000 } ], "color": "#4A9EFF", "absorb_count": 0, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1711987200000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Partially updates a concept with only the fields you provide. Label and file assignments use atomic add/remove arrays so concurrent edits do not clobber each other. Changing visibility to \"released\" shares the concept to your Circle and requires `canvas.write` scope. The concept is re-embedded in the background after any content change.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "visibility": { "type": "string", "description": "Change access level: \"private\" or \"released\"" }, "add_file_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" }, "description": "Atomically attach additional files" }, "remove_file_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" }, "description": "Atomically detach files" }, "title": { "type": "string", "description": "Updated title", "example": "Consensus in Distributed Systems" } } }, "example": { "title": "Consensus in Distributed Systems", "add_label_ids": ["lbl_architecture"] } } } } }, "delete": { "operationId": "deleteCanvasByConceptId", "tags": ["Canvas: Concepts"], "summary": "Delete concept permanently", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently and irreversibly deletes a concept, all its relations, linked calendar events, and timeline entries. This cannot be undone. For a recoverable deletion, use the trash endpoint (`POST /{conceptId}/trash`) instead.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/{concept_id}/export.md": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "get": { "operationId": "getCanvasByConceptIdExport.md", "tags": ["Canvas: Concepts"], "summary": "Get canvas export.md", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "Canvas export.md", "content": { "application/json": { "schema": { "type": "object", "description": "Response for GET /api/v1/canvas/{conceptId}/export.md", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Download a single concept as a .md file.\nIf the concept has attachments, returns a ZIP containing the .md + files.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.get" } }, "/api/v1/canvas/{concept_id}/links": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "post": { "operationId": "postCanvasByConceptIdLinks", "tags": ["Canvas: Concepts"], "summary": "Add link to concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Add link to concept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string", "description": "Concept title" }, "description": { "type": "string", "nullable": true }, "favicon": { "type": "string", "nullable": true }, "added_at": { "type": "integer" } }, "required": ["url", "title", "added_at"] }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "color", "absorb_count", "last_interacted_at", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "con_abc123", "title": "The Art of Fermentation", "visibility": "private", "label_ids": ["lbl_cooking"], "links": [ { "url": "https://example.com", "title": "Reference", "description": null, "favicon": null, "added_at": 1711900800000 } ], "color": "#4A9EFF", "absorb_count": 0, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1711987200000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Appends an external URL to the concept's link list and triggers background re-embedding so the link's content becomes searchable. Each concept supports up to 50 links. Returns the full updated concept.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true, "description": "Link URL", "example": "https://raft.github.io/" }, "title": { "type": "string", "description": "Display title", "example": "The Raft Consensus Algorithm" }, "description": { "type": "string", "description": "Link description" }, "favicon": { "type": "string", "description": "Favicon URL for display" } } }, "example": { "url": "https://raft.github.io/", "title": "The Raft Consensus Algorithm", "description": "Official Raft website" } } } } }, "delete": { "operationId": "deleteCanvasByConceptIdLinks", "tags": ["Canvas: Concepts"], "summary": "Remove link from concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Removes a specific URL from the concept's link list by exact URL match. The concept is re-embedded in the background to update semantic search. Returns 204 on success.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the link to remove", "example": "https://raft.github.io/" } } }, "example": { "url": "https://raft.github.io/" } } } } } }, "/api/v1/canvas/{concept_id}/restore": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "post": { "operationId": "postCanvasByConceptIdRestore", "tags": ["Canvas: Concepts"], "summary": "Restore trashed concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Restore trashed concept", "content": { "application/json": { "schema": { "type": "object", "description": "Response for POST /api/v1/canvas/{conceptId}/restore", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Restores a previously trashed concept back to active status. Relations that were removed during trashing are not automatically restored -- you will need to recreate them. Returns 204 No Content.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.restore", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/{concept_id}/timeline": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "get": { "operationId": "getCanvasByConceptIdTimeline", "tags": ["Canvas: Timeline"], "summary": "List timeline entries", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "List timeline entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique timeline entry identifier" }, "kind": { "type": "string", "description": "Entry kind: manual (user-created) or auto (system-generated)" }, "content": { "type": "string", "description": "Entry text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the entry creator" } }, "required": ["id", "kind", "content", "created_at", "created_by"] } } }, "required": ["data"] }, "example": { "data": [ { "id": "tle_m3n4o5", "kind": "manual", "content": "Read the original Paxos paper and added key insights.", "created_at": "2026-02-22T14:15:00Z", "created_by": "usr_abc123" }, { "id": "tle_a1b2c3", "kind": "auto", "content": "Concept created", "auto_meta": { "event_type": "concept_created" }, "created_at": "2026-02-20T10:30:00Z", "created_by": "usr_abc123" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns timeline entries for a concept with cursor-based pagination. Includes both manual user entries and auto-generated system events (concept_created, connection_created, migrated_notes). On first access for legacy concepts, auto-migrates the concept's notes field into timeline entries.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.timeline.list" }, "post": { "operationId": "postCanvasByConceptIdTimeline", "tags": ["Canvas: Timeline"], "summary": "Add timeline entry", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Add timeline entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique timeline entry identifier" }, "kind": { "type": "string", "description": "Entry kind: manual (user-created) or auto (system-generated)" }, "content": { "type": "string", "description": "Entry text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the entry creator" } }, "required": ["id", "kind", "content", "created_at", "created_by"] } }, "required": ["data"] }, "example": { "data": { "id": "tle_m3n4o5", "kind": "manual", "content": "Read the original Paxos paper and added key insights.", "created_at": "2026-02-22T14:15:00Z", "created_by": "usr_abc123" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Adds a manual timeline entry to a concept. Timeline entries capture your evolving thinking about a concept over time. The concept is re-embedded in the background so the new content becomes searchable.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.timeline.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Entry text content (1-500,000 chars)", "example": "Read the original Paxos paper and added key insights." } } }, "example": { "content": "Read the original Paxos paper and added key insights." } } } } } }, "/api/v1/canvas/{concept_id}/timeline/{entry_id}": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" }, { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "entry identifier" } ], "patch": { "operationId": "patchCanvasByConceptIdTimelineByEntryId", "tags": ["Canvas: Timeline"], "summary": "Update timeline entry", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique timeline entry identifier" }, "kind": { "type": "string", "description": "Entry kind: manual (user-created) or auto (system-generated)" }, "content": { "type": "string", "description": "Entry text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the entry creator" } }, "required": ["id", "kind", "content", "created_at", "created_by"] } }, "required": ["data"] }, "example": { "data": { "id": "tle_m3n4o5", "kind": "manual", "content": "Read the original Paxos paper — key insight: single-decree vs multi-decree.", "created_at": "2026-02-22T14:15:00Z", "created_by": "usr_abc123" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates the content of a manual timeline entry. Only manual entries can be edited -- attempting to edit an auto-generated entry returns 403 Forbidden. The concept is re-embedded in the background after the update.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.timeline.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Updated entry text content (1-500,000 chars)" } } }, "example": { "content": "Read the original Paxos paper — key insight: single-decree vs multi-decree." } } } } }, "delete": { "operationId": "deleteCanvasByConceptIdTimelineByEntryId", "tags": ["Canvas: Timeline"], "summary": "Delete timeline entry", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Soft-deletes a manual timeline entry. Only manual entries can be deleted -- attempting to delete an auto-generated entry returns 403 Forbidden. Idempotent -- returns 204 No Content if already deleted.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.timeline.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/{concept_id}/trash": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "post": { "operationId": "postCanvasByConceptIdTrash", "tags": ["Canvas: Concepts"], "summary": "Trash concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Trash concept", "content": { "application/json": { "schema": { "type": "object", "description": "Response for POST /api/v1/canvas/{conceptId}/trash", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Soft-deletes a concept by moving it to trash and removing its relations. The concept can be restored later via the restore endpoint, but relations must be recreated manually. Returns 204 No Content.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/export/mdl": { "post": { "operationId": "postCanvasExportMdl", "tags": ["Canvas: Concepts"], "summary": "Create export mdl", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "201": { "description": "Export mdl created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "export_id": { "type": "string", "description": "Unique identifier" }, "status": { "type": "string" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Start an async bulk MDL export. Returns an exportId to poll.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "export.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/export/mdl/{export_id}": { "parameters": [ { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "export identifier" } ], "get": { "operationId": "getCanvasExportMdlByExportId", "tags": ["Canvas: Concepts"], "summary": "Get export mdl", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "Export mdl", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "export_id": { "type": "string", "description": "Unique identifier" }, "status": { "type": "string" }, "download_url": { "type": "string", "format": "uri", "nullable": true }, "counts": { "type": "array", "items": { "type": "integer" } }, "size_bytes": { "type": "array", "items": { "type": "string" } }, "error": { "type": "string", "nullable": true }, "started_at": { "type": "integer", "description": "Unix timestamp (ms)" }, "completed_at": { "type": "integer", "description": "Unix timestamp (ms)" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Poll export status. If complete, includes download URL.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.list" } }, "/api/v1/canvas/import": { "post": { "operationId": "postCanvasImport", "tags": ["Canvas: Concepts"], "summary": "Create canvas import", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "Canvas import created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "format": { "type": "string" }, "imported": { "type": "string" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Full import from any supported format.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "format": { "type": "string" }, "on_duplicate": { "type": "string" } } } } } } } }, "/api/v1/canvas/import/preview": { "post": { "operationId": "postCanvasImportPreview", "tags": ["Canvas: Concepts"], "summary": "Create import preview", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "201": { "description": "Import preview created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "format": { "type": "string" }, "counts": { "type": "array", "items": { "type": "integer" } } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Dry-run: parse an uploaded file/ZIP and return counts + warnings.\nNo data is written.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.list", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "format": { "type": "string" } } } } } } } }, "/api/v1/canvas/labels": { "get": { "operationId": "getCanvasLabels", "tags": ["Canvas: Labels"], "summary": "List labels", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "List labels", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique label identifier" }, "name": { "type": "string", "description": "Label display name" }, "icon": { "type": "string", "description": "Icon identifier or null" }, "color": { "type": "string", "description": "Display color (hex)" }, "order": { "type": "integer", "description": "Sort position (0-based)" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" } }, "required": ["id", "name", "color", "created_at", "updated_at"] } } }, "required": ["data"] }, "example": { "data": [ { "id": "lbl_research", "name": "Research", "icon": "beaker", "color": "#6366f1", "order": 0, "created_at": "2026-01-15T09:00:00Z", "updated_at": "2026-01-15T09:00:00Z" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all concept labels for the space, sorted by the `order` field. Labels are used to organize concepts into categories. Supports ETag for conditional requests; send `If-None-Match` to receive 304 when unchanged.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.labels.list" }, "post": { "operationId": "postCanvasLabels", "tags": ["Canvas: Labels"], "summary": "Create label", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "Label created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique label identifier" }, "name": { "type": "string", "description": "Label display name" }, "icon": { "type": "string", "description": "Icon identifier or null" }, "color": { "type": "string", "description": "Display color (hex)" }, "order": { "type": "integer", "description": "Sort position (0-based)" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" } }, "required": ["id", "name", "color", "created_at", "updated_at"] } }, "required": ["data"] }, "example": { "data": { "id": "lbl_research", "name": "Research", "icon": "beaker", "color": "#6366f1", "order": 0, "created_at": "2026-01-15T09:00:00Z", "updated_at": "2026-01-15T09:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new label for organizing concepts on your Canvas. Labels have a name, optional icon, color, and sort order. Assign labels to concepts via the concept create or update endpoints.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.labels.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Label name", "example": "Research" }, "icon": { "type": "string", "format": "uri", "nullable": true, "description": "Icon identifier", "example": "beaker" }, "color": { "type": "string", "nullable": true, "description": "Display color", "example": "#6366f1" }, "order": { "type": "integer", "description": "Sort order (0-based)", "example": 0 } } }, "example": { "name": "Research", "icon": "beaker", "color": "#6366f1", "order": 0 } } } } } }, "/api/v1/canvas/labels/{label_id}": { "parameters": [ { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Label identifier" } ], "patch": { "operationId": "patchCanvasLabelsByLabelId", "tags": ["Canvas: Labels"], "summary": "Update label", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique label identifier" }, "name": { "type": "string", "description": "Label display name" }, "icon": { "type": "string", "description": "Icon identifier or null" }, "color": { "type": "string", "description": "Display color (hex)" }, "order": { "type": "integer", "description": "Sort position (0-based)" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" } }, "required": ["id", "name", "color", "created_at", "updated_at"] } }, "required": ["data"] }, "example": { "data": { "id": "lbl_research", "name": "Research", "icon": "beaker", "color": "#6366f1", "order": 0, "created_at": "2026-01-15T09:00:00Z", "updated_at": "2026-01-15T09:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Partially updates a label's name, icon, color, or sort order. Only the fields you provide are changed. At least one field is required.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.labels.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated name" } } }, "example": { "name": "Updated Research", "color": "#10B981", "order": 1 } } } } }, "delete": { "operationId": "deleteCanvasLabelsByLabelId", "tags": ["Canvas: Labels"], "summary": "Delete label", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently deletes a label and removes it from the `label_ids` array of every concept that references it. Returns 204 No Content.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.labels.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/layout": { "get": { "operationId": "getCanvasLayout", "tags": ["Canvas: Layout"], "summary": "Get canvas layout", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "Canvas layout", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "views": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nodes": { "type": "object", "properties": { "cpt_8f3a2b1c": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] }, "cpt_4d6e8f0a": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] } }, "required": ["cpt_8f3a2b1c", "cpt_4d6e8f0a"] }, "viewport": { "type": "object", "properties": { "zoom": { "type": "integer" }, "pan_x": { "type": "integer" }, "pan_y": { "type": "integer" } }, "required": ["zoom", "pan_x", "pan_y"] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": ["id", "name", "nodes", "viewport", "created_at", "updated_at"] }, "description": "Array of saved canvas views with node positions and viewport settings" } }, "required": ["views"] } }, "required": ["data"] }, "example": { "data": { "views": [ { "id": "view_arch1", "name": "System Architecture", "nodes": { "cpt_8f3a2b1c": { "x": 120, "y": 340 }, "cpt_4d6e8f0a": { "x": 450, "y": 200 } }, "viewport": { "zoom": 1, "pan_x": 0, "pan_y": 0 }, "created_at": "2026-02-22T10:00:00Z", "updated_at": "2026-02-22T14:30:00Z" } ] } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the full canvas layout state for the authenticated user, including all saved views with node positions, viewport settings, and named clusters. Returns `{ data: null }` if the user has not created any views yet.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.layout.list" } }, "/api/v1/canvas/layout/views": { "post": { "operationId": "postCanvasLayoutViews", "tags": ["Canvas: Layout"], "summary": "Create canvas view", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "Canvas view created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique view identifier" }, "name": { "type": "string", "description": "View display name" }, "nodes": { "type": "object", "properties": { "cpt_8f3a2b1c": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] }, "cpt_4d6e8f0a": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] } }, "required": ["cpt_8f3a2b1c", "cpt_4d6e8f0a"], "description": "Node positions keyed by concept ID" }, "viewport": { "type": "object", "properties": { "zoom": { "type": "integer" }, "pan_x": { "type": "integer" }, "pan_y": { "type": "integer" } }, "required": ["zoom", "pan_x", "pan_y"], "description": "Viewport state: zoom, pan_x, pan_y" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" } }, "required": ["id", "name", "nodes", "viewport", "created_at", "updated_at"] } }, "required": ["data"] }, "example": { "data": { "id": "view_arch1", "name": "System Architecture", "nodes": { "cpt_8f3a2b1c": { "x": 120, "y": 340 }, "cpt_4d6e8f0a": { "x": 450, "y": 200 } }, "viewport": { "zoom": 1, "pan_x": 0, "pan_y": 0 }, "created_at": "2026-02-22T10:00:00Z", "updated_at": "2026-02-22T14:30:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new named canvas view with initial node positions and viewport settings. Views let you save different visual arrangements of your Canvas (e.g., by topic, project, or time period). Each user can have multiple views.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.layout.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "View name", "example": "System Architecture" }, "nodes": { "type": "object", "properties": { "cpt_8f3a2b1c": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] }, "cpt_4d6e8f0a": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] } }, "required": ["cpt_8f3a2b1c", "cpt_4d6e8f0a"], "description": "Node positions keyed by concept ID: `{ [conceptId]: { x, y } }`" }, "viewport": { "type": "object", "properties": { "zoom": { "type": "integer" }, "pan_x": { "type": "integer" }, "pan_y": { "type": "integer" } }, "required": ["zoom", "pan_x", "pan_y"], "description": "Initial viewport: `{ zoom, panX, panY }`" } }, "required": ["name", "nodes", "viewport"] }, "example": { "name": "System Architecture", "nodes": { "cpt_8f3a2b1c": { "x": 120, "y": 340 }, "cpt_4d6e8f0a": { "x": 450, "y": 200 } }, "viewport": { "zoom": 1, "pan_x": 0, "pan_y": 0 } } } } } } }, "/api/v1/canvas/layout/views/{view_id}": { "parameters": [ { "name": "view_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canvas view identifier" } ], "put": { "operationId": "putCanvasLayoutViewsByViewId", "tags": ["Canvas: Layout"], "summary": "Save canvas view", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "description": "Response for PUT /api/v1/canvas/layout/views/{viewId}", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Overwrites the full layout state for an existing canvas view. Call this to persist node positions and viewport after the user rearranges concepts on the Canvas. Nodes not present in the payload are removed from the view.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.layout.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "type": "string" }, "description": "Record of node positions keyed by concept ID. Each value is an object: `{ x, y }` (required), plus optional `autoPlaced`, `expanded`, `userScale`, `cardWidth`, `cardHeight`, `cardDisplay` (\"both\"|\"text\"|\"image\")" }, "viewport": { "type": "string", "description": "Viewport state object: `{ zoom (0.1-5), panX (number), panY (number) }`" } } }, "example": { "nodes": { "cpt_8f3a2b1c": { "x": 150, "y": 350, "auto_placed": false }, "cpt_4d6e8f0a": { "x": 480, "y": 220, "expanded": true } }, "viewport": { "zoom": 1.2, "pan_x": -50, "pan_y": 30 } } } } } }, "patch": { "operationId": "patchCanvasLayoutViewsByViewId", "tags": ["Canvas: Layout"], "summary": "Rename canvas view", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "description": "Response for PATCH /api/v1/canvas/layout/views/{viewId}", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates the display name of an existing canvas view. Only the name can be changed -- use PUT to update node positions and viewport. Returns 204 No Content.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.layout.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New view name", "example": "Architecture v2" } } }, "example": { "name": "Architecture v2" } } } } }, "delete": { "operationId": "deleteCanvasLayoutViewsByViewId", "tags": ["Canvas: Layout"], "summary": "Delete canvas view", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently deletes a canvas view and all its saved node positions, viewport settings, and named clusters. This does not affect the concepts themselves. Returns 204 No Content.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.layout.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/pages": { "get": { "operationId": "getCanvasPages", "tags": ["Canvas: Pages"], "summary": "List pages", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "List pages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" }, "example": { "data": [ { "id": "page_abc", "concept_id": "cpt_8f3a2b1c", "title": "The Complete Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Consensus algorithms ensure all nodes agree..." } ], "word_count": 3500, "read_time": 12, "created_at": "2026-02-20T10:30:00Z", "updated_at": "2026-02-20T10:30:00Z", "created_by": "usr_abc123" } ], "next_cursor": null } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns pages in the space with cursor-based pagination. Supports filtering by linked concept ID. Responds with ETag for conditional requests; send `If-None-Match` to receive 304 when unchanged.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] }, "post": { "operationId": "postCanvasPages", "tags": ["Canvas: Pages"], "summary": "Create page", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "Page created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique page identifier" }, "concept_id": { "type": "string", "description": "Linked concept ID" }, "title": { "type": "string", "description": "Page title" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string", "description": "Page title" }, "content": { "type": "string" } }, "required": ["type", "title", "content"] }, "description": "Array of rich-text sections" }, "word_count": { "type": "integer", "description": "Total word count across all sections" }, "read_time": { "type": "integer", "description": "Estimated read time in minutes" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the page creator" } }, "required": [ "id", "concept_id", "title", "sections", "word_count", "read_time", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "page_abc", "concept_id": "cpt_8f3a2b1c", "title": "The Complete Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Consensus algorithms ensure all nodes agree..." } ], "word_count": 3500, "read_time": 12, "created_at": "2026-02-20T10:30:00Z", "updated_at": "2026-02-20T10:30:00Z", "created_by": "usr_abc123" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "Page title (required)", "example": "The Complete Guide to Consensus Algorithms" }, "sections": { "type": "array", "items": { "type": "string" }, "description": "Array of section objects with type and content (max 100)" } } }, "example": { "concept_id": "cpt_8f3a2b1c", "title": "The Complete Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Consensus algorithms ensure all nodes agree on a single value..." }, { "type": "text", "title": "Paxos", "content": "Paxos was introduced by Leslie Lamport in 1989..." } ] } } } }, "description": "Creates a rich-text page linked to a concept for long-form content. Each concept supports up to 5 pages; exceeding this returns 409 Conflict. Sections support types: text, heading, code, image, quote, divider, toggle, and callouts (info, warning, tip, success). Word count and estimated read time are computed server-side." } }, "/api/v1/canvas/pages/{page_id}": { "parameters": [ { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Page identifier" } ], "get": { "operationId": "getCanvasPagesByPageId", "tags": ["Canvas: Pages"], "summary": "Get page by ID", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "Page by ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique page identifier" }, "concept_id": { "type": "string", "description": "Linked concept ID" }, "title": { "type": "string", "description": "Page title" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string", "description": "Page title" }, "content": { "type": "string" } }, "required": ["type", "title", "content"] }, "description": "Array of rich-text sections" }, "word_count": { "type": "integer", "description": "Total word count across all sections" }, "read_time": { "type": "integer", "description": "Estimated read time in minutes" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the page creator" } }, "required": [ "id", "concept_id", "title", "sections", "word_count", "read_time", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "page_abc", "concept_id": "cpt_8f3a2b1c", "title": "The Complete Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Consensus algorithms ensure all nodes agree..." } ], "word_count": 3500, "read_time": 12, "created_at": "2026-02-20T10:30:00Z", "updated_at": "2026-02-20T10:30:00Z", "created_by": "usr_abc123" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.get", "description": "Returns a page by ID including its full rich-text sections, linked concept ID, word count, and read time. Supports ETag for conditional requests; send `If-None-Match` to receive 304 when unchanged." }, "patch": { "operationId": "patchCanvasPagesByPageId", "tags": ["Canvas: Pages"], "summary": "Update page", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique page identifier" }, "concept_id": { "type": "string", "description": "Linked concept ID" }, "title": { "type": "string", "description": "Page title" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string", "description": "Page title" }, "content": { "type": "string" } }, "required": ["type", "title", "content"] }, "description": "Array of rich-text sections" }, "word_count": { "type": "integer", "description": "Total word count across all sections" }, "read_time": { "type": "integer", "description": "Estimated read time in minutes" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the page creator" } }, "required": [ "id", "concept_id", "title", "sections", "word_count", "read_time", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "page_abc", "concept_id": "cpt_8f3a2b1c", "title": "Updated Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Consensus algorithms ensure all nodes agree..." } ], "word_count": 3500, "read_time": 12, "created_at": "2026-02-20T10:30:00Z", "updated_at": "2026-02-20T10:30:00Z", "created_by": "usr_abc123" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "string" }, "description": "Updated sections array (max 100)" }, "title": { "type": "string", "description": "Updated page title (max 200 chars)", "example": "Updated Guide" } } }, "example": { "title": "Updated Guide to Consensus Algorithms", "sections": [ { "type": "text", "title": "Introduction", "content": "Updated introduction..." } ] } } } }, "description": "Partially updates a page -- only the fields you provide are changed. If sections contain @-mentions of other concepts, relations are automatically created. Word count and read time are recomputed server-side after any content change." }, "delete": { "operationId": "deleteCanvasPagesByPageId", "tags": ["Canvas: Pages"], "summary": "Delete page", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "description": "Soft-deletes a page by moving it to trash. The page can be restored within the retention period. Returns 204 No Content." } }, "/api/v1/canvas/pages/reorder": { "patch": { "operationId": "patchCanvasPagesReorder", "tags": ["Canvas: Pages"], "summary": "Reorder pages within a concept", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.pages.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "concept_id": { "type": "string", "description": "Unique identifier" }, "page_order": { "type": "string" } } } } } } } }, "/api/v1/canvas/relations": { "get": { "operationId": "getCanvasRelations", "tags": ["Canvas: Concepts"], "summary": "List relations", "security": [ { "bearerAuth": ["canvas.read"] } ], "responses": { "200": { "description": "List relations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse" }, "example": { "data": [ { "id": "rel_xyz", "source_id": "con_abc123", "target_id": "con_def456", "relation": "influences", "label": "Raft builds on Paxos", "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } ], "next_cursor": null } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all relations between concepts with cursor-based pagination. Each relation includes source/target concept IDs, relation type, optional label, and timestamps. Default page size is 1000 for bulk graph loading.", "x-scopes": ["canvas.read"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.relations.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] }, "post": { "operationId": "postCanvasRelations", "tags": ["Canvas: Concepts"], "summary": "Create relation", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "201": { "description": "Relation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique relation identifier" }, "source_id": { "type": "string", "description": "Source concept ID" }, "target_id": { "type": "string", "description": "Target concept ID" }, "relation": { "type": "string", "description": "Relation type slug (e.g. supports, contradicts, related)" }, "label": { "type": "string", "description": "Optional human-readable label" }, "is_deleted": { "type": "boolean", "description": "Whether the relation is soft-deleted" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the relation creator" } }, "required": [ "id", "source_id", "target_id", "relation", "label", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "rel_xyz", "source_id": "con_abc123", "target_id": "con_def456", "relation": "influences", "label": "Raft builds on Paxos", "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a typed, directional relation between two concepts. Built-in relation types include \"related\" (default), \"influences\", and \"contradicts\"; custom types are also accepted (lowercase slug, e.g. \"extends\", \"prerequisite\"). Both concepts must exist and source/target must be different. Duplicate relations (same source, target, and type) return 409 Conflict.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.relations.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relation": { "type": "string", "description": "Relation type: \"related\", \"influences\", \"contradicts\", or custom", "example": "influences" }, "label": { "type": "string", "description": "Human-readable description of the connection", "example": "Raft builds on Paxos" }, "color": { "type": "string", "nullable": true, "description": "Display color (hex)" } } }, "example": { "source_id": "cpt_8f3a2b1c", "target_id": "cpt_4d6e8f0a", "relation": "influences", "label": "Raft builds on Paxos" } } } } } }, "/api/v1/canvas/relations/{relation_id}": { "parameters": [ { "name": "relation_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Relation identifier" } ], "patch": { "operationId": "patchCanvasRelationsByRelationId", "tags": ["Canvas: Concepts"], "summary": "Update relation", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique relation identifier" }, "source_id": { "type": "string", "description": "Source concept ID" }, "target_id": { "type": "string", "description": "Target concept ID" }, "relation": { "type": "string", "description": "Relation type slug (e.g. supports, contradicts, related)" }, "label": { "type": "string", "description": "Optional human-readable label" }, "is_deleted": { "type": "boolean", "description": "Whether the relation is soft-deleted" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the relation creator" } }, "required": [ "id", "source_id", "target_id", "relation", "label", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "rel_xyz", "source_id": "con_abc123", "target_id": "con_def456", "relation": "contradicts", "label": "challenges the assumption of", "is_deleted": false, "created_at": "2026-03-15T10:00:00.000Z", "updated_at": "2026-03-20T14:30:00.000Z", "created_by": "usr_owner1" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates a relation's type, label, or display color. At least one field must be provided. Changing the relation type re-classifies the edge on the Canvas (e.g., from \"related\" to \"contradicts\").", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.relations.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "relation": { "type": "string", "description": "Updated relation type (related, influences, contradicts, or custom)", "example": "contradicts" }, "label": { "type": "string", "description": "Updated human-readable label or null to clear" } } }, "example": { "relation": "contradicts", "label": "challenges the assumption of" } } } } }, "delete": { "operationId": "deleteCanvasRelationsByRelationId", "tags": ["Canvas: Concepts"], "summary": "Delete relation", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently deletes a relation between two concepts. Idempotent -- returns 204 No Content even if the relation was already deleted or does not exist.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.relations.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/synthesize": { "post": { "operationId": "postCanvasSynthesize", "tags": ["Canvas: AI"], "summary": "Synthesize concepts", "security": [ { "bearerAuth": ["canvas.read", "ai.use"] } ], "responses": { "200": { "description": "Synthesize concepts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "ai_unavailable": { "type": "boolean" } } } }, "required": ["data"] }, "example": { "data": { "synthesis": { "pattern": "Both concepts explore mechanisms for achieving agreement in complex systems — one in distributed computing, the other in organizational design.", "tensions": [ { "between": ["Distributed Consensus Algorithms", "Organizational Decision Making"], "description": "Technical consensus prioritizes correctness over speed; organizational consensus often trades correctness for buy-in." } ], "questions": [ "How might organizational decision-making benefit from formal consensus protocols?" ], "gaps": [ "Neither concept addresses consensus in adversarial environments (Byzantine fault tolerance in organizations)." ] } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Select 2-50 concepts to discover emergent patterns, tensions between ideas, open questions, and knowledge gaps that span across them. The AI analyzes each concept, its content, and inter-concept relations to surface insights you might have missed. Consumes AI credits.", "x-scopes": ["canvas.read", "ai.use"], "x-entitlements": ["canvas", "canvas.synthesis"], "x-rate-limit": "canvas.get", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "concept_ids": ["cpt_8f3a2b1c", "cpt_4d6e8f0a"] } } } } } }, "/api/v1/canvas/trash": { "delete": { "operationId": "deleteCanvasTrash", "tags": ["Canvas: Concepts"], "summary": "Empty trash", "security": [ { "bearerAuth": ["canvas.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Permanently and irreversibly deletes ALL trashed concepts for the authenticated user. Also cleans up associated timeline entries, relations, Circle edges, and calendar events. Returns the count of deleted concepts.", "x-scopes": ["canvas.write"], "x-entitlements": ["canvas"], "x-rate-limit": "canvas.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/canvas/weekly-report": { "get": { "operationId": "getCanvasWeeklyReport", "tags": ["Canvas: AI"], "summary": "Get weekly report", "security": [ { "bearerAuth": ["canvas.read", "ai.use"] } ], "responses": { "200": { "description": "Weekly report", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique report identifier" }, "week_start": { "type": "string", "description": "Report period start date (YYYY-MM-DD)" }, "week_end": { "type": "string", "description": "Report period end date (YYYY-MM-DD)" }, "concepts_created": { "type": "integer", "description": "Number of concepts created during the week" }, "concepts_updated": { "type": "integer", "description": "Number of concepts updated during the week" }, "relations_created": { "type": "integer", "description": "Number of relations created during the week" }, "questions_asked": { "type": "integer", "description": "Number of Ask Madless questions during the week" }, "narrative": { "type": "string", "description": "AI-generated narrative summary of the week" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Array of notable events and achievements" }, "momentum": { "type": "string", "description": "Growth momentum assessment: growing, steady, or declining" }, "suggested_next_steps": { "type": "array", "items": { "type": "string" }, "description": "Prioritized action suggestions for the next week" }, "created_at": { "type": "string", "description": "Report generation timestamp (ISO 8601)" } }, "required": [ "id", "week_start", "week_end", "concepts_created", "concepts_updated", "relations_created", "questions_asked", "narrative", "highlights", "momentum", "suggested_next_steps", "created_at" ] } }, "required": ["data"] }, "example": { "data": { "id": "dgst_w1x2y3", "week_start": "2026-02-17", "week_end": "2026-02-21", "concepts_created": 5, "concepts_updated": 3, "relations_created": 8, "questions_asked": 2, "narrative": "This week you deepened your understanding of distributed systems, adding 5 new concepts and forming 8 connections...", "highlights": [ "Connected Raft to Paxos via \"extends\" relation", "Explored Byzantine fault tolerance for the first time" ], "momentum": "growing", "suggested_next_steps": [ "Review the orphan concept \"Lamport Clocks\"", "Explore links between consensus and game theory" ], "created_at": "2026-02-21T08:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the latest combined weekly report (health metrics + narrative digest) for the current user. Includes growth stats, highlights, momentum assessment, and suggested next steps. Returns `{ data: null }` if no report has been generated yet.", "x-scopes": ["canvas.read", "ai.use"], "x-entitlements": ["canvas", "canvas.report"], "x-rate-limit": "canvas.get" }, "post": { "operationId": "postCanvasWeeklyReport", "tags": ["Canvas: AI"], "summary": "Generate weekly report", "security": [ { "bearerAuth": ["canvas.read", "ai.use"] } ], "responses": { "200": { "description": "The generated or existing weekly report (201 Created)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique report identifier" }, "week_start": { "type": "string", "description": "Report period start date (YYYY-MM-DD)" }, "week_end": { "type": "string", "description": "Report period end date (YYYY-MM-DD)" }, "concepts_created": { "type": "integer", "description": "Number of concepts created during the week" }, "concepts_updated": { "type": "integer", "description": "Number of concepts updated during the week" }, "relations_created": { "type": "integer", "description": "Number of relations created during the week" }, "questions_asked": { "type": "integer", "description": "Number of Ask Madless questions during the week" }, "narrative": { "type": "string", "description": "AI-generated narrative summary of the week" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Array of notable events and achievements" }, "momentum": { "type": "string", "description": "Growth momentum assessment: growing, steady, or declining" }, "suggested_next_steps": { "type": "array", "items": { "type": "string" }, "description": "Prioritized action suggestions for the next week" }, "created_at": { "type": "string", "description": "Report generation timestamp (ISO 8601)" } }, "required": [ "id", "week_start", "week_end", "concepts_created", "concepts_updated", "relations_created", "questions_asked", "narrative", "highlights", "momentum", "suggested_next_steps", "created_at" ] } }, "required": ["data"] }, "example": { "data": { "id": "dgst_w1x2y3", "week_start": "2026-02-17", "week_end": "2026-02-21", "concepts_created": 5, "concepts_updated": 3, "relations_created": 8, "questions_asked": 2, "narrative": "This week you deepened your understanding of distributed systems...", "highlights": ["Connected Raft to Paxos via \"extends\" relation"], "momentum": "growing", "suggested_next_steps": ["Review the orphan concept \"Lamport Clocks\""], "created_at": "2026-02-21T08:00:00Z" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Generates a combined weekly report (health metrics + narrative digest) for the current user. Gathers concepts, relations, graph analysis, pages, timeline entries, and ask history for the week, then produces a narrative summary with highlights and recommendations. Returns the existing report if one was already generated this week (idempotent within the same week). Consumes AI credits on first generation only.", "x-scopes": ["canvas.read", "ai.use"], "x-entitlements": ["canvas", "canvas.report"], "x-rate-limit": "canvas.get", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/circle": { "get": { "operationId": "getCircle", "tags": ["Circle: Concepts"], "summary": "Browse released concepts", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "string" }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "color", "absorb_count", "last_interacted_at", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } } }, "required": ["data"] }, "example": { "data": [ { "id": "cpt_pub_abc", "title": "Design Systems", "visibility": "released", "label_ids": ["lbl_design"], "links": [], "color": "#4F46E5", "absorb_count": 3, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1709000000000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-02-20T10:00:00.000Z", "created_by": "usr_abc" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns concepts that Circle members have released for shared visibility. Results are ordered by recency or popularity and support tag-based filtering and free-text search. Cursor-based pagination and ETag conditional requests are supported.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "Field to sort by" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query string" } ] } }, "/api/v1/circle/{concept_id}": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "get": { "operationId": "getCircleByConceptId", "tags": ["Circle: Concepts"], "summary": "Get a released concept", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "Released concept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique concept identifier" }, "title": { "type": "string", "description": "Concept title" }, "visibility": { "type": "string", "description": "Access level: private (default) or released (shared to Circle)" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of label IDs assigned to this concept" }, "links": { "type": "array", "items": { "type": "string" }, "description": "External URLs attached to this concept" }, "color": { "type": "string", "description": "User-assigned display color (hex) or null" }, "absorb_count": { "type": "integer", "description": "Number of times this concept has been absorbed from the Circle" }, "calendar_event_id": { "type": "string", "nullable": true, "description": "Linked calendar event ID or null" }, "revisit_by": { "type": "string", "nullable": true, "description": "Spaced repetition target date (epoch ms) or null" }, "last_interacted_at": { "type": "integer", "description": "Last interaction timestamp (epoch ms) or null" }, "attached_file_ids": { "type": "array", "items": { "type": "string" }, "description": "Drive file IDs attached to this concept" }, "is_deleted": { "type": "boolean", "description": "Whether the concept is in the trash" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID of the concept creator" } }, "required": [ "id", "title", "visibility", "label_ids", "links", "color", "absorb_count", "last_interacted_at", "attached_file_ids", "is_deleted", "created_at", "updated_at", "created_by" ] } }, "required": ["data"] }, "example": { "data": { "id": "cpt_pub_abc", "title": "Design Systems", "visibility": "released", "label_ids": ["lbl_design"], "links": [], "color": "#4F46E5", "absorb_count": 3, "calendar_event_id": null, "revisit_by": null, "last_interacted_at": 1709000000000, "attached_file_ids": [], "is_deleted": false, "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-02-20T10:00:00.000Z", "created_by": "usr_abc" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a single released concept from the Circle by its ID. The concept must have visibility \"released\" and not be deleted. Returns 404 if the concept does not exist, is private, or has been soft-deleted.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.list" } }, "/api/v1/circle/{concept_id}/absorb": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "post": { "operationId": "postCircleByConceptIdAbsorb", "tags": ["Circle: Concepts"], "summary": "Absorb a concept", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "200": { "description": "Absorb a concept", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Absorption record identifier" }, "circle_concept_id": { "type": "string", "description": "ID of the absorbed Circle concept" }, "user_id": { "type": "string", "description": "User ID who absorbed the concept" }, "absorbed_at": { "type": "integer", "description": "Absorption timestamp (epoch ms)" }, "snapshot": { "type": "object", "properties": { "title": { "type": "string" }, "color": { "type": "string" }, "updated_at": { "type": "integer" } }, "required": ["title", "color", "updated_at"], "description": "Frozen snapshot of the concept at absorption time" } }, "required": ["id", "circle_concept_id", "user_id", "absorbed_at", "snapshot"] } }, "required": ["data"] }, "example": { "data": { "id": "cpt_pub_abc_usr_current", "circle_concept_id": "cpt_pub_abc", "user_id": "usr_current", "absorbed_at": 1709000000000, "snapshot": { "title": "Design Systems", "color": "#4F46E5", "updated_at": 1709000000000 } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Absorbing a concept creates a lightweight reference and a frozen snapshot in your account. The original Circle concept is unchanged. You can later re-absorb to refresh the snapshot if the source is updated. Returns 409 Conflict if the concept has already been absorbed.", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.absorb", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/circle/{concept_id}/discussions": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "get": { "operationId": "getCircleByConceptIdDiscussions", "tags": ["Circle: Discussions"], "summary": "List discussion messages", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "List discussion messages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier" }, "concept_id": { "type": "string", "description": "Parent concept ID" }, "text": { "type": "string", "description": "Message text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the message" }, "reply_to": { "type": "string", "nullable": true, "description": "Quoted reply context or null" }, "reactions": { "type": "array", "items": { "type": "string" }, "description": "Emoji reactions map" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "File attachments array" }, "is_deleted": { "type": "boolean", "description": "Whether the message is soft-deleted" } }, "required": [ "id", "concept_id", "text", "created_at", "updated_at", "created_by", "reactions", "attachments", "is_deleted" ] } } }, "required": ["data"] }, "example": { "data": [ { "id": "msg_disc_001", "concept_id": "cpt_pub_abc", "text": "Great insight — this connects nicely to atomic design principles.", "created_at": "2026-02-20T14:30:00.000Z", "updated_at": "2026-02-20T14:30:00.000Z", "created_by": "usr_abc", "reply_to": null, "reactions": [], "attachments": [], "is_deleted": false } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns discussion messages for a released Circle concept, ordered chronologically (oldest first). Supports cursor-based pagination with the `after` parameter to fetch messages after a given message ID. The concept must exist and have visibility \"released\". Maximum 100 messages per page.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.list" }, "post": { "operationId": "postCircleByConceptIdDiscussions", "tags": ["Circle: Discussions"], "summary": "Post a discussion message", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier" }, "concept_id": { "type": "string", "description": "Parent concept ID" }, "text": { "type": "string", "description": "Message text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the message" }, "reply_to": { "type": "string", "nullable": true, "description": "Quoted reply context or null" }, "reactions": { "type": "array", "items": { "type": "string" }, "description": "Emoji reactions map" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "File attachments array" }, "is_deleted": { "type": "boolean", "description": "Whether the message is soft-deleted" } }, "required": [ "id", "concept_id", "text", "created_at", "updated_at", "created_by", "reactions", "attachments", "is_deleted" ] } }, "required": ["data"] }, "example": { "data": { "id": "msg_disc_001", "concept_id": "cpt_pub_abc", "text": "Great insight — this connects nicely to atomic design principles.", "created_at": "2026-02-20T14:30:00.000Z", "updated_at": "2026-02-20T14:30:00.000Z", "created_by": "usr_abc", "reply_to": null, "reactions": [], "attachments": [], "is_deleted": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Creates a new discussion message on a released Circle concept. Optionally attach files (up to 10) and reply to an existing message. The concept author is automatically notified when someone else posts. The concept must exist and have visibility \"released\".", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Message body. Must be 1-2000 characters after trimming.", "example": "Great insight — this connects nicely to atomic design principles." } } }, "example": { "text": "Great insight — this connects nicely to atomic design principles.", "reply_to": { "message_id": "msg_disc_parent", "author_id": "usr_def", "author_name": "Bob", "text": "The original point about design tokens..." }, "file_ids": ["file_abc"] } } } } } }, "/api/v1/circle/{concept_id}/discussions/{message_id}": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discussion message identifier" } ], "get": { "operationId": "getCircleByConceptIdDiscussionsByMessageId", "tags": ["Circle: Discussions"], "summary": "Get a discussion message", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "Discussion message", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier" }, "concept_id": { "type": "string", "description": "Parent concept ID" }, "text": { "type": "string", "description": "Message text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the message" }, "reply_to": { "type": "string", "nullable": true, "description": "Quoted reply context or null" }, "reactions": { "type": "array", "items": { "type": "string" }, "description": "Emoji reactions map" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "File attachments array" }, "is_deleted": { "type": "boolean", "description": "Whether the message is soft-deleted" } }, "required": [ "id", "concept_id", "text", "created_at", "updated_at", "created_by", "reactions", "attachments", "is_deleted" ] } }, "required": ["data"] }, "example": { "data": { "id": "msg_disc_001", "concept_id": "cpt_pub_abc", "text": "Great insight — this connects nicely to atomic design principles.", "created_at": "2026-02-20T14:30:00.000Z", "updated_at": "2026-02-20T14:30:00.000Z", "created_by": "usr_abc", "reply_to": null, "reactions": [], "attachments": [], "is_deleted": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a single discussion message by its ID within a Circle concept discussion thread. Includes reply context, reactions, and file attachments if present. Returns 404 if the message does not exist or has been soft-deleted.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.list" }, "patch": { "operationId": "patchCircleByConceptIdDiscussionsByMessageId", "tags": ["Circle: Discussions"], "summary": "Edit a discussion message", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier" }, "concept_id": { "type": "string", "description": "Parent concept ID" }, "text": { "type": "string", "description": "Message text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the message" }, "reply_to": { "type": "string", "nullable": true, "description": "Quoted reply context or null" }, "reactions": { "type": "array", "items": { "type": "string" }, "description": "Emoji reactions map" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "File attachments array" }, "is_deleted": { "type": "boolean", "description": "Whether the message is soft-deleted" } }, "required": [ "id", "concept_id", "text", "created_at", "updated_at", "created_by", "reactions", "attachments", "is_deleted" ] } }, "required": ["data"] }, "example": { "data": { "id": "msg_disc_001", "concept_id": "cpt_pub_abc", "text": "Updated insight — this connects to atomic design and component-driven development.", "created_at": "2026-02-20T14:30:00.000Z", "updated_at": "2026-02-20T15:00:00.000Z", "created_by": "usr_abc", "reply_to": null, "reactions": [], "attachments": [], "is_deleted": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates the text of an existing discussion message. Only the original author may edit their own message. The message receives an `edited_at` timestamp. Returns 403 if the caller is not the author.", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Updated message body. Must be 1-2000 characters after trimming.", "example": "Updated insight — this connects to atomic design and component-driven development." } } }, "example": { "text": "Updated insight — this connects to atomic design and component-driven development." } } } } }, "delete": { "operationId": "deleteCircleByConceptIdDiscussionsByMessageId", "tags": ["Circle: Discussions"], "summary": "Delete a discussion message", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Soft-deletes a discussion message and decrements the thread message count. Only the original author may delete their own message. Returns 204 No Content on success, 403 if the caller is not the author.", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/circle/{concept_id}/discussions/{message_id}/reactions": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discussion message identifier" } ], "post": { "operationId": "postCircleByConceptIdDiscussionsByMessageIdReactions", "tags": ["Circle: Discussions"], "summary": "Toggle a reaction", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "200": { "description": "Toggle a reaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique message identifier" }, "concept_id": { "type": "string", "description": "Parent concept ID" }, "text": { "type": "string", "description": "Message text content" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the message" }, "reply_to": { "type": "string", "nullable": true, "description": "Quoted reply context or null" }, "reactions": { "type": "array", "items": { "type": "object", "properties": { "emoji": { "type": "string" }, "user_ids": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" } }, "required": ["emoji", "user_ids", "count"] }, "description": "Emoji reactions map" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "File attachments array" }, "is_deleted": { "type": "boolean", "description": "Whether the message is soft-deleted" } }, "required": [ "id", "concept_id", "text", "created_at", "updated_at", "created_by", "reactions", "attachments", "is_deleted" ] } }, "required": ["data"] }, "example": { "data": { "id": "msg_disc_001", "concept_id": "cpt_pub_abc", "text": "Great insight — this connects nicely to atomic design principles.", "created_at": "2026-02-20T14:30:00.000Z", "updated_at": "2026-02-20T14:30:00.000Z", "created_by": "usr_abc", "reply_to": null, "reactions": [ { "emoji": "👍", "user_ids": ["usr_abc"], "count": 1 } ], "attachments": [], "is_deleted": false } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Toggles an emoji reaction on a discussion message. If the authenticated user has not reacted with this emoji, it is added; if already present, it is removed. The emoji string supports standard Unicode emoji (max 32 characters). The message must exist and not be deleted.", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.discussion.post", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emoji": { "type": "string", "description": "Unicode emoji string to toggle. Maximum 32 characters.", "example": "👍" } } }, "example": { "emoji": "👍" } } } } } }, "/api/v1/circle/{concept_id}/reabsorb": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "post": { "operationId": "postCircleByConceptIdReabsorb", "tags": ["Circle: Concepts"], "summary": "Refresh absorption snapshot", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "200": { "description": "Refresh absorption snapshot", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Absorption record identifier" }, "circle_concept_id": { "type": "string", "description": "ID of the absorbed Circle concept" }, "user_id": { "type": "string", "description": "User ID who absorbed the concept" }, "absorbed_at": { "type": "integer", "description": "Absorption timestamp (epoch ms)" }, "snapshot": { "type": "object", "properties": { "title": { "type": "string" }, "color": { "type": "string" }, "updated_at": { "type": "integer" } }, "required": ["title", "color", "updated_at"], "description": "Updated frozen snapshot of the concept" } }, "required": ["id", "circle_concept_id", "user_id", "absorbed_at", "snapshot"] } }, "required": ["data"] }, "example": { "data": { "id": "cpt_pub_abc_usr_current", "circle_concept_id": "cpt_pub_abc", "user_id": "usr_current", "absorbed_at": 1709000000000, "snapshot": { "title": "Design Systems (Updated)", "color": "#4F46E5", "updated_at": 1710000000000 } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Re-syncs your absorption snapshot to the current state of the source Circle concept. If you have a Canvas copy of this concept, it is also updated. Useful when the source has been edited since you originally absorbed it. Returns 404 if not previously absorbed, 403 if the concept is no longer released.", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.absorb", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/circle/{concept_id}/unabsorb": { "parameters": [ { "name": "concept_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique concept identifier" } ], "delete": { "operationId": "deleteCircleByConceptIdUnabsorb", "tags": ["Circle: Concepts"], "summary": "Delete circle unabsorb", "security": [ { "bearerAuth": ["circle.write"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Un-absorb a concept — removes the absorption record and decrements absorbCount", "x-scopes": ["circle.write"], "x-entitlements": ["circle"], "x-rate-limit": "circle.absorb", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/circle/canvas": { "get": { "operationId": "getCircleCanvas", "tags": ["Circle: Graph"], "summary": "Get Circle canvas positions", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "Circle canvas positions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "cpt_pub_abc": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] }, "cpt_pub_def": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": ["x", "y"] } }, "required": ["cpt_pub_abc", "cpt_pub_def"] } }, "required": ["data"] }, "example": { "data": { "cpt_pub_abc": { "x": 120, "y": 340 }, "cpt_pub_def": { "x": 450, "y": 200 } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the authenticated user's saved pill positions on the Circle canvas. Each key is a concept ID mapped to its x/y coordinates. Returns an empty object if no positions have been saved yet.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.canvas" } }, "/api/v1/circle/discussions/active": { "get": { "operationId": "getCircleDiscussionsActive", "tags": ["Circle: Discussions"], "summary": "List active discussions", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "List active discussions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "concept_id": { "type": "string", "description": "ID of the discussed concept" }, "concept_title": { "type": "string", "description": "Title of the discussed concept" }, "last_message_at": { "type": "string", "description": "Timestamp of the most recent message (ISO 8601)" }, "message_count": { "type": "integer", "description": "Total number of messages in the thread" }, "last_author_id": { "type": "string", "description": "User ID of the most recent message author" } }, "required": [ "concept_id", "concept_title", "last_message_at", "message_count", "last_author_id" ] } } }, "required": ["data"] }, "example": { "data": [ { "concept_id": "cpt_pub_abc", "concept_title": "Design Systems", "last_message_at": "2026-02-20T14:30:00Z", "message_count": 5, "last_author_id": "usr_abc" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns concepts that have recent discussion activity, ordered by the time of the last message (most recent first). Each entry includes the concept title, message count, and a preview. Maximum 50 threads per page, defaults to 20.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.threads.active" } }, "/api/v1/circle/edges": { "get": { "operationId": "getCircleEdges", "tags": ["Circle: Graph"], "summary": "List emergent edges", "security": [ { "bearerAuth": ["circle.read"] } ], "responses": { "200": { "description": "List emergent edges", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique edge identifier" }, "concept_a": { "type": "string", "description": "First concept ID in the edge" }, "concept_b": { "type": "string", "description": "Second concept ID in the edge" }, "member_count": { "type": "integer", "description": "Number of members who independently created this relation" }, "relations": { "type": "object", "properties": { "related": { "type": "integer" }, "influences": { "type": "integer" } }, "required": ["related", "influences"], "description": "Breakdown of relation types and their counts" }, "dominant_relation": { "type": "string", "description": "Most common relation type for this edge" }, "created_at": { "type": "string", "description": "First detection timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last update timestamp (ISO 8601)" } }, "required": [ "id", "concept_a", "concept_b", "member_count", "relations", "dominant_relation", "created_at", "updated_at" ] } } }, "required": ["data"] }, "example": { "data": [ { "id": "edge_abc_def", "concept_a": "cpt_pub_abc", "concept_b": "cpt_pub_def", "member_count": 3, "relations": { "related": 2, "influences": 1 }, "dominant_relation": "related", "created_at": "2026-02-01T00:00:00Z", "updated_at": "2026-02-20T10:00:00Z" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns emergent Circle edges -- relations that two or more members independently created between the same pair of concepts. Edge thickness scales with the number of confirming members. Each edge includes a breakdown of relation types and the dominant (most common) type.", "x-scopes": ["circle.read"], "x-entitlements": ["circle"], "x-rate-limit": "circle.edges" } }, "/api/v1/drive/download": { "get": { "operationId": "getDriveDownload", "tags": ["Drive: Media"], "summary": "Get file download URL", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "File download URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "nullable": true }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer", "description": "File size in bytes" } } } }, "required": ["data"] }, "example": { "data": { "download_url": "https://storage.googleapis.com/...", "file_name": "report.pdf", "content_type": "application/pdf", "size": 1048576 } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a temporary signed download URL for a file. If the request Accept header prefers a redirect, the response is a 302 redirect to the signed URL instead. URLs expire after a short TTL.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.download", "parameters": [ { "name": "file_id", "in": "query", "schema": { "type": "string" }, "description": "File identifier", "required": true }, { "name": "inline", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Return file inline instead of as attachment" } ] } }, "/api/v1/drive/drives": { "get": { "operationId": "getDriveDrives", "tags": ["Drive: Drives"], "summary": "List all drives", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "List all drives", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Drive" } } } } ] }, "example": { "data": [ { "id": "drv_personal", "name": "My Drive", "type": "personal", "slug": "my-drive", "description": "", "visibility": "listed", "owner_id": "usr_abc", "created_at": "2026-01-15T09:00:00Z", "updated_at": "2026-02-20T10:00:00Z", "stats": { "file_count": 14, "total_size": 52428800 } } ], "next_cursor": "drv_personal" } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a paginated list of drives the caller has access to, including personal, shared, and module drives. Supports ETag-based conditional requests for cache efficiency and optional filtering by drive type.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.drives", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Resource type filter" }, { "name": "include_all", "in": "query", "schema": { "type": "string", "enum": ["true", "false"] }, "description": "Include all drives (personal + shared)" } ] } }, "/api/v1/drive/drives/{drive_id}": { "parameters": [ { "name": "drive_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Drive identifier" } ], "get": { "operationId": "getDriveDrivesByDriveId", "tags": ["Drive: Drives"], "summary": "Get a drive", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "Drive", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Drive" } }, "required": ["data"] }, "example": { "data": { "id": "drv_personal", "name": "My Drive", "type": "personal", "slug": "my-drive", "description": "", "visibility": "listed", "owner_id": "usr_abc", "created_at": "2026-01-15T09:00:00Z", "updated_at": "2026-02-20T10:00:00Z", "stats": { "file_count": 14, "total_size": 52428800 } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.drives", "description": "Retrieves a single drive by its ID, including metadata such as name, type, visibility, owner, and aggregate file statistics (count and total size)." } }, "/api/v1/drive/preview": { "get": { "operationId": "getDrivePreview", "tags": ["Drive: Media"], "summary": "Get file preview URL", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "File preview URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "content_type": { "type": "string" }, "name": { "type": "string" }, "ext": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" } } } }, "required": ["data"] }, "example": { "data": { "preview_url": "https://storage.googleapis.com/...", "content_type": "image/png" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns a URL to a rendered preview of the file, such as a thumbnail for images or a rendered page for PDFs. Returns 404 if no preview has been generated yet.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.files", "parameters": [ { "name": "file_id", "in": "query", "schema": { "type": "string" }, "description": "File identifier" } ] } }, "/api/v1/drive/thumbnail": { "get": { "operationId": "getDriveThumbnail", "tags": ["Drive: Media"], "summary": "Get file thumbnail", "security": [ { "bearerAuth": ["drive.read"] } ], "responses": { "200": { "description": "File thumbnail", "content": { "application/json": { "schema": { "type": "object", "description": "Response for GET /api/v1/drive/thumbnail", "x-needs-schema": true, "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns an on-demand generated WebP thumbnail for an image file. Supports widths of 400px (card view) and 1600px (preview). Streams image bytes with immutable cache headers for CDN efficiency. Non-image files redirect to their preview URL.", "x-scopes": ["drive.read"], "x-entitlements": ["drive"], "x-rate-limit": "drive.thumbnail" } }, "/api/v1/search": { "get": { "operationId": "getSearch", "tags": ["Search"], "summary": "Search across modules", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Search across modules", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "results": { "type": "object", "properties": { "drive": { "type": "object", "additionalProperties": true }, "calendar": { "type": "object", "additionalProperties": true } }, "description": "Search results grouped by module (drive, canvas, circle)" }, "total": { "type": "number", "description": "Total number of results across all modules" }, "query": { "type": "string", "description": "The original search query" } } } }, "required": ["data"] }, "example": { "data": { "results": { "drive": { "drives": [], "files": [ { "id": "file_xyz", "name": "report.pdf", "description": "PDF file • 1 MB", "drive_id": "drv_personal", "url": "/drive/drv_personal?file=file_xyz" } ] }, "canvas": { "concepts": [ { "id": "cpt_abc", "name": "Design Systems", "url": "/canvas/cpt_abc" } ] }, "circle": { "threads": [ { "id": "cpt_pub_abc", "name": "Design Tokens Discussion", "url": "/circle?selected=cpt_pub_abc" } ] } }, "total": 3, "query": "design systems" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Performs a cross-module search across Drive files, Canvas concepts, Circle threads, and Calendar events. Results are grouped by module and filtered by the user's scopes -- modules the user cannot access are automatically excluded. When `semantic=true` and the query is longer than 3 characters, an AI-powered semantic search supplements lexical matching for Canvas and Circle results. Default limit is 5 results per entity type, maximum 20.", "x-rate-limit": "search.query", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query string", "required": true }, { "name": "modules", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated list of modules to search (e.g. drive,canvas,calendar)" } ] } }, "/api/v1/signals/connections/enrich": { "post": { "operationId": "postSignalsConnectionsEnrich", "tags": ["Signals"], "summary": "Create connections enrich", "security": [ { "bearerAuth": ["signals.read"] } ], "responses": { "201": { "description": "Connections enrich created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "near_duplicates": { "type": "array", "items": { "type": "string" } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Given orphan / small-cluster concept IDs, finds the closest semantic\nmatch for each using stored embeddings. Returns human-readable\nstrength labels instead of raw numbers.\nWhen `allConceptIds` is provided, also computes pairwise cosine similarity\nacross all concepts and returns near-duplicate pairs (similarity >= 0.88)\nin the `near_duplicates` field. This is pure math — no AI cost.", "x-scopes": ["signals.read"], "x-entitlements": ["signals"], "x-rate-limit": "signals.connections", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "concept_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" } }, "exclude_ids = []": { "type": "string" }, "all_concept_ids": { "type": "array", "items": { "type": "string", "description": "Unique identifier" } } } } } } } } }, "/api/v1/signals/discoveries": { "get": { "operationId": "getSignalsDiscoveries", "tags": ["Signals"], "summary": "List signals discoveries", "security": [ { "bearerAuth": ["signals.read"] } ], "responses": { "200": { "description": "List signals discoveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "List discovery insights (gap analysis) for the current user.", "x-scopes": ["signals.read"], "x-entitlements": ["signals", "signals.discoveries"], "x-rate-limit": "signals.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Status filter" } ] }, "post": { "operationId": "postSignalsDiscoveries", "tags": ["Signals"], "summary": "Create signals discoveries", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "201": { "description": "Signals discoveries created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Run AI-powered gap analysis via durable workflow.", "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals", "signals.discoveries"], "x-rate-limit": "signals.discoveries", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clusters": { "type": "array", "items": { "type": "string" } }, "hubs": { "type": "array", "items": { "type": "string" } }, "orphans": { "type": "array", "items": { "type": "string" } }, "bridges": { "type": "array", "items": { "type": "string" } }, "total_concepts": { "type": "array", "items": { "type": "string" } }, "total_relations": { "type": "array", "items": { "type": "string" } }, "existing_edges": { "type": "array", "items": { "type": "string" } }, "relation_types": { "type": "array", "items": { "type": "string" } }, "concept_context": { "type": "string" }, "fingerprint": { "type": "string" } } } } } } } }, "/api/v1/signals/discoveries/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier" } ], "patch": { "operationId": "patchSignalsDiscoveriesById", "tags": ["Signals"], "summary": "Update signals discoveries", "security": [ { "bearerAuth": ["signals.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Update discovery status (dismiss/resolve/act) or mark as seen.", "x-scopes": ["signals.write"], "x-entitlements": ["signals"], "x-rate-limit": "signals.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "seen_at": { "type": "integer", "description": "Unix timestamp (ms)" } } } } } } } }, "/api/v1/signals/patterns": { "post": { "operationId": "postSignalsPatterns", "tags": ["Signals"], "summary": "Create signals patterns", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "201": { "description": "Signals patterns created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "patterns": { "type": "array", "items": { "type": "string" } }, "ai_unavailable": { "type": "boolean" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Durable workflow pipeline: clustering → AI analysis → post-processing.", "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals", "signals.patterns"], "x-rate-limit": "signals.patterns", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string" }, "concepts": { "type": "array", "items": { "type": "string" } } } } } } } }, "get": { "operationId": "getSignalsPatterns", "tags": ["Signals"], "summary": "List signals patterns", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "200": { "description": "List signals patterns", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "List stored patterns for the current user.", "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals", "signals.patterns"], "x-rate-limit": "signals.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Status filter" } ] } }, "/api/v1/signals/patterns/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier" } ], "patch": { "operationId": "patchSignalsPatternsById", "tags": ["Signals"], "summary": "Update signals patterns", "security": [ { "bearerAuth": ["signals.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Dismiss a pattern.", "x-scopes": ["signals.write"], "x-entitlements": ["signals"], "x-rate-limit": "signals.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } } } }, "/api/v1/signals/scan": { "post": { "operationId": "postSignalsScan", "tags": ["Signals"], "summary": "Create signals scan", "security": [ { "bearerAuth": ["signals.scan", "ai.use"] } ], "responses": { "201": { "description": "Signals scan created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["signals.scan", "ai.use"], "x-entitlements": ["signals"], "x-rate-limit": "signals.scan", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/v1/signals/scan/{run_id}": { "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "run identifier" } ], "get": { "operationId": "getSignalsScanByRunId", "tags": ["Signals"], "summary": "Get signals scan", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "200": { "description": "Signals scan", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "run_id": { "type": "string", "description": "Unique identifier" }, "status": { "type": "string" }, "result": { "type": "string" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals"], "x-rate-limit": "signals.list" } }, "/api/v1/signals/scan/meta": { "get": { "operationId": "getSignalsScanMeta", "tags": ["Signals"], "summary": "List scan meta", "security": [ { "bearerAuth": ["signals.read"] } ], "responses": { "200": { "description": "List scan meta", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "last_scan_at": { "type": "string", "nullable": true }, "tension_count": { "type": "number" }, "pattern_count": { "type": "number" }, "discovery_count": { "type": "number" }, "concept_count": { "type": "number" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["signals.read"], "x-entitlements": ["signals"], "x-rate-limit": "signals.list" } }, "/api/v1/signals/tensions": { "post": { "operationId": "postSignalsTensions", "tags": ["Signals"], "summary": "Create signals tensions", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "201": { "description": "Signals tensions created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "tensions": { "type": "array", "items": { "type": "string" } }, "ai_unavailable": { "type": "boolean" } } } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Durable workflow pipeline: candidate selection → AI analysis → post-processing.", "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals", "signals.tensions"], "x-rate-limit": "signals.tensions", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fingerprint": { "type": "string" }, "concepts": { "type": "array", "items": { "type": "string" } }, "relations": { "type": "array", "items": { "type": "string" } }, "clusters": { "type": "array", "items": { "type": "string" } } } } } } } }, "get": { "operationId": "getSignalsTensions", "tags": ["Signals"], "summary": "List signals tensions", "security": [ { "bearerAuth": ["signals.read", "ai.use"] } ], "responses": { "200": { "description": "List signals tensions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "List stored tensions for the current user.", "x-scopes": ["signals.read", "ai.use"], "x-entitlements": ["signals", "signals.tensions"], "x-rate-limit": "signals.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Status filter" } ] } }, "/api/v1/signals/tensions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Resource identifier" } ], "patch": { "operationId": "patchSignalsTensionsById", "tags": ["Signals"], "summary": "Update signals tensions", "security": [ { "bearerAuth": ["signals.write"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string" } }, "required": ["data"] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Dismiss or resolve a tension.", "x-scopes": ["signals.write"], "x-entitlements": ["signals"], "x-rate-limit": "signals.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "note": { "type": "string" }, "resolution_type": { "type": "string" } } } } } } } }, "/api/v1/users/me": { "get": { "operationId": "getUsersMe", "tags": ["Users"], "summary": "Get current user details", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current user details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" } }, "required": ["data"] }, "example": { "data": { "ok": true, "user": { "id": "usr_abc", "email": "alice@example.com", "name": "Alice Smith", "photo_url": null, "is_verified": true } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns extended profile information for the authenticated user, including account settings and space membership. This is a more detailed variant of the `/me` endpoint.", "x-rate-limit": "users.me.read" } }, "/api/v1/users/me/blocked": { "get": { "operationId": "getUsersMeBlocked", "tags": ["Users"], "summary": "List blocked users", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List blocked users", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blocked": { "type": "array", "items": { "type": "string" } } } } }, "required": ["data"] }, "example": { "data": [ { "user_id": "usr_blocked_001", "blocked_at": "2026-02-18T12:00:00Z" } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all users blocked by the authenticated user, ordered by most recently blocked. When the `userId` query parameter is provided, returns a single `{blocked: true/false}` check instead of the full list. Maximum 500 blocked users returned.", "x-rate-limit": "users.me.blocked.list", "parameters": [ { "name": "user_id", "in": "query", "schema": { "type": "string" }, "description": "User identifier" } ] }, "post": { "operationId": "postUsersMeBlocked", "tags": ["Users"], "summary": "Block a user", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Block a user", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "blocked": { "type": "boolean", "description": "Whether the user is now blocked" } } } }, "required": ["data"] }, "example": { "data": { "blocked": true } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Adds a user to the authenticated user's block list. Blocked users are hidden from Circle discussions and other social surfaces. Returns 400 if attempting to block yourself.", "x-rate-limit": "users.me.block", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "user_id": "usr_target_001" } } } } }, "delete": { "operationId": "deleteUsersMeBlocked", "tags": ["Users"], "summary": "Unblock a user", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Removes a user from the authenticated user's block list. The target user ID is passed as a required `userId` query parameter. Returns 400 if `userId` is missing.", "x-rate-limit": "users.me.block", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "user_id", "in": "query", "schema": { "type": "string" }, "description": "User identifier" } ] } }, "/api/v1/users/me/profile": { "get": { "operationId": "getUsersMeProfile", "tags": ["Users"], "summary": "Get space profile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Space profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "currently_exploring": { "type": "string", "nullable": true } } } }, "required": ["data"] }, "example": { "data": { "currently_exploring": "Knowledge graph architectures" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the authenticated user's space-scoped profile fields. Currently exposes `currently_exploring` which is shown on the user's public profile and in Circle interactions.", "x-rate-limit": "users.profile.read" }, "patch": { "operationId": "patchUsersMeProfile", "tags": ["Users"], "summary": "Update user profile", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string", "description": "Updated display name" }, "handle": { "type": "string", "description": "Unique handle" }, "currently_exploring": { "type": "string", "description": "What the user is currently exploring" } }, "required": ["name", "handle", "currently_exploring"] } }, "required": ["data"] }, "example": { "data": { "name": "Alice Smith", "handle": "alice_s", "currently_exploring": "Knowledge graph architectures" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Updates the authenticated user's space-scoped profile. All fields are optional -- only provided fields are changed. Handle claims are globally unique and validated against `^[a-z0-9_]{3,20}$`. Returns 409 Conflict if the requested handle is already taken.", "x-rate-limit": "users.profile.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name. Maximum 100 characters.", "example": "Alice Smith" }, "location": { "type": "string", "description": "Location string. Maximum 200 characters. Send empty string to clear.", "example": "London, UK" }, "team": { "type": "string", "description": "Team or department name. Maximum 100 characters. Send empty string to clear.", "example": "Research" }, "handle": { "type": "string", "description": "Unique handle (lowercase alphanumeric and underscores). Must be 3-20 characters matching `^[a-z0-9_]+$`. Globally unique across all spaces.", "example": "alice_s" } } }, "example": { "name": "Alice Smith", "handle": "alice_s", "currently_exploring": "Knowledge graph architectures" } } } } } }, "/api/v1/users/me/storage-usage": { "get": { "operationId": "getUsersMeStorageUsage", "tags": ["Users"], "summary": "Get storage usage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Storage usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "storage": { "type": "string", "description": "User-level storage usage with breakdown by file type" }, "space": { "type": "string", "description": "Space-level storage usage and cap" } } } }, "required": ["data"] }, "example": { "data": { "ok": true, "storage": { "used": 52428800, "file_count": 14, "limit": 26843545600, "percentage": 0.19, "breakdown": { "images": 20971520, "pdf": 10485760, "video": 0, "documents": 15728640, "other": 5242880 } }, "space": { "used": 524288000, "cap": 26843545600, "file_count": 142, "percentage": 1.95 } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns the authenticated user's storage consumption broken down by file type (images, PDF, video, documents, other), along with the space-level storage cap and usage. Useful for displaying quota bars and enforcing upload limits.", "x-rate-limit": "users.me.storage_usage" } }, "/api/v1/webhooks/subscriptions": { "get": { "operationId": "getWebhooksSubscriptions", "tags": ["Webhooks"], "summary": "List webhook subscriptions", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "200": { "description": "List webhook subscriptions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } } ] }, "example": { "data": [ { "id": "wh_sub_001", "url": "https://example.com/webhook", "events": ["drive.file.uploaded", "canvas.concept.created"], "active": true, "description": "Production webhook", "created_at": 1708416000000, "updated_at": 1708416000000, "stats": { "delivery_count": 142, "failure_count": 3, "last_delivered_at": 1709000000000, "last_failed_at": null, "last_error": null } } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns all webhook subscriptions for the space, including their event types, target URLs, active status, and delivery statistics. Use this to audit configured integrations and monitor delivery health.", "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.subscriptions.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] }, "post": { "operationId": "postWebhooksSubscriptions", "tags": ["Webhooks"], "summary": "Create a webhook subscription", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "201": { "description": "Webhook subscription created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique subscription identifier" }, "url": { "type": "string", "description": "Webhook delivery URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of subscribed event types" }, "secret": { "type": "string", "description": "Signing secret (returned only on creation, store it securely)" } } } }, "required": ["data"] }, "example": { "data": { "id": "wh_sub_001", "url": "https://example.com/webhook", "events": ["drive.file.uploaded"], "secret": "whsec_a1b2c3d4e5f6g7h8" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Registers a new webhook subscription that receives POST requests when the specified events occur. The target URL must be HTTPS and publicly reachable (SSRF-validated). The signing secret is returned exactly once in the creation response and cannot be retrieved again -- store it securely.", "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.subscriptions.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS endpoint URL to receive webhook POST requests (required)", "example": "https://example.com/webhook" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of event type strings to subscribe to (required, 1-50 items)", "example": ["drive.file.uploaded", "canvas.concept.created"] }, "description": { "type": "string", "description": "Human-readable description of this subscription (optional, up to 500 chars)", "example": "Production webhook" } }, "required": ["url", "events", "description"] }, "example": { "url": "https://example.com/webhook", "events": ["drive.file.uploaded", "canvas.concept.created"], "description": "Production webhook" } } } } } }, "/api/v1/webhooks/subscriptions/{subscription_id}": { "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook subscription identifier" } ], "get": { "operationId": "getWebhooksSubscriptionsBySubscriptionId", "tags": ["Webhooks"], "summary": "Get a webhook subscription", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "200": { "description": "Webhook subscription", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } }, "required": ["data"] }, "example": { "data": { "id": "wh_sub_001", "url": "https://example.com/webhook", "events": ["drive.file.uploaded", "canvas.concept.created"], "active": true, "description": "Production webhook", "created_at": 1708416000000, "updated_at": 1708416000000, "stats": { "delivery_count": 142, "failure_count": 3, "last_delivered_at": 1709000000000, "last_failed_at": null, "last_error": null } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.subscriptions.get", "description": "Retrieves the full details of a specific webhook subscription including its target URL, event types, active status, and delivery statistics. The signing secret is never included in GET responses for security." }, "patch": { "operationId": "patchWebhooksSubscriptionsBySubscriptionId", "tags": ["Webhooks"], "summary": "Update a webhook subscription", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "200": { "description": "Updated resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } }, "required": ["data"] }, "example": { "data": { "id": "wh_sub_001", "url": "https://example.com/webhook", "events": ["drive.file.uploaded", "canvas.concept.created"], "active": true, "description": "Production webhook", "created_at": 1708416000000, "updated_at": 1708416000000, "stats": { "delivery_count": 142, "failure_count": 3, "last_delivered_at": 1709000000000, "last_failed_at": null, "last_error": null } } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.subscriptions.update", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Updated HTTPS endpoint URL (optional)", "example": "https://example.com/webhook/v2" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Updated event types array (optional, 1-50 items)", "example": ["drive.file.uploaded", "calendar.event.created"] }, "active": { "type": "boolean", "description": "Enable or disable the subscription (optional)", "example": true } } }, "example": { "url": "https://example.com/webhook/v2", "events": ["drive.file.uploaded", "canvas.concept.created", "calendar.event.created"], "active": true } } } }, "description": "Partially updates a webhook subscription's properties. All fields are optional -- only the provided fields are modified. Pass a new `secret` to rotate the signing key. Supports If-Match concurrency control via ETag." }, "delete": { "operationId": "deleteWebhooksSubscriptionsBySubscriptionId", "tags": ["Webhooks"], "summary": "Delete a webhook subscription", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "204": { "description": "No content" }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.subscriptions.delete", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "description": "Permanently removes a webhook subscription and cancels any pending deliveries. This action cannot be undone. Historical delivery logs are retained for audit purposes." } }, "/api/v1/webhooks/subscriptions/{subscription_id}/deliveries": { "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Webhook subscription identifier" } ], "get": { "operationId": "getWebhooksSubscriptionsBySubscriptionIdDeliveries", "tags": ["Webhooks"], "summary": "List webhook deliveries", "security": [ { "bearerAuth": ["webhooks.manage"] } ], "responses": { "200": { "description": "List webhook deliveries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] }, "example": { "data": [ { "id": "del_abc", "status": "delivered", "event_type": "drive.file.uploaded", "created_at": 1709000000000, "attempts": 1, "error": null, "delivered_at": 1709000001000, "last_attempt_at": 1709000001000 } ] } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "description": "Returns recent delivery attempts for a specific subscription, including HTTP response status codes, timestamps, attempt counts, and error details. Use this to debug integration issues and monitor delivery reliability.", "x-scopes": ["webhooks.manage"], "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.deliveries.list", "parameters": [ { "$ref": "#/components/parameters/PaginationLimit" }, { "$ref": "#/components/parameters/PaginationCursor" } ] } }, "/api/v1/webhooks/test": { "post": { "operationId": "postWebhooksTest", "tags": ["Webhooks"], "summary": "Send a test webhook", "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "description": "HTTP response status code from the target URL" }, "headers": { "type": "object", "additionalProperties": true, "description": "Response headers from the target URL" }, "body": { "type": "string", "description": "Response body from the target URL" }, "signature": { "type": "string", "description": "Computed HMAC-SHA256 signature sent with the request" }, "event_id": { "type": "string", "description": "Unique identifier" } } } }, "required": ["data"] }, "example": { "data": { "status": 200, "headers": { "content-type": "application/json" }, "body": "{\"ok\":true}", "signature": "sha256=abc123...", "event_id": "evt_test_001" } } } } }, "400": { "description": "Validation error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "401": { "description": "Authentication required", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "403": { "description": "Insufficient permissions", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Resource not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "headers": { "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Rate limit ceiling", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in window", "schema": { "type": "integer" } } } }, "500": { "description": "Internal server error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-entitlements": ["webhooks"], "x-rate-limit": "webhooks.test.send", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription_id": { "type": "string", "description": "ID of the subscription to test (required)", "example": "wh_sub_001" }, "event_type": { "type": "string", "description": "Event type to simulate (optional, defaults to \"test.ping\")", "example": "test.ping" } }, "required": ["subscription_id", "event_type"] }, "example": { "subscription_id": "wh_sub_001", "event_type": "test.ping" } } } }, "description": "Sends a test event to the specified subscription's target URL to verify connectivity and signature validation. Returns the full round-trip result including HTTP status, response headers, body, and the computed HMAC signature." } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as Bearer token: `Authorization: Bearer mad_sk_...`" } }, "schemas": { "ProblemDetails": { "type": "object", "description": "RFC 7807 Problem Details error response", "required": ["type", "title", "status", "detail"], "properties": { "type": { "type": "string", "format": "uri-reference", "description": "Error type URI", "example": "/docs/errors#not_found" }, "title": { "type": "string", "description": "Short human-readable summary", "example": "not found" }, "status": { "type": "integer", "description": "HTTP status code", "example": 404 }, "detail": { "type": "string", "description": "Human-readable explanation", "example": "File not found" }, "request_id": { "type": "string", "description": "Server-assigned request ID for debugging" }, "details": { "type": "object", "description": "Additional error details (e.g. field validation errors)", "additionalProperties": true } } }, "PaginatedResponse": { "type": "object", "description": "Cursor-based paginated response wrapper. All list endpoints return this shape. Pass `next_cursor` as the `cursor` query parameter to fetch the next page. When `next_cursor` is absent, there are no more results.", "required": ["data"], "properties": { "data": { "type": "array", "items": {}, "description": "Page of results" }, "next_cursor": { "type": "string", "description": "Cursor for the next page (absent if no more results)" } } }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/ProblemDetails" }, { "type": "object", "properties": { "details": { "type": "object", "description": "Field-level validation errors", "additionalProperties": { "type": "string" } } } } ] }, "DriveFile": { "type": "object", "description": "A file stored in a drive.", "required": ["id", "name", "mime", "drive_id", "created_at"], "properties": { "id": { "type": "string", "description": "Unique file identifier" }, "name": { "type": "string", "description": "File name" }, "ext": { "type": "string", "description": "File extension (e.g. pdf, png)" }, "mime": { "type": "string", "description": "MIME type" }, "size": { "type": "integer", "description": "File size in bytes" }, "drive_id": { "type": "string", "description": "Parent drive identifier" }, "status": { "type": "string", "enum": ["active", "deleted"], "description": "File lifecycle status" }, "is_starred": { "type": "boolean", "description": "Whether the current user has starred this file" }, "owner_name": { "type": "string", "nullable": true, "description": "Display name of file uploader" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the file" } } }, "Drive": { "type": "object", "description": "A drive container that holds files.", "required": ["id", "name", "type", "created_at"], "properties": { "id": { "type": "string", "description": "Unique drive identifier" }, "name": { "type": "string", "description": "Drive name" }, "type": { "type": "string", "enum": ["personal", "shared", "module"], "description": "Drive type" }, "owner_id": { "type": "string", "description": "Drive owner user ID" }, "slug": { "type": "string", "description": "URL-safe slug" }, "description": { "type": "string", "description": "Drive description" }, "visibility": { "type": "string", "enum": ["listed", "private", "shared"], "description": "Drive visibility" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "stats": { "type": "object", "properties": { "file_count": { "type": "integer" }, "total_size": { "type": "integer", "description": "Total size in bytes" } } } } }, "CalendarEvent": { "type": "object", "description": "A calendar event with start/end times.", "required": ["id", "calendar_id", "title", "created_at"], "properties": { "id": { "type": "string", "description": "Unique event identifier" }, "calendar_id": { "type": "string", "description": "Parent calendar identifier" }, "title": { "type": "string", "description": "Event title" }, "description": { "type": "string", "nullable": true, "description": "Event description" }, "start": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix timestamp (ms)" }, "tz": { "type": "string", "description": "IANA timezone (e.g. Europe/London)" } } }, "end": { "type": "object", "properties": { "ts": { "type": "integer", "description": "Unix timestamp (ms)" }, "tz": { "type": "string", "description": "IANA timezone (e.g. Europe/London)" } } }, "concept_id": { "type": "string", "nullable": true, "description": "Linked Canvas concept ID" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the event" } } }, "Calendar": { "type": "object", "description": "A calendar containing events.", "required": ["id", "name", "created_at"], "properties": { "id": { "type": "string", "description": "Unique calendar identifier" }, "name": { "type": "string", "description": "Calendar name" }, "color": { "type": "string", "nullable": true, "description": "Hex color code" }, "time_zone": { "type": "string", "description": "IANA timezone (e.g. Europe/London)" }, "visibility": { "type": "string", "enum": ["private", "shared"] }, "archived": { "type": "boolean", "description": "Whether the calendar is archived" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "description": "Last modification timestamp (ISO 8601)" }, "created_by": { "type": "string", "description": "User ID who created the calendar" } } }, "WebhookSubscription": { "type": "object", "description": "A webhook subscription that delivers event payloads to a URL.", "required": ["id", "url", "events", "active", "created_at"], "properties": { "id": { "type": "string", "description": "Unique subscription identifier" }, "url": { "type": "string", "format": "uri", "description": "Delivery URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "active": { "type": "boolean", "description": "Whether the subscription is active" }, "description": { "type": "string" }, "secret": { "type": "string", "description": "HMAC signing secret (only returned on creation)" }, "stats": { "type": "object", "properties": { "delivery_count": { "type": "integer" }, "failure_count": { "type": "integer" }, "last_delivered_at": { "type": "integer", "description": "Unix timestamp (ms)" }, "last_failed_at": { "type": "integer", "nullable": true }, "last_error": { "type": "string", "nullable": true } } }, "created_at": { "type": "integer", "description": "Creation timestamp (epoch ms)" }, "updated_at": { "type": "integer", "description": "Last modification timestamp (epoch ms)" } } }, "User": { "type": "object", "description": "A space user with profile, roles, and permission scopes.", "required": ["id"], "properties": { "id": { "type": "string", "description": "Unique user identifier" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "User email address" }, "name": { "type": "string", "nullable": true, "description": "User name" }, "photo_url": { "type": "string", "format": "uri", "nullable": true, "description": "Profile photo URL" }, "location": { "type": "string", "nullable": true, "description": "Location" }, "team": { "type": "string", "nullable": true, "description": "Team" }, "role": { "type": "string", "nullable": true, "description": "Role name" }, "active": { "type": "boolean", "description": "Whether the user is active" }, "created_at": { "type": "string", "nullable": true, "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": "string", "nullable": true, "description": "Last modification timestamp (ISO 8601)" } } }, "Notification": { "type": "object", "description": "A user notification triggered by platform events.", "required": ["id", "type", "created_at"], "properties": { "id": { "type": "string", "description": "Unique notification identifier" }, "type": { "type": "string", "enum": ["circleAbsorb", "circleEdgeStrengthened", "circleDiscussionReply", "circleConceptUpdated"], "description": "Notification type" }, "subject_id": { "type": "string", "description": "Subject entity identifier" }, "subject_name": { "type": "string", "nullable": true, "description": "Subject display name" }, "from_uid": { "type": "string", "nullable": true, "description": "Sender user ID" }, "link": { "type": "string", "nullable": true, "description": "Action link" }, "message": { "type": "string", "nullable": true, "description": "Notification message" }, "created_at": { "type": "string", "description": "Creation timestamp (ISO 8601)" }, "read": { "type": "boolean", "description": "Whether the notification has been read" }, "read_at": { "type": "string", "nullable": true, "description": "Read timestamp (ISO 8601)" } } }, "WebhookDelivery": { "type": "object", "description": "A single delivery attempt for a webhook subscription.", "required": ["id", "status", "event_type", "created_at"], "properties": { "id": { "type": "string", "description": "Unique delivery identifier" }, "status": { "type": "string", "enum": ["pending", "processing", "delivered", "failed"], "description": "Delivery status" }, "event_type": { "type": "string", "description": "Event type that triggered the delivery" }, "created_at": { "type": "integer", "description": "Creation timestamp (ms)" }, "attempts": { "type": "integer", "description": "Number of delivery attempts" }, "error": { "type": "string", "nullable": true, "description": "Error message if failed" }, "delivered_at": { "type": "integer", "nullable": true, "description": "Delivery timestamp (ms)" }, "last_attempt_at": { "type": "integer", "nullable": true, "description": "Last attempt timestamp (ms)" } } } }, "parameters": { "PaginationLimit": { "name": "limit", "in": "query", "description": "Maximum number of items to return (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "PaginationCursor": { "name": "cursor", "in": "query", "description": "Cursor from a previous page response", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Unique key for idempotent POST requests", "schema": { "type": "string", "format": "uuid" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "description": "ETag for conditional requests", "schema": { "type": "string" } } } }, "tags": [ { "name": "Agent" }, { "name": "Calendar: Calendars", "description": "Calendar management: creating, updating, and listing calendars." }, { "name": "Calendar: Events", "description": "Event management: scheduling, recurrence, and attendee operations." }, { "name": "Canvas: AI", "description": "AI-powered Canvas features: synthesis, discovery, similarity checks, and ask." }, { "name": "Canvas: Concepts", "description": "Core concept CRUD: creating, reading, updating, trashing, and restoring concepts." }, { "name": "Canvas: Labels", "description": "Concept labels: organizing concepts into logical groupings." }, { "name": "Canvas: Layout", "description": "Layout views: spatial layouts for visualizing concept relationships." }, { "name": "Canvas: Pages", "description": "Concept pages: rich-text documents attached to concepts." }, { "name": "Canvas: Timeline", "description": "Concept timeline: chronological entries and notes on a concept." }, { "name": "Circle: Concepts", "description": "Circle concepts: releasing, browsing, and managing shared concepts." }, { "name": "Circle: Discussions", "description": "Circle discussions: threaded conversations on shared concepts." }, { "name": "Circle: Graph", "description": "Circle graph: edges, canvas layout, and personal layer overlay." }, { "name": "Drive: Drives", "description": "Drive management: creating and configuring personal and shared drives." }, { "name": "Drive: Files", "description": "File management: uploading, listing, sharing, and managing files." }, { "name": "Drive: Media", "description": "Media access: downloading, previewing, and generating thumbnails." }, { "name": "Search", "description": "Cross-module full-text search across drive files and canvas concepts." }, { "name": "Signals", "description": "Structured knowledge base: labels, documents, templates, and search." }, { "name": "Users", "description": "User profiles, presence, and storage usage." }, { "name": "Webhooks", "description": "Outbound webhook subscriptions, delivery history, and testing." } ] }