{"specVersion":"2.0.0","generatedAt":"2026-08-27T06:45:47.364Z","product":"Aicoo","apiVersion":"v1","docsUrl":"https://www.aicoo.io/docs/api","baseUrl":"https://www.aicoo.io/api/v1","protocolTagline":"Message conveys intent and context, not authority.","statusLegend":{"ga":"Live in production.","preview":"Design partners only; contract may change.","planned":"Contract preview only, not yet callable."},"authentication":{"type":"bearer","header":"Authorization","format":"Bearer YOUR_API_KEY","apiKeySetupUrl":"https://www.aicoo.io/settings/api-keys","oauth":{"description":"All v1 routes also accept Login with Aicoo OAuth access tokens minted with resource=https://www.aicoo.io/api/v1.","docsUrl":"https://www.aicoo.io/docs/api/oauth"}},"tracks":[{"key":"aicoo","title":"Build on Aicoo","description":"Aicoo-based infrastructure: the data plane is the user's Aicoo workspace. Auth via Login with Aicoo OAuth or user API keys.","docsUrl":"https://www.aicoo.io/docs/api#aicoo","groups":[{"key":"getting-started","title":"Getting Started","description":"API keys, auth headers, and your first requests against your own workspace.","docsUrl":"https://www.aicoo.io/docs/api/getting-started","endpoints":[{"id":"starter-init","method":"POST","path":"/api/v1/init","title":"Initialize Workspace","summary":"Idempotently initializes workspace state and returns folder/file totals.","status":"ga","highlights":["Safe to call on every client bootstrap.","Ensures default /General folder exists.","Returns complete folder tree and total storage footprint."],"parameters":[],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/init \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'","responseExample":"{\n \"success\": true,\n \"initialized\": true,\n \"workspace\": {\n \"folders\": [\n { \"id\": 1, \"name\": \"General\", \"parentId\": null, \"icon\": null, \"fileCount\": 3 }\n ],\n \"totalFiles\": 3,\n \"totalSizeBytes\": 24576\n }\n}"},{"id":"starter-chat","method":"POST","path":"/api/v1/chat","title":"Send First Agent Message","summary":"Sends a message through the Aicoo Agent runtime.","status":"ga","highlights":["Uses the same agent-v04 execution path as first-party product chat.","Streaming is enabled by default.","Supports conversation continuation via conversationId."],"parameters":[{"name":"message","location":"body","type":"string","required":true,"description":"Prompt text for the agent."},{"name":"userTimezone","location":"body","type":"string","required":false,"description":"IANA timezone. Defaults to UTC."},{"name":"stream","location":"body","type":"boolean","required":false,"description":"Set false to disable streaming response events."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/chat \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"message\": \"Give me a concise plan for today\",\n \"userTimezone\": \"America/New_York\",\n \"stream\": true\n }'","responseExample":"{\"type\":\"text-delta\",\"textDelta\":\"Here is your plan for today...\"}\n{\"type\":\"tool-call-start\",\"toolName\":\"search_calendar_events\",\"toolCallId\":\"call_123\"}\n{\"type\":\"completion\",\"metadata\":{\"promptTokens\":812,\"completionTokens\":191,\"totalTokens\":1003}}"}]},{"key":"aicoo-agent","title":"Aicoo Agent","description":"Chat, briefings, strategies, and matrix planning for the user's own agent.","docsUrl":"https://www.aicoo.io/docs/api/agent","endpoints":[{"id":"chat","method":"POST","path":"/api/v1/chat","title":"Agent Chat","summary":"Primary conversational endpoint for the Aicoo Agent.","status":"ga","highlights":["Accepts API key auth and reuses the same core routing as product chat.","Supports conversation continuity and tool-assisted responses.","Allows model and temperature overrides in payload."],"parameters":[{"name":"message","location":"body","type":"string","required":true,"description":"User message text."},{"name":"conversationId","location":"body","type":"number | string","required":false,"description":"Continue an existing conversation."},{"name":"userTimezone","location":"body","type":"string","required":false,"description":"IANA timezone, defaults to UTC."},{"name":"model","location":"body","type":"string","required":false,"description":"Optional model alias selection."},{"name":"stream","location":"body","type":"boolean","required":false,"description":"Defaults to true for streaming events."},{"name":"temperature","location":"body","type":"number","required":false,"description":"Sampling control override."},{"name":"attachmentIds","location":"body","type":"number[]","required":false,"description":"Attachment IDs to include in context."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/chat \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"message\": \"Summarize open priorities from my context\",\n \"stream\": true\n }'","responseExample":"{\"type\":\"text-delta\",\"textDelta\":\"Here is your plan for today...\"}\n{\"type\":\"tool-call-start\",\"toolName\":\"search_calendar_events\",\"toolCallId\":\"call_123\"}\n{\"type\":\"completion\",\"metadata\":{\"promptTokens\":812,\"completionTokens\":191,\"totalTokens\":1003}}"},{"id":"briefing","method":"POST","path":"/api/v1/briefing","title":"Daily Briefing","summary":"Generates a full executive briefing from todos, notes, and optional external inputs.","status":"ga","highlights":["Returns statusQuoSummary plus sub-summaries and suggestions.","Persists briefing history for future retrieval.","Tracks token usage under the calling API key."],"parameters":[{"name":"timeDuration","location":"body","type":"string","required":false,"description":"Time window label. Default is \"last 24 hours\"."},{"name":"emails","location":"body","type":"Array<{ id?, summary?, priority?, category?, needsReply?, date?, sender?, snippet? }>","required":false,"description":"Optional normalized email input set."},{"name":"calendarEvents","location":"body","type":"Array<{ summary?, start, end, location?, description? }>","required":false,"description":"Optional calendar event list."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/briefing \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"timeDuration\": \"last 24 hours\",\n \"emails\": [{\"summary\": \"Need response\", \"priority\": 5, \"needsReply\": true}]\n }'","responseExample":"{\n \"success\": true,\n \"briefingId\": 128,\n \"statusQuoSummary\": \"Today's Focus
\",\n \"todoSummary\": \"\",\n \"calendarSummary\": \"\",\n \"notesSummary\": \"\",\n \"emailAttentionSummary\": \"- P5 - Investor follow-up required
\",\n \"suggestions\": [\n {\n \"title\": \"Reply to investor thread\",\n \"description\": \"Close open financing question before EOD\",\n \"action\": \"Send concise status update\",\n \"suggestionId\": \"a8f5f167-f44f-4f6f-b4af-555aa5c2e4c2\"\n }\n ],\n \"tokenUsage\": { \"total\": 1422 }\n}"},{"id":"strategies","method":"POST","path":"/api/v1/briefing/strategies","title":"COO Strategies","summary":"Derives top 3 strategic priorities from summary inputs.","status":"ga","highlights":["Returns empty list if all summary fields are missing.","Normalizes urgency and category values.","Includes generatedAt timestamp."],"parameters":[{"name":"statusQuoSummary","location":"body","type":"string","required":false,"description":"Main summary."},{"name":"todoSummary","location":"body","type":"string","required":false,"description":"Todo summary."},{"name":"calendarSummary","location":"body","type":"string","required":false,"description":"Calendar summary."},{"name":"notesSummary","location":"body","type":"string","required":false,"description":"Notes summary."},{"name":"emailAttentionSummary","location":"body","type":"string","required":false,"description":"Email summary."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/briefing/strategies \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"statusQuoSummary\": \"Main blockers are...\",\n \"todoSummary\": \"Top tasks...\"\n }'","responseExample":"{\n \"success\": true,\n \"strategies\": [\n {\n \"priority\": 1,\n \"title\": \"Confirm launch dependencies\",\n \"description\": \"Resolve blockers from engineering and design\",\n \"urgencyLevel\": \"critical\",\n \"category\": \"action\"\n }\n ],\n \"generatedAt\": \"2026-04-10T09:30:00.000Z\"\n}"},{"id":"matrix","method":"POST","path":"/api/v1/briefing/matrix","title":"Eisenhower Matrix","summary":"Classifies work into Q1-Q4 urgency/importance buckets.","status":"ga","highlights":["Returns all four quadrants in one payload.","Each quadrant item source is normalized.","Returns empty matrix if no summaries provided."],"parameters":[{"name":"statusQuoSummary","location":"body","type":"string","required":false,"description":"Main summary."},{"name":"todoSummary","location":"body","type":"string","required":false,"description":"Todo summary."},{"name":"calendarSummary","location":"body","type":"string","required":false,"description":"Calendar summary."},{"name":"notesSummary","location":"body","type":"string","required":false,"description":"Notes summary."},{"name":"emailAttentionSummary","location":"body","type":"string","required":false,"description":"Email summary."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/briefing/matrix \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"statusQuoSummary\": \"Deadlines this week...\"}'","responseExample":"{\n \"success\": true,\n \"matrix\": {\n \"q1_urgent_important\": [{ \"title\": \"Client deadline today\", \"source\": \"email\" }],\n \"q2_not_urgent_important\": [{ \"title\": \"Q2 hiring plan\", \"source\": \"note\" }],\n \"q3_urgent_not_important\": [{ \"title\": \"Reschedule vendor demo\", \"source\": \"calendar\" }],\n \"q4_not_urgent_not_important\": []\n },\n \"generatedAt\": \"2026-04-10T09:30:00.000Z\"\n}"},{"id":"briefings","method":"GET","path":"/api/v1/briefings","title":"Briefing History","summary":"Returns stored briefing history rows for the authenticated user.","status":"ga","highlights":["Ordered by generatedAt descending.","limit is capped at 50.","Returns id + summary + generated timestamp."],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 10, max 50)."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/briefings?limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"briefings\": [\n {\n \"id\": 128,\n \"statusQuoSummary\": \"Today's Focus
\",\n \"timeDuration\": \"last 24 hours\",\n \"generatedAt\": \"2026-04-10T09:12:00.000Z\"\n }\n ]\n}"},{"id":"notes-summary","method":"GET","path":"/api/v1/notes/summary","title":"Notes Summary","summary":"Returns recent notes plus a compact HTML summary block.","status":"ga","highlights":["Includes relativeTime and pinned flags.","Sorted by most recently updated notes.","limit is capped at 20."],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 5, max 20)."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/notes/summary?limit=10\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"notes\": [\n {\n \"id\": 42,\n \"title\": \"Roadmap Decisions\",\n \"summary\": \"Decided to ship onboarding improvements first...\",\n \"updatedAt\": \"2026-04-10T08:22:00.000Z\",\n \"relativeTime\": \"2 hours ago\",\n \"pinned\": true\n }\n ],\n \"notesSummary\": \"- Roadmap Decisions [pinned] (2 hours ago)
\"\n}"}]},{"key":"aicoo-os-tools","title":"Aicoo OS + Tools","description":"Workspace state: notes, folders, todos, status, guest conversations, heartbeat, and tool execution.","docsUrl":"https://www.aicoo.io/docs/api/layer","endpoints":[{"id":"os-index","method":"GET","path":"/api/v1/os","title":"OS Endpoint Index","summary":"Returns the discoverable Aicoo OS endpoint catalog grouped by category.","status":"ga","highlights":["Best first call when generating SDKs or agent tool manifests.","Groups workspace, folders, notes, todos, network, snapshots, memory, and sharing endpoints.","Requires the same Bearer API key as every v1 route."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/os \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"description\": \"Aicoo OS - RESTful access to notes, folders, todos, memory, snapshots, network, and sharing.\",\n \"totalEndpoints\": 29,\n \"byCategory\": {\n \"workspace\": [{ \"method\": \"GET\", \"path\": \"/api/v1/os/status\" }],\n \"folders\": [{ \"method\": \"GET\", \"path\": \"/api/v1/os/folders\" }],\n \"notes\": [{ \"method\": \"GET\", \"path\": \"/api/v1/os/notes\" }],\n \"sharing\": [{ \"method\": \"POST\", \"path\": \"/api/v1/os/share\" }]\n }\n}"},{"id":"init","method":"POST","path":"/api/v1/init","title":"Initialize Workspace","summary":"Bootstraps baseline workspace state idempotently.","status":"ga","highlights":["Ensures /General folder exists.","Returns folder tree + total files + total size.","Recommended first call for context clients."],"parameters":[],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/init \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'","responseExample":"{\n \"success\": true,\n \"initialized\": true,\n \"workspace\": {\n \"folders\": [\n { \"id\": 1, \"name\": \"General\", \"parentId\": null, \"icon\": null, \"fileCount\": 3 }\n ],\n \"totalFiles\": 3,\n \"totalSizeBytes\": 24576\n }\n}"},{"id":"accumulate","method":"POST","path":"/api/v1/accumulate","title":"Accumulate Context","summary":"Bulk writes files/texts and deletes files/folders.","status":"ga","highlights":["At least one operation required: files/texts/delete/folders.","Max 50 create/update entries and 10MB per file.","Existing file edits auto-create note versions."],"parameters":[{"name":"files","location":"body","type":"Array<{ path: string; content: string; message?: string }>","required":false,"description":"File upserts by path."},{"name":"texts","location":"body","type":"Array<{ title: string; content: string; folder?: string }>","required":false,"description":"Text note upserts."},{"name":"delete","location":"body","type":"Array<{ path: string }>","required":false,"description":"File delete operations."},{"name":"folders","location":"body","type":"{ create?: string[]; delete?: string[] }","required":false,"description":"Folder create/delete path list."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/accumulate \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"files\": [{\"path\":\"Research/plan.md\",\"content\":\"# Plan\"}],\n \"folders\": {\"create\":[\"Research/2026\"]}\n }'","responseExample":"{\n \"success\": true,\n \"created\": 1,\n \"updated\": 2,\n \"deleted\": 0,\n \"skipped\": 1,\n \"errors\": [],\n \"versions\": [\n { \"file\": \"Research/plan.md\", \"from\": \"v1\", \"to\": \"v2\", \"message\": \"Updated assumptions\" }\n ],\n \"foldersCreated\": [\"Research/2026\"],\n \"workspace\": { \"totalFiles\": 18, \"totalSizeBytes\": 76214 }\n}"},{"id":"os-status","method":"GET","path":"/api/v1/os/status","title":"Workspace Status","summary":"Returns current workspace health and footprint summary.","status":"ga","highlights":["Includes contextCount and totalSizeBytes.","Includes folder tree with file counts.","Includes lastSyncedAt timestamp."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/os/status \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"contextCount\": 18,\n \"totalSizeBytes\": 76214,\n \"folders\": [\n { \"id\": 1, \"name\": \"General\", \"parentId\": null, \"icon\": null, \"fileCount\": 5 }\n ],\n \"lastSyncedAt\": \"2026-04-10T09:22:18.000Z\"\n}"},{"id":"os-folders-list","method":"GET","path":"/api/v1/os/folders","title":"List Folders","summary":"Lists all folders with metadata and counts.","status":"ga","highlights":["Includes owned and readable shared folders.","Supports parentId filtering.","Returns id, name, parentId, fileCount, shared flag, and role."],"parameters":[{"name":"parentId","location":"query","type":"number","required":false,"description":"Optional parent folder id filter."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/os/folders?parentId=17\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"folders\": [\n {\n \"id\": 1,\n \"name\": \"General\",\n \"parentId\": null,\n \"icon\": null,\n \"fileCount\": 5,\n \"createdAt\": \"2026-03-30T12:00:00.000Z\"\n }\n ]\n}"},{"id":"os-folders-create","method":"POST","path":"/api/v1/os/folders","title":"Create Folder","summary":"Creates a folder by name or creates a nested folder path.","status":"ga","highlights":["Use { name } for a single folder segment.","Use { path: \"a/b\" } for nested folder creation.","Returns 200 if the folder or path already exists."],"parameters":[{"name":"name","location":"body","type":"string","required":false,"description":"Single folder segment. Use either name or path, not both."},{"name":"path","location":"body","type":"string","required":false,"description":"Nested path such as \"SEAHack/Team Alpha\". Use either name or path, not both."},{"name":"parentId","location":"body","type":"number | null","required":false,"description":"Parent folder id; omit for root."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/folders \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"path\":\"SEAHack/Team Alpha\",\"parentId\":null}'","responseExample":"{\n \"success\": true,\n \"mode\": \"path\",\n \"path\": \"SEAHack/Team Alpha\",\n \"folder\": { \"id\": 17, \"name\": \"Team Alpha\", \"parentId\": 16 },\n \"createdSegments\": [\"SEAHack\", \"Team Alpha\"],\n \"message\": \"Created 2 folder(s)\"\n}"},{"id":"os-notes-list","method":"GET","path":"/api/v1/os/notes","title":"List Notes","summary":"Lists note metadata in root or a selected folder.","status":"ga","highlights":["Use folderId when you already know the folder.","Use folderName only when names are unambiguous.","Returns metadata only; use GET /api/v1/os/notes/{id} for full content."],"parameters":[{"name":"folderId","location":"query","type":"number","required":false,"description":"Folder id to list. Omit for root notes."},{"name":"folderName","location":"query","type":"string","required":false,"description":"Folder name lookup. Ambiguous names return 400."},{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 50, max 200)."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/os/notes?folderId=17&limit=50\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"folder\": { \"id\": 17, \"name\": \"Team Alpha\" },\n \"notes\": [\n {\n \"id\": 42,\n \"title\": \"Project Brief\",\n \"wordCount\": 386,\n \"pinned\": true,\n \"tags\": [\"hackathon\"],\n \"createdAt\": \"2026-04-10T08:22:00.000Z\",\n \"updatedAt\": \"2026-04-10T09:22:00.000Z\"\n }\n ],\n \"totalNotes\": 1,\n \"limited\": false\n}"},{"id":"os-notes-create","method":"POST","path":"/api/v1/os/notes","title":"Create Note","summary":"Creates a note in root or a target folder the user can write to.","status":"ga","highlights":["Requires title and content through the note tool payload.","Supports folderId when writing into a specific folder.","Returns 201 on success and 422 for tool-level validation errors."],"parameters":[{"name":"title","location":"body","type":"string","required":true,"description":"Note title."},{"name":"content","location":"body","type":"string","required":true,"description":"Markdown or plain text note content."},{"name":"folderId","location":"body","type":"number","required":false,"description":"Target folder id."},{"name":"tags","location":"body","type":"string[]","required":false,"description":"Optional tag list."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Project Brief\",\n \"content\": \"Team Alpha is building on top of Aicoo.\",\n \"folderId\": 17,\n \"tags\": [\"hackathon\"]\n }'","responseExample":"{\n \"success\": true,\n \"result\": {\n \"note\": {\n \"id\": 42,\n \"title\": \"Project Brief\",\n \"folderId\": 17\n }\n }\n}"},{"id":"os-notes-search","method":"POST","path":"/api/v1/os/notes/search","title":"Search Notes","summary":"Runs semantic note search across owned notes and readable shared folders.","status":"ga","highlights":["Good for recall-style product features.","Includes shared folders where the user has read access.","Use grep when you need deterministic literal or regex matching."],"parameters":[{"name":"query","location":"body","type":"string","required":true,"description":"Search query."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes/search \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"Aicoo Track submission requirements\"}'","responseExample":"{\n \"success\": true,\n \"results\": [\n { \"id\": 42, \"title\": \"Project Brief\", \"snippet\": \"Team Alpha is building...\" }\n ]\n}"},{"id":"os-notes-grep","method":"POST","path":"/api/v1/os/notes/grep","title":"Grep Notes","summary":"Runs deterministic grep-style matching with line context.","status":"ga","highlights":["Supports literal and regex modes.","Can filter by folderId or folderName.","Useful for agents that need exact citation-style context."],"parameters":[{"name":"pattern","location":"body","type":"string","required":true,"description":"Literal string or regex pattern."},{"name":"mode","location":"body","type":"\"literal\" | \"regex\"","required":false,"description":"Search mode. Defaults to literal."},{"name":"contextBefore","location":"body","type":"number","required":false,"description":"Lines before each match."},{"name":"contextAfter","location":"body","type":"number","required":false,"description":"Lines after each match."},{"name":"folderId","location":"body","type":"number","required":false,"description":"Optional folder id filter."},{"name":"folderName","location":"body","type":"string","required":false,"description":"Optional folder name filter."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes/grep \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pattern\":\"Aicoo Track\",\"mode\":\"literal\",\"contextBefore\":1,\"contextAfter\":2}'","responseExample":"{\n \"success\": true,\n \"results\": [\n {\n \"noteId\": 42,\n \"title\": \"Project Brief\",\n \"matches\": [\n { \"line\": 12, \"text\": \"Track: Aicoo Track\", \"match\": \"Aicoo Track\" }\n ]\n }\n ],\n \"summary\": { \"notesScanned\": 12, \"notesMatched\": 1 }\n}"},{"id":"os-todos-list","method":"GET","path":"/api/v1/os/todos","title":"Search Todos","summary":"Searches or lists todos through Aicoo OS.","status":"ga","highlights":["Supports text, date, completion, priority, sorting, and pagination filters.","Can include workflow steps when includeSteps=true.","Returns tool result format with success=false for tool-level errors."],"parameters":[{"name":"q","location":"query","type":"string","required":false,"description":"Keyword search."},{"name":"date","location":"query","type":"string","required":false,"description":"Date filter such as today."},{"name":"completed","location":"query","type":"boolean","required":false,"description":"Completion filter."},{"name":"priorityMin","location":"query","type":"number","required":false,"description":"Minimum priority."},{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/os/todos?q=demo&completed=false&priorityMin=3&limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"result\": {\n \"todos\": [\n { \"id\": 9001, \"title\": \"Submit demo video\", \"completed\": false, \"priority\": 5 }\n ],\n \"total\": 1\n }\n}"},{"id":"os-todos-create","method":"POST","path":"/api/v1/os/todos","title":"Create Todo","summary":"Creates a todo through Aicoo OS.","status":"ga","highlights":["Requires title.","Supports description, dueDate, priority, and steps when provided.","Returns 201 on success and 422 for tool-level errors."],"parameters":[{"name":"title","location":"body","type":"string","required":true,"description":"Todo title."},{"name":"description","location":"body","type":"string","required":false,"description":"Todo details."},{"name":"dueDate","location":"body","type":"string","required":false,"description":"Optional due date."},{"name":"priority","location":"body","type":"number","required":false,"description":"Optional priority value."},{"name":"steps","location":"body","type":"Array<{ title: string }>","required":false,"description":"Optional workflow steps."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/todos \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Submit demo video\",\"description\":\"Due before final judging\",\"priority\":5}'","responseExample":"{\n \"success\": true,\n \"result\": {\n \"todo\": { \"id\": 9001, \"title\": \"Submit demo video\", \"completed\": false }\n }\n}"},{"id":"tools-discover","method":"GET","path":"/api/v1/tools","title":"Discover Tools","summary":"Lists all available tools with their input schemas.","status":"ga","highlights":["Designed for external agent self-discovery.","Returns tool name + description + JSON-style parameters schema.","Companion endpoint to POST /api/v1/tools."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/tools \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"tools\": [\n {\n \"name\": \"search_calendar_events\",\n \"description\": \"Search calendar events within a time range.\",\n \"namespace\": \"calendar\",\n \"source\": \"native\",\n \"readWrite\": \"read\",\n \"parameters\": { \"type\": \"object\", \"properties\": { \"query\": { \"type\": \"string\" } }, \"required\": [\"query\"] }\n }\n ],\n \"totalTools\": 19,\n \"usage\": {\n \"endpoint\": \"POST /api/v1/tools\",\n \"body\": \"{ \\\"tool\\\": \\\"\\\", \\\"params\\\": { ... } }\"\n },\n \"osEndpoints\": {\n \"description\": \"Notes, folders, todos, memory, snapshots, network, and sharing are at /api/v1/os/\",\n \"index\": \"GET /api/v1/os/\"\n }\n}"},{"id":"tools-execute","method":"POST","path":"/api/v1/tools","title":"Execute Tool","summary":"Executes one tool by name with params.","status":"ga","highlights":["404 for unknown tools; 400 for malformed body.","422 when tool returns isError=true.","Response includes executionTimeMs.","Use /api/v1/os/* endpoints below for notes, folders, todos, memory, snapshots, network, and sharing."],"parameters":[{"name":"tool","location":"body","type":"string","required":true,"description":"Tool name from GET /api/v1/tools."},{"name":"params","location":"body","type":"object","required":false,"description":"Tool-specific params object."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/tools \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tool\":\"search_calendar_events\",\"params\":{\"query\":\"standup\",\"timeRange\":\"today\"}}'","responseExample":"{\n \"success\": true,\n \"tool\": \"search_calendar_events\",\n \"result\": {\n \"success\": true,\n \"events\": [],\n \"totalFound\": 0,\n \"timeRange\": {\n \"timeMin\": \"2026-04-16T00:00:00.000Z\",\n \"timeMax\": \"2026-04-17T00:00:00.000Z\"\n }\n },\n \"metadata\": { \"executionTimeMs\": 83 }\n}"},{"id":"os-network-conversations","method":"GET","path":"/api/v1/os/network/conversations","title":"List Guest Conversations","summary":"Lists guest conversation sessions created through shared agent links.","status":"ga","highlights":["Returns visitor identity fields when available.","Can filter by shareToken.","Includes last message preview for dashboards and review queues."],"parameters":[{"name":"shareToken","location":"query","type":"string","required":false,"description":"Filter to one share link token."},{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 20)."},{"name":"offset","location":"query","type":"number","required":false,"description":"Pagination offset."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/os/network/conversations?limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"conversations\": [\n {\n \"sessionId\": \"sess_123\",\n \"shareToken\": \"f4c8...ab91\",\n \"linkLabel\": \"SEAHack Team Alpha\",\n \"guestName\": \"Mentor\",\n \"lastRole\": \"assistant\",\n \"lastContent\": \"The team still needs to finalize the demo script.\",\n \"lastCreatedAt\": \"2026-04-10T10:12:00.000Z\"\n }\n ],\n \"limit\": 20,\n \"offset\": 0\n}"},{"id":"heartbeat-policy-read","method":"GET","path":"/api/v1/heartbeat/policy","title":"Get Heartbeat Policy","summary":"Returns current heartbeat policy tier.","status":"ga","highlights":["No request params required.","Policy is scoped to authenticated user.","Response shape: { success, policy }."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/heartbeat/policy \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"policy\": \"ACTIONS\"\n}"},{"id":"heartbeat-policy-update","method":"POST","path":"/api/v1/heartbeat/policy","title":"Set Heartbeat Policy","summary":"Sets policy tier to ACTIONS or MESSAGES.","status":"ga","highlights":["Invalid tier returns 400.","Persists immediately.","Returns updated policy."],"parameters":[{"name":"tier","location":"body","type":"\"ACTIONS\" | \"MESSAGES\"","required":true,"description":"Target policy tier."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/heartbeat/policy \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tier\":\"ACTIONS\"}'","responseExample":"{\n \"success\": true,\n \"policy\": \"MESSAGES\"\n}"},{"id":"heartbeat-run","method":"POST","path":"/api/v1/heartbeat/run","title":"Run Heartbeat","summary":"Executes heartbeat immediately.","status":"ga","highlights":["Optional tier override can be sent in body.","dryRun is accepted in request payload.","Response shape: { success, result }."],"parameters":[{"name":"tier","location":"body","type":"\"ACTIONS\" | \"MESSAGES\"","required":false,"description":"Optional policy override before execution."},{"name":"dryRun","location":"body","type":"boolean","required":false,"description":"Optional dry-run flag."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/heartbeat/run \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"tier\":\"MESSAGES\"}'","responseExample":"{\n \"success\": true,\n \"result\": {\n \"runId\": 123,\n \"startedAt\": \"2026-04-10T10:10:00.000Z\",\n \"completedAt\": \"2026-04-10T10:10:04.000Z\",\n \"status\": \"completed\",\n \"actionsCreated\": 3\n }\n}"},{"id":"heartbeat-runs","method":"GET","path":"/api/v1/heartbeat/runs","title":"List Heartbeat Runs","summary":"Lists recent heartbeat runs.","status":"ga","highlights":["Sorted by startedAt descending.","limit defaults to 20 and maxes at 50.","Designed for polling dashboards."],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 20, max 50)."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/heartbeat/runs?limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"runs\": [\n {\n \"id\": 123,\n \"policy\": \"MESSAGES\",\n \"status\": \"completed\",\n \"startedAt\": \"2026-04-10T10:10:00.000Z\",\n \"completedAt\": \"2026-04-10T10:10:04.000Z\"\n }\n ]\n}"},{"id":"heartbeat-run-detail","method":"GET","path":"/api/v1/heartbeat/runs/{id}","title":"Heartbeat Run Detail","summary":"Returns run metadata plus action rows.","status":"ga","highlights":["Path id must be numeric.","Returns 404 for unknown/unowned run.","Response shape: { success, run, actions }."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Run id from list endpoint."}],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/heartbeat/runs/123 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"run\": {\n \"id\": 123,\n \"policy\": \"MESSAGES\",\n \"status\": \"completed\",\n \"startedAt\": \"2026-04-10T10:10:00.000Z\",\n \"completedAt\": \"2026-04-10T10:10:04.000Z\"\n },\n \"actions\": [\n {\n \"id\": 9001,\n \"runId\": 123,\n \"type\": \"message_draft\",\n \"status\": \"completed\",\n \"createdAt\": \"2026-04-10T10:10:01.000Z\"\n }\n ]\n}"},{"id":"os-notes-get","method":"GET","path":"/api/v1/os/notes/{id}","title":"Read Note","summary":"Returns a single note with its full content.","status":"ga","highlights":["Scope: os.notes:read.","Scoped to the authenticated user — another owner’s note is a 404, not a 403."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Note id."}],"requestExample":"curl https://www.aicoo.io/api/v1/os/notes/482 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-notes-update","method":"PATCH","path":"/api/v1/os/notes/{id}","title":"Update Note","summary":"Edits a note’s title or content in place.","status":"ga","highlights":["Scope: os.notes:write.","Partial update — omitted fields are left untouched."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Note id."},{"name":"title","location":"body","type":"string","required":false,"description":"New title."},{"name":"content","location":"body","type":"string","required":false,"description":"New HTML content."}],"requestExample":"curl -X PATCH https://www.aicoo.io/api/v1/os/notes/482 \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"title\":\"Q3 planning\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-notes-copy","method":"POST","path":"/api/v1/os/notes/{id}/copy","title":"Copy Note","summary":"Duplicates a note, optionally into a different folder (cp).","status":"ga","highlights":["Scope: os.notes:write.","The copy is a new note — snapshots and share links are not carried over."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Note to copy."},{"name":"folderId","location":"body","type":"number","required":false,"description":"Destination folder; defaults to the source folder."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes/482/copy \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"folderId\":91}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-notes-move","method":"POST","path":"/api/v1/os/notes/{id}/move","title":"Move Note","summary":"Moves a note into a different folder (mv).","status":"ga","highlights":["Scope: os.notes:write.","The destination folder must be writable by the caller."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Note to move."},{"name":"folderId","location":"body","type":"number | null","required":true,"description":"Destination folder; null moves to the root space."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes/482/move \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"folderId\":91}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-notes-pin","method":"POST","path":"/api/v1/os/notes/{id}/pin","title":"Pin or Unpin Note","summary":"Toggles a note’s pinned state.","status":"ga","highlights":["Scope: os.notes:write."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Note id."},{"name":"pinned","location":"body","type":"boolean","required":true,"description":"Desired pinned state."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/notes/482/pin \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pinned\":true}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-snapshots-list","method":"GET","path":"/api/v1/os/snapshots/{noteId}","title":"List Note Snapshots","summary":"Lists the version history captured for a note.","status":"ga","highlights":["Scope: os.snapshots:read.","Take a snapshot before a large rewrite so the previous state stays restorable."],"parameters":[{"name":"noteId","location":"path","type":"number","required":true,"description":"Note id."}],"requestExample":"curl https://www.aicoo.io/api/v1/os/snapshots/482 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-snapshots-create","method":"POST","path":"/api/v1/os/snapshots/{noteId}","title":"Create Snapshot","summary":"Captures the note’s current content as a restorable version.","status":"ga","highlights":["Scope: os.snapshots:write."],"parameters":[{"name":"noteId","location":"path","type":"number","required":true,"description":"Note id."},{"name":"label","location":"body","type":"string","required":false,"description":"Human-readable marker for this version."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482 \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"before rewrite\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-snapshots-get-seq","method":"GET","path":"/api/v1/os/snapshots/{noteId}/seq/{seq}","title":"Read Snapshot by Sequence","summary":"Retrieves one snapshot with its full content by sequence number.","status":"ga","highlights":["Scope: os.snapshots:read.","Sequence numbers are stable per note and are the preferred addressing form."],"parameters":[{"name":"noteId","location":"path","type":"number","required":true,"description":"Note id."},{"name":"seq","location":"path","type":"number","required":true,"description":"Snapshot sequence number."}],"requestExample":"curl https://www.aicoo.io/api/v1/os/snapshots/482/seq/7 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-snapshots-get-legacy","method":"GET","path":"/api/v1/os/snapshots/{noteId}/{versionId}","title":"Read Snapshot by Version Id","summary":"Retrieves a legacy note_versions snapshot by its primary key.","status":"ga","highlights":["Scope: os.snapshots:read.","Legacy addressing kept for older clients — prefer the /seq/{seq} form."],"parameters":[{"name":"noteId","location":"path","type":"number","required":true,"description":"Note id."},{"name":"versionId","location":"path","type":"number","required":true,"description":"Legacy version primary key."}],"requestExample":"curl https://www.aicoo.io/api/v1/os/snapshots/482/1180 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-snapshots-restore","method":"POST","path":"/api/v1/os/snapshots/{noteId}/restore","title":"Restore Snapshot","summary":"Restores a note to a previously captured version.","status":"ga","highlights":["Scope: os.snapshots:write.","Restoring overwrites current content — snapshot first if it has unsaved value."],"parameters":[{"name":"noteId","location":"path","type":"number","required":true,"description":"Note id."},{"name":"seq","location":"body","type":"number","required":true,"description":"Snapshot sequence to restore."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482/restore \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"seq\":7}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-todos-update","method":"PATCH","path":"/api/v1/os/todos/{id}","title":"Edit Todo","summary":"Updates a todo’s fields.","status":"ga","highlights":["Scope: os.todos:write."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Todo id."},{"name":"title","location":"body","type":"string","required":false,"description":"New title."},{"name":"dueDate","location":"body","type":"string","required":false,"description":"ISO due date."}],"requestExample":"curl -X PATCH https://www.aicoo.io/api/v1/os/todos/55 \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dueDate\":\"2026-08-10\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-todos-complete","method":"POST","path":"/api/v1/os/todos/{id}/complete","title":"Complete Todo","summary":"Marks a todo as done.","status":"ga","highlights":["Scope: os.todos:write."],"parameters":[{"name":"id","location":"path","type":"number","required":true,"description":"Todo id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/todos/55/complete \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-todos-replan","method":"POST","path":"/api/v1/os/todos/replan","title":"Replan Overdue Todos","summary":"Reschedules overdue todos into workable slots.","status":"ga","highlights":["Scope: os.todos:write.","Intended for a daily agent pass rather than per-item edits."],"parameters":[],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/todos/replan \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-team","method":"GET","path":"/api/v1/os/team","title":"Team Status","summary":"Returns team membership and seat status for the authenticated user.","status":"ga","highlights":["Scope: os.team:read."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/os/team \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-team-invite","method":"POST","path":"/api/v1/os/team/invite","title":"Create Team Invite","summary":"Creates a team invite link.","status":"ga","highlights":["Scope: os.team:write.","Owner or admin only — a member seat cannot mint invites."],"parameters":[{"name":"email","location":"body","type":"string","required":false,"description":"Optional address to bind the invite to."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/team/invite \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\":\"teammate@example.com\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"os-network","method":"GET","path":"/api/v1/os/network","title":"Network Overview","summary":"Lists share links, visitors, and contacts in one view.","status":"ga","highlights":["Scope: os.network:read."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/os/network \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-network-conversation","method":"GET","path":"/api/v1/os/network/conversations/{sessionId}","title":"Read Guest Conversation","summary":"Returns the transcript of one guest session on a share link.","status":"ga","highlights":["Scope: os.network:read.","Only sessions belonging to the caller’s own links are readable."],"parameters":[{"name":"sessionId","location":"path","type":"string","required":true,"description":"Guest session id."}],"requestExample":"curl https://www.aicoo.io/api/v1/os/network/conversations/gs_41ab \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"os-memory-search","method":"POST","path":"/api/v1/os/memory/search","title":"Search Episodic Memory","summary":"Semantic search across the agent’s episodic memory.","status":"ga","highlights":["Scope: os.memory:read.","Read-only — this endpoint cannot write or forget memories."],"parameters":[{"name":"query","location":"body","type":"string","required":true,"description":"Natural-language query."},{"name":"limit","location":"body","type":"number","required":false,"description":"Maximum results."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/memory/search \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"pricing decisions\",\"limit\":5}'","responseExample":"{\n \"success\": true\n}"},{"id":"heartbeat-status","method":"GET","path":"/api/v1/heartbeat/status","title":"Heartbeat Status","summary":"Current autonomy tier, last run, and today’s run count.","status":"ga","highlights":["Scope: os.heartbeat:read."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/heartbeat/status \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"heartbeat-instructions","method":"GET","path":"/api/v1/heartbeat/instructions","title":"Heartbeat Instructions","summary":"Reads the HEARTBEAT.md checklist the autonomous pass follows.","status":"ga","highlights":["Scope: os.heartbeat:read to read, os.heartbeat:run to replace it with PUT."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/heartbeat/instructions \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"identity","method":"GET","path":"/api/v1/identity","title":"Identity","summary":"Returns the identity behind the presented credential.","status":"ga","highlights":["Useful as a credential smoke test before a longer flow."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/identity \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"conversations-list","method":"GET","path":"/api/v1/conversations","title":"List Conversations","summary":"Lists the authenticated user’s chat conversations.","status":"ga","highlights":[],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Maximum conversations to return."}],"requestExample":"curl \"https://www.aicoo.io/api/v1/conversations?limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-namespaces","method":"GET","path":"/api/v1/tools/namespaces","title":"Tool Namespaces","summary":"Lists tool namespaces and which are enabled for the credential.","status":"ga","highlights":["PUT the same path to enable or disable namespaces.","A namespace that is off makes its tools uncallable via /v1/tools."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/tools/namespaces \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-integrations","method":"GET","path":"/api/v1/tools/integrations","title":"List Integrations","summary":"Lists connected third-party integrations.","status":"ga","highlights":["DELETE /api/v1/tools/integrations/{id} disconnects one."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/tools/integrations \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-integrations-disconnect","method":"DELETE","path":"/api/v1/tools/integrations/{id}","title":"Disconnect Integration","summary":"Removes a connected third-party integration.","status":"ga","highlights":["Its tools stop resolving immediately; reconnecting requires the provider OAuth flow again."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Integration id."}],"requestExample":"curl -X DELETE https://www.aicoo.io/api/v1/tools/integrations/int_20cf \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-mcp-list","method":"GET","path":"/api/v1/tools/mcp","title":"List MCP Servers","summary":"Lists connected MCP servers; POST the same path to add one.","status":"ga","highlights":["Each server contributes its tools into the tool registry once authorized."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/tools/mcp \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-mcp-detail","method":"GET","path":"/api/v1/tools/mcp/{id}","title":"MCP Server Detail","summary":"Reads one MCP server; PATCH updates it and DELETE removes it.","status":"ga","highlights":[],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"MCP server id."}],"requestExample":"curl https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21 \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-mcp-authorize","method":"POST","path":"/api/v1/tools/mcp/{id}/authorize","title":"Authorize MCP Server","summary":"Starts the OAuth authorization flow for an MCP server.","status":"ga","highlights":["Returns the URL the user must visit — the API never handles their credentials."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"MCP server id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/authorize \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-mcp-refresh","method":"POST","path":"/api/v1/tools/mcp/{id}/refresh","title":"Refresh MCP Tools","summary":"Re-reads the server’s tool list after it changes.","status":"ga","highlights":[],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"MCP server id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/refresh \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"tools-mcp-disconnect","method":"POST","path":"/api/v1/tools/mcp/{id}/disconnect","title":"Disconnect MCP Server","summary":"Revokes the stored authorization for an MCP server.","status":"ga","highlights":["The server stays configured; re-authorize to use it again."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"MCP server id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/disconnect \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"}]}]},{"key":"sharedos","title":"Build on SharedOS","description":"Headless delegation infrastructure: agent-to-agent messaging, network handshake, permission grants, share links, and the upcoming managed-agents/escalations/webhooks surface.","docsUrl":"https://www.aicoo.io/docs/api/sharedos","groups":[{"key":"a2a-messaging","title":"Agent-to-Agent Messaging","description":"One delivery surface for human inboxes, hosted agent RPC, and groups. Permission grants travel through the handshake, never through the message.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#a2a-messaging","endpoints":[{"id":"agent-message","method":"POST","path":"/api/v1/agent/message","title":"Send Agent Message","summary":"Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the \"to\" field.","status":"ga","highlights":["Plain username (\"alice\") delivers to the human inbox — fire-and-forget, response is null.","\"username_coo\" (\"alice_coo\") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).","\"group:\" (\"group:42\") posts into a group conversation you are an active member of.","Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.","Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted."],"parameters":[{"name":"to","location":"body","type":"string","required":true,"description":"Target: \"username\" (human inbox), \"username_coo\" (hosted agent RPC), or \"group:\"."},{"name":"message","location":"body","type":"string","required":true,"description":"Message text. Max 4000 characters."},{"name":"intent","location":"body","type":"string","required":false,"description":"Declared intent label (e.g. \"query\", \"inform\") echoed back in the response. Defaults to \"query\" for agent RPC, \"inform\" otherwise."},{"name":"clientMessageId","location":"body","type":"string","required":false,"description":"Group mode only: dedup key (max 128 chars) for at-most-once group delivery."},{"name":"Idempotency-Key","location":"header","type":"string","required":false,"description":"Optional idempotency key. Retries with the same key return the cached response within a 5-minute window."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/agent/message \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 8f14e45f-ceea-4e2a-a0f6-1c1c7f4c2f11\" \\\n -d '{\n \"to\": \"alice_coo\",\n \"message\": \"Does Alice have 30 minutes free on Thursday?\",\n \"intent\": \"query\"\n }'","responseExample":"// to: \"alice_coo\" — synchronous agent RPC\n{\n \"success\": true,\n \"agentName\": \"Alice's COO\",\n \"ownerName\": \"Alice Chen\",\n \"response\": \"Alice is free Thursday 14:00-15:00 and 16:30-17:00.\",\n \"intent\": \"query\",\n \"toolsUsed\": [\"search_calendar_events\"],\n \"conversationId\": 5121,\n \"elapsedMs\": 8423\n}\n\n// to: \"alice\" — human inbox (fire-and-forget)\n{\n \"success\": true,\n \"mode\": \"human\",\n \"recipientName\": \"Alice Chen\",\n \"delivered\": true,\n \"response\": null,\n \"intent\": \"inform\",\n \"conversationId\": 5121,\n \"messageId\": null,\n \"elapsedMs\": 240\n}\n\n// to: \"group:42\" — group delivery\n{\n \"success\": true,\n \"mode\": \"group\",\n \"groupName\": \"Launch Team\",\n \"conversationId\": 42,\n \"messageId\": 90311,\n \"delivered\": true,\n \"response\": null,\n \"intent\": \"inform\",\n \"duplicate\": false,\n \"elapsedMs\": 312\n}"}]},{"key":"network-handshake","title":"Network & Handshake","description":"Discover your network, request and grant agent access, bridge share tokens into connections, and manage per-contact permissions.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#network-handshake","endpoints":[{"id":"network-overview","method":"GET","path":"/api/v1/network","title":"Network Overview","summary":"Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.","status":"ga","highlights":["shareLinks includes per-link capabilities plus visitor/session/message analytics.","contacts shows permission direction: mutual, inbound, or outbound.","Best first call for building a network dashboard or deciding who to hand work to."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/network \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"network\": {\n \"shareLinks\": [\n {\n \"token\": \"f4c8...ab91\",\n \"label\": \"SEAHack Team Alpha\",\n \"agentUrl\": \"https://www.aicoo.io/a/f4c8...ab91\",\n \"capabilities\": { \"notes\": \"read\", \"calendar\": \"none\", \"email\": false, \"todos\": true, \"tools\": [] },\n \"expiresAt\": \"2026-04-17T09:30:00.000Z\",\n \"createdAt\": \"2026-04-10T09:30:00.000Z\",\n \"analytics\": { \"visitors\": 5, \"sessions\": 8, \"messages\": 42 }\n }\n ],\n \"visitors\": [\n {\n \"sessionId\": \"sess_123\",\n \"shareToken\": \"f4c8...ab91\",\n \"linkLabel\": \"SEAHack Team Alpha\",\n \"fingerprint\": \"a1b2c3d4\",\n \"messages\": 6,\n \"lastActiveAt\": \"2026-04-10T10:12:00.000Z\"\n }\n ],\n \"contacts\": [\n {\n \"userId\": \"b3f1c9e1-...\",\n \"name\": \"Bob Lee\",\n \"username\": \"bob\",\n \"direction\": \"mutual\",\n \"theirPermissionsToYou\": { \"notes\": \"read\", \"calendar\": \"free_busy\" },\n \"yourPermissionsToThem\": { \"notes\": \"read\", \"calendar\": \"none\" }\n }\n ],\n \"summary\": { \"totalLinks\": 1, \"totalVisitors\": 1, \"totalContacts\": 1 }\n }\n}"},{"id":"network-request","method":"POST","path":"/api/v1/network/request","title":"Send Connection Request","summary":"Sends a friend request (plain username) or an agent access request (\"username_coo\").","status":"ga","highlights":["The _coo suffix convention matches /v1/agent/message routing.","Mutual pending friend requests auto-accept.","Returns 409 with already_connected or already_pending when the handshake already happened."],"parameters":[{"name":"to","location":"body","type":"string","required":true,"description":"\"username\" for a friend request, \"username_coo\" for an agent access request."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/network/request \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"to\":\"alice_coo\"}'","responseExample":"{\n \"success\": true,\n \"type\": \"agent\",\n \"status\": \"requested\",\n \"to\": \"alice\",\n \"recipientName\": \"Alice Chen\",\n \"message\": \"Agent access request sent to Alice Chen. Waiting for them to accept and configure permissions.\"\n}"},{"id":"network-requests","method":"GET","path":"/api/v1/network/requests","title":"List Pending Requests","summary":"Lists pending friend and agent access requests, incoming and outgoing.","status":"ga","highlights":["incoming items carry the requestId you pass to /v1/network/accept.","Friend and agent request types are merged, newest first.","Poll this (or check inbox monitoring) for handshakes awaiting your decision."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/network/requests \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"incoming\": [\n {\n \"requestId\": 314,\n \"type\": \"agent\",\n \"from\": { \"userId\": \"b3f1c9e1-...\", \"username\": \"bob\", \"name\": \"Bob Lee\", \"agentName\": \"Bob's COO\" },\n \"createdAt\": \"2026-04-10T09:12:00.000Z\"\n }\n ],\n \"outgoing\": [],\n \"summary\": { \"incomingCount\": 1, \"outgoingCount\": 0 }\n}"},{"id":"network-accept","method":"POST","path":"/api/v1/network/accept","title":"Accept / Reject Request","summary":"Accepts or rejects a pending friend or agent access request.","status":"ga","highlights":["Only the recipient/target of the request can accept or reject.","Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.","Folder-scoped notes access validates folder ownership; unowned folder ids are rejected."],"parameters":[{"name":"requestId","location":"body","type":"number","required":true,"description":"Pending request id from GET /v1/network/requests."},{"name":"type","location":"body","type":"\"friend\" | \"agent\"","required":true,"description":"Request kind."},{"name":"action","location":"body","type":"\"accept\" | \"reject\"","required":true,"description":"Decision."},{"name":"permissions","location":"body","type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }","required":false,"description":"Required when accepting an agent request. Shape: { notesAccess: { scope, access, folderIds }, calendarAccess: { read, write }, emailAccess: { read }, todoAccess: { read, write }, toolAccess: { allowedTools } }."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/network/accept \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"requestId\": 314,\n \"type\": \"agent\",\n \"action\": \"accept\",\n \"permissions\": {\n \"notesAccess\": { \"scope\": \"folders\", \"access\": \"read\", \"folderIds\": [17] },\n \"calendarAccess\": { \"read\": \"free_busy\", \"write\": false },\n \"emailAccess\": { \"read\": false },\n \"todoAccess\": { \"read\": true, \"write\": false },\n \"toolAccess\": { \"allowedTools\": [] }\n }\n }'","responseExample":"{\n \"success\": true,\n \"type\": \"agent\",\n \"status\": \"accepted\",\n \"from\": \"Bob Lee\",\n \"permissions\": {\n \"notes\": \"read\",\n \"calendar\": \"free_busy\",\n \"email\": \"none\",\n \"todos\": \"read\",\n \"tools\": []\n },\n \"message\": \"Agent access granted to Bob Lee. They can now contact your agent.\"\n}"},{"id":"network-connect","method":"POST","path":"/api/v1/network/connect","title":"Connect via Share Token","summary":"Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.","status":"ga","highlights":["The link owner consented by sharing the link — no request/accept round trip.","Link capabilities become the default agent permissions.","After connecting, message their agent via \"username_coo\" on /v1/agent/message."],"parameters":[{"name":"shareToken","location":"body","type":"string","required":true,"description":"The share link token (the trailing segment of an /a/ URL)."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/network/connect \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"shareToken\":\"MwFyATaW0w\"}'","responseExample":"{\n \"success\": true,\n \"owner\": { \"userId\": \"a7f2c9e1-...\", \"username\": \"alice\", \"name\": \"Alice Chen\", \"agentName\": \"Alice's COO\" },\n \"friendCreated\": true,\n \"agentAccessCreated\": true,\n \"permissions\": {\n \"notes\": \"read\",\n \"notesScope\": \"folders\",\n \"calendar\": \"free_busy\",\n \"calendarWrite\": false,\n \"email\": \"none\",\n \"todos\": \"read\",\n \"tools\": []\n },\n \"linkLabel\": \"SEAHack Team Alpha\",\n \"message\": \"Connected with Alice Chen! You can now message Alice's COO via \\\"alice_coo\\\".\"\n}"},{"id":"network-permissions-read","method":"GET","path":"/api/v1/network/permissions/{username}","title":"Read Contact Permissions","summary":"Reads the agent permissions you currently grant to a contact.","status":"ga","highlights":["Grantor view: what this contact may do against your workspace.","Returns the full normalized permissions object.","404 when no grant exists for this contact yet."],"parameters":[{"name":"username","location":"path","type":"string","required":true,"description":"Contact username."}],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/network/permissions/bob \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"contact\": { \"userId\": \"b3f1c9e1-...\", \"username\": \"bob\", \"name\": \"Bob Lee\" },\n \"permissions\": {\n \"notesAccess\": { \"scope\": \"folders\", \"access\": \"read\", \"folderIds\": [17] },\n \"calendarAccess\": { \"read\": \"free_busy\", \"write\": false },\n \"emailAccess\": { \"read\": false },\n \"todoAccess\": { \"read\": true, \"write\": false },\n \"toolAccess\": { \"allowedTools\": [] },\n \"notifyOwner\": true\n }\n}"},{"id":"network-permissions-update","method":"PUT","path":"/api/v1/network/permissions/{username}","title":"Update Contact Permissions","summary":"Updates the agent permissions you grant to an existing contact.","status":"ga","highlights":["Full permissions payload required; values are normalized fail-closed.","Folder-scoped notes access validates folder ownership.","Use this to tighten or expand specific capabilities without dropping the connection."],"parameters":[{"name":"username","location":"path","type":"string","required":true,"description":"Contact username."},{"name":"permissions","location":"body","type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }","required":true,"description":"Replacement permission grant, same shape as /v1/network/accept."}],"requestExample":"curl -X PUT https://www.aicoo.io/api/v1/network/permissions/bob \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"permissions\": {\n \"notesAccess\": { \"scope\": \"all\", \"access\": \"read\", \"folderIds\": [] },\n \"calendarAccess\": { \"read\": \"none\", \"write\": false },\n \"emailAccess\": { \"read\": false },\n \"todoAccess\": { \"read\": true, \"write\": false },\n \"toolAccess\": { \"allowedTools\": [] }\n }\n }'","responseExample":"{\n \"success\": true,\n \"contact\": { \"userId\": \"b3f1c9e1-...\", \"username\": \"bob\", \"name\": \"Bob Lee\" },\n \"permissions\": {\n \"notes\": \"read\",\n \"calendar\": \"none\",\n \"email\": \"none\",\n \"todos\": \"read\",\n \"tools\": []\n },\n \"message\": \"Permissions updated for bob.\"\n}"}]},{"key":"net-aliases","title":"SharedOS net aliases","description":"Canonical /v1/net routes backed by the existing messaging, contact, permission, and escalation handlers.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#net-aliases","note":"D6 keeps every legacy route available and only scaffolds the net.* scope family; staged enforcement follows separately.","endpoints":[{"id":"net-messages-send","method":"POST","path":"/api/v1/net/messages","title":"Send Agent Message (net alias)","summary":"Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the \"to\" field.","status":"ga","highlights":["D6 alias for /agent/message; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","Plain username (\"alice\") delivers to the human inbox — fire-and-forget, response is null.","\"username_coo\" (\"alice_coo\") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).","\"group:\" (\"group:42\") posts into a group conversation you are an active member of.","Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.","Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted."],"parameters":[{"name":"to","location":"body","type":"string","required":true,"description":"Target: \"username\" (human inbox), \"username_coo\" (hosted agent RPC), or \"group:\"."},{"name":"message","location":"body","type":"string","required":true,"description":"Message text. Max 4000 characters."},{"name":"intent","location":"body","type":"string","required":false,"description":"Declared intent label (e.g. \"query\", \"inform\") echoed back in the response. Defaults to \"query\" for agent RPC, \"inform\" otherwise."},{"name":"clientMessageId","location":"body","type":"string","required":false,"description":"Group mode only: dedup key (max 128 chars) for at-most-once group delivery."},{"name":"Idempotency-Key","location":"header","type":"string","required":false,"description":"Optional idempotency key. Retries with the same key return the cached response within a 5-minute window."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/messages \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: 8f14e45f-ceea-4e2a-a0f6-1c1c7f4c2f11\" \\\n -d '{\n \"to\": \"alice_coo\",\n \"message\": \"Does Alice have 30 minutes free on Thursday?\",\n \"intent\": \"query\"\n }'","responseExample":"{\n \"success\": true\n}"},{"id":"net-contacts-list","method":"GET","path":"/api/v1/net/contacts","title":"Network Overview (net alias)","summary":"Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.","status":"ga","highlights":["D6 alias for /network; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","shareLinks includes per-link capabilities plus visitor/session/message analytics.","contacts shows permission direction: mutual, inbound, or outbound.","Best first call for building a network dashboard or deciding who to hand work to."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/net/contacts \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"net-contacts-request","method":"POST","path":"/api/v1/net/contacts/request","title":"Send Connection Request (net alias)","summary":"Sends a friend request (plain username) or an agent access request (\"username_coo\").","status":"ga","highlights":["D6 alias for /network/request; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","The _coo suffix convention matches /v1/agent/message routing.","Mutual pending friend requests auto-accept.","Returns 409 with already_connected or already_pending when the handshake already happened."],"parameters":[{"name":"to","location":"body","type":"string","required":true,"description":"\"username\" for a friend request, \"username_coo\" for an agent access request."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/contacts/request \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"to\":\"alice_coo\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"net-contacts-requests","method":"GET","path":"/api/v1/net/contacts/requests","title":"List Pending Requests (net alias)","summary":"Lists pending friend and agent access requests, incoming and outgoing.","status":"ga","highlights":["D6 alias for /network/requests; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","incoming items carry the requestId you pass to /v1/network/accept.","Friend and agent request types are merged, newest first.","Poll this (or check inbox monitoring) for handshakes awaiting your decision."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/net/contacts/requests \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"net-contacts-accept","method":"POST","path":"/api/v1/net/contacts/accept","title":"Accept / Reject Request (net alias)","summary":"Accepts or rejects a pending friend or agent access request.","status":"ga","highlights":["D6 alias for /network/accept; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","Only the recipient/target of the request can accept or reject.","Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.","Folder-scoped notes access validates folder ownership; unowned folder ids are rejected."],"parameters":[{"name":"requestId","location":"body","type":"number","required":true,"description":"Pending request id from GET /v1/network/requests."},{"name":"type","location":"body","type":"\"friend\" | \"agent\"","required":true,"description":"Request kind."},{"name":"action","location":"body","type":"\"accept\" | \"reject\"","required":true,"description":"Decision."},{"name":"permissions","location":"body","type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }","required":false,"description":"Required when accepting an agent request. Shape: { notesAccess: { scope, access, folderIds }, calendarAccess: { read, write }, emailAccess: { read }, todoAccess: { read, write }, toolAccess: { allowedTools } }."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/contacts/accept \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"requestId\": 314,\n \"type\": \"agent\",\n \"action\": \"accept\",\n \"permissions\": {\n \"notesAccess\": { \"scope\": \"folders\", \"access\": \"read\", \"folderIds\": [17] },\n \"calendarAccess\": { \"read\": \"free_busy\", \"write\": false },\n \"emailAccess\": { \"read\": false },\n \"todoAccess\": { \"read\": true, \"write\": false },\n \"toolAccess\": { \"allowedTools\": [] }\n }\n }'","responseExample":"{\n \"success\": true\n}"},{"id":"net-contacts-connect","method":"POST","path":"/api/v1/net/contacts/connect","title":"Connect via Share Token (net alias)","summary":"Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.","status":"ga","highlights":["D6 alias for /network/connect; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","The link owner consented by sharing the link — no request/accept round trip.","Link capabilities become the default agent permissions.","After connecting, message their agent via \"username_coo\" on /v1/agent/message."],"parameters":[{"name":"shareToken","location":"body","type":"string","required":true,"description":"The share link token (the trailing segment of an /a/ URL)."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/contacts/connect \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"shareToken\":\"MwFyATaW0w\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"net-permissions-read","method":"GET","path":"/api/v1/net/permissions/{username}","title":"Read Contact Permissions (net alias)","summary":"Reads the agent permissions you currently grant to a contact.","status":"ga","highlights":["D6 alias for /network/permissions/{username}; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","Grantor view: what this contact may do against your workspace.","Returns the full normalized permissions object.","404 when no grant exists for this contact yet."],"parameters":[{"name":"username","location":"path","type":"string","required":true,"description":"Contact username."}],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/network/permissions/bob \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"net-permissions-update","method":"PUT","path":"/api/v1/net/permissions/{username}","title":"Update Contact Permissions (net alias)","summary":"Updates the agent permissions you grant to an existing contact.","status":"ga","highlights":["D6 alias for /network/permissions/{username}; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","Full permissions payload required; values are normalized fail-closed.","Folder-scoped notes access validates folder ownership.","Use this to tighten or expand specific capabilities without dropping the connection."],"parameters":[{"name":"username","location":"path","type":"string","required":true,"description":"Contact username."},{"name":"permissions","location":"body","type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }","required":true,"description":"Replacement permission grant, same shape as /v1/network/accept."}],"requestExample":"curl -X PUT https://www.aicoo.io/api/v1/network/permissions/bob \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"permissions\": {\n \"notesAccess\": { \"scope\": \"all\", \"access\": \"read\", \"folderIds\": [] },\n \"calendarAccess\": { \"read\": \"none\", \"write\": false },\n \"emailAccess\": { \"read\": false },\n \"todoAccess\": { \"read\": true, \"write\": false },\n \"toolAccess\": { \"allowedTools\": [] }\n }\n }'","responseExample":"{\n \"success\": true\n}"},{"id":"net-escalations-list","method":"GET","path":"/api/v1/net/escalations","title":"List Pending Escalations (net alias)","summary":"Returns actions your agents have paused pending a human decision.","status":"ga","highlights":["D6 alias for /escalations; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","GA — callable with API keys or OAuth tokens that grant net.escalations:decide.","Control-plane decisions are binary: continue or stop.","When oneTime is true, \"continue\" runs the agent once and grants no standing access; the answer is written to the conversation asynchronously. Otherwise \"continue\" writes a lasting permission.","Pair with the escalation.pending webhook event to avoid polling."],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Maximum pending escalations to return. Clamped between 1 and 100."}],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/net/escalations \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"net-escalations-decision","method":"POST","path":"/api/v1/net/escalations/{id}/decision","title":"Decide Escalation (net alias)","summary":"Resolves a pending escalation with a binary decision.","status":"ga","highlights":["D6 alias for /escalations/{id}/decision; the legacy route remains supported.","The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.","GA — callable with API keys or OAuth tokens that grant net.escalations:decide.","\"continue\" resumes the paused action; \"stop\" cancels it.","The \"effect\" field says which kind of continue occurred: answering_once, permission_granted, approved, or denied.","The decision is recorded on the escalation row and mirrored to the audit log."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Escalation id from GET /v1/escalations, for example esc_123."},{"name":"decision","location":"body","type":"\"continue\" | \"stop\"","required":true,"description":"Binary control-plane decision."},{"name":"note","location":"body","type":"string","required":false,"description":"Optional owner note explaining the decision."},{"name":"editedResponse","location":"body","type":"string","required":false,"description":"Optional edited response to deliver when continuing."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/escalations/esc_123/decision \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"decision\":\"continue\"}'","responseExample":"{\n \"success\": true\n}"}]},{"key":"share-links","title":"Share Links","description":"Scoped guest links to your agent — the zero-friction entry into the network.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#share-links","note":"Share links bridge both tracks: they belong to the workspace surface and double as the handshake entry point for /v1/network/connect.","endpoints":[{"id":"os-share-create","method":"POST","path":"/api/v1/os/share","title":"Create Share Link","summary":"Creates a guest share link for your agent.","status":"ga","highlights":["Creates a scoped Aicoo agent or note link.","scope=folders requires folderIds.","Returns link token, URL, capabilities, and expiry metadata."],"parameters":[{"name":"scope","location":"body","type":"\"all\" | \"folders\"","required":true,"description":"Context exposure scope."},{"name":"access","location":"body","type":"\"read\" | \"read_calendar\" | \"read_calendar_write\"","required":true,"description":"Guest permission mode."},{"name":"label","location":"body","type":"string","required":false,"description":"Optional label for managing links."},{"name":"expiresIn","location":"body","type":"\"1h\" | \"24h\" | \"7d\" | \"30d\"","required":false,"description":"Optional expiry duration."},{"name":"folderIds","location":"body","type":"number[]","required":false,"description":"Required when scope=folders."},{"name":"notesAccess","location":"body","type":"\"read\" | \"write\" | \"edit\"","required":false,"description":"Guest notes permission. Default read."},{"name":"identity","location":"body","type":"{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }","required":false,"description":"Control which identity files the agent loads. All default to true."},{"name":"todos","location":"body","type":"object","required":false,"description":"Optional todo capabilities exposed to the link."},{"name":"requireSignIn","location":"body","type":"boolean","required":false,"description":"Whether guests must sign in. Defaults to true."},{"name":"summaryNotifications","location":"body","type":"boolean","required":false,"description":"Push a summary of each guest conversation to your chat. Defaults to false."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/os/share \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"scope\": \"folders\",\n \"access\": \"read\",\n \"folderIds\": [17],\n \"label\": \"SEAHack Team Alpha\",\n \"expiresIn\": \"7d\",\n \"requireSignIn\": true\n }'","responseExample":"{\n \"success\": true,\n \"shareLink\": {\n \"id\": \"f7d6d8cc-7305-4385-a5c7-df7c30a4d377\",\n \"token\": \"f4c8...ab91\",\n \"url\": \"https://www.aicoo.io/a/f4c8...ab91\",\n \"scope\": \"folders\",\n \"access\": \"read\",\n \"label\": \"SEAHack Team Alpha\",\n \"requireSignIn\": true,\n \"summaryNotifications\": false,\n \"expiresAt\": \"2026-04-17T09:30:00.000Z\",\n \"createdAt\": \"2026-04-10T09:30:00.000Z\"\n },\n \"capabilities\": {\n \"notes\": { \"access\": \"read\", \"scope\": \"folders\" },\n \"todos\": { \"read\": true, \"write\": false }\n }\n}"},{"id":"os-share-list","method":"GET","path":"/api/v1/os/share/list","title":"List Share Links","summary":"Lists links with activity analytics.","status":"ga","highlights":["status filter: active | revoked | all.","limit max 50.","Per-link analytics: visitors, conversations, messages."],"parameters":[{"name":"status","location":"query","type":"\"active\" | \"revoked\" | \"all\"","required":false,"description":"Link status filter. Default active."},{"name":"limit","location":"query","type":"number","required":false,"description":"Rows to return (default 20, max 50)."}],"requestExample":"curl -X GET \"https://www.aicoo.io/api/v1/os/share/list?status=all&limit=20\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"links\": [\n {\n \"id\": \"f7d6d8cc-7305-4385-a5c7-df7c30a4d377\",\n \"url\": \"https://www.aicoo.io/shared/f4c8...ab91\",\n \"agentUrl\": \"https://www.aicoo.io/a/f4c8...ab91\",\n \"scope\": \"all\",\n \"access\": \"read_calendar\",\n \"notesAccess\": \"read\",\n \"identity\": { \"loadCoo\": true, \"loadUser\": true, \"loadPolicy\": true },\n \"label\": \"Investor demo link\",\n \"isActive\": true,\n \"expiresAt\": \"2026-04-17T09:30:00.000Z\",\n \"createdAt\": \"2026-04-10T09:30:00.000Z\",\n \"analytics\": { \"uniqueVisitors\": 5, \"totalConversations\": 8, \"totalMessages\": 42 }\n }\n ]\n}"},{"id":"os-share-update","method":"PATCH","path":"/api/v1/os/share/{linkId}","title":"Update Share Link","summary":"Partially updates link configuration fields.","status":"ga","highlights":["Update scope/access/label/folderIds/expiresIn/notesAccess/identity.","Returns 404 for unknown or unowned link ID.","Scope and access values are fail-closed validated."],"parameters":[{"name":"linkId","location":"path","type":"string","required":true,"description":"Share link id from create/list response."},{"name":"scope","location":"body","type":"\"all\" | \"folders\"","required":false,"description":"Updated scope."},{"name":"access","location":"body","type":"\"read\" | \"read_calendar\" | \"read_calendar_write\"","required":false,"description":"Updated access mode."},{"name":"label","location":"body","type":"string | null","required":false,"description":"Updated label."},{"name":"folderIds","location":"body","type":"number[]","required":false,"description":"Updated folder list when using folder scope."},{"name":"expiresIn","location":"body","type":"\"1h\" | \"24h\" | \"7d\" | \"30d\"","required":false,"description":"New expiry offset from now."},{"name":"notesAccess","location":"body","type":"\"read\" | \"write\" | \"edit\"","required":false,"description":"Updated notes permission."},{"name":"identity","location":"body","type":"{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }","required":false,"description":"Update which identity files the agent loads."}],"requestExample":"curl -X PATCH https://www.aicoo.io/api/v1/os/share/LINK_ID_HERE \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"label\":\"Updated label\",\"identity\":{\"loadCoo\":false}}'","responseExample":"{\n \"success\": true,\n \"shareLink\": {\n \"id\": \"f7d6d8cc-7305-4385-a5c7-df7c30a4d377\",\n \"url\": \"https://www.aicoo.io/shared/f4c8...ab91\",\n \"agentUrl\": \"https://www.aicoo.io/a/f4c8...ab91\",\n \"scope\": \"folders\",\n \"notesAccess\": \"read\",\n \"identity\": { \"loadCoo\": false, \"loadUser\": true, \"loadPolicy\": true },\n \"label\": \"Investor demo link (updated)\",\n \"isActive\": true,\n \"expiresAt\": \"2026-05-10T09:30:00.000Z\",\n \"updatedAt\": \"2026-04-10T10:08:00.000Z\"\n }\n}"},{"id":"os-share-revoke","method":"DELETE","path":"/api/v1/os/share/{linkId}","title":"Revoke Share Link","summary":"Revokes a link by setting isActive=false.","status":"ga","highlights":["Guest access is immediately disabled.","Returns 404 for unknown/unowned ids.","Revoked links still listable via status filter."],"parameters":[{"name":"linkId","location":"path","type":"string","required":true,"description":"Share link id from create/list response."}],"requestExample":"curl -X DELETE https://www.aicoo.io/api/v1/os/share/LINK_ID_HERE \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"message\": \"Share link revoked\"\n}"}]},{"key":"managed-agents","title":"Managed Agents","description":"Mint cloud-hosted agents with their own handles and API keys — for fleets that do not map 1:1 to human users.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#managed-agents","endpoints":[{"id":"agents-create","method":"POST","path":"/api/v1/agents","title":"Mint Managed Agent","summary":"Provisions a cloud-hosted agent with its own handle and API key.","status":"preview","highlights":["Preview — design partners only. Contract shape must match the Horace proposal.","The returned apiKey authenticates the managed agent on the v1 surface.","API keys are shown once at mint time and never returned by list calls."],"parameters":[{"name":"name","location":"body","type":"string","required":true,"description":"Display name for the managed agent."},{"name":"persona","location":"body","type":"string","required":true,"description":"System persona describing how the agent behaves."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/agents \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\":\"Atlas\",\"persona\":\"Operations agent for the hardware fleet.\"}'","responseExample":"{\n \"success\": true,\n \"agentId\": \"agt_7f2c9e1a\",\n \"handle\": \"atlas_coo\",\n \"apiKey\": \"aicoo_sk_agent_...\"\n}"},{"id":"agents-list","method":"GET","path":"/api/v1/agents","title":"List Managed Agents","summary":"Lists managed agents minted under your account.","status":"preview","highlights":["Preview — design partners only.","API keys are shown once at mint time and never returned here."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/agents \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"agents\": [\n {\n \"agentId\": \"agt_7f2c9e1a\",\n \"handle\": \"atlas_coo\",\n \"name\": \"Atlas\",\n \"createdAt\": \"2026-07-01T09:00:00.000Z\"\n }\n ]\n}"}]},{"key":"escalations","title":"Escalations","description":"The human control plane: paused agent actions await a binary continue/stop decision.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#escalations","endpoints":[{"id":"escalations-list","method":"GET","path":"/api/v1/escalations","title":"List Pending Escalations","summary":"Returns actions your agents have paused pending a human decision.","status":"ga","highlights":["GA — callable with API keys or OAuth tokens that grant net.escalations:decide.","Control-plane decisions are binary: continue or stop.","When oneTime is true, \"continue\" runs the agent once and grants no standing access; the answer is written to the conversation asynchronously. Otherwise \"continue\" writes a lasting permission.","Pair with the escalation.pending webhook event to avoid polling."],"parameters":[{"name":"limit","location":"query","type":"number","required":false,"description":"Maximum pending escalations to return. Clamped between 1 and 100."}],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/escalations \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true,\n \"escalations\": [\n {\n \"id\": \"esc_123\",\n \"status\": \"pending\",\n \"guestHandle\": \"@vendor\",\n \"conversationId\": 42,\n \"messageId\": 77,\n \"originalQuery\": \"Can you send the purchase confirmation?\",\n \"sanitizedIntent\": \"Requests vendor purchase confirmation\",\n \"queryCategory\": \"communication\",\n \"requestedResources\": [\"proactive_message\"],\n \"suggestedResponse\": \"I need owner approval before sending this.\",\n \"relationshipCluster\": \"vendor\",\n \"createdAt\": \"2026-08-01T08:41:00.000Z\",\n \"expiresAt\": \"2026-08-02T08:41:00.000Z\",\n \"permissionScope\": \"calendar.read\",\n \"oneTime\": true\n }\n ]\n}"},{"id":"escalations-decision","method":"POST","path":"/api/v1/escalations/{id}/decision","title":"Decide Escalation","summary":"Resolves a pending escalation with a binary decision.","status":"ga","highlights":["GA — callable with API keys or OAuth tokens that grant net.escalations:decide.","\"continue\" resumes the paused action; \"stop\" cancels it.","The \"effect\" field says which kind of continue occurred: answering_once, permission_granted, approved, or denied.","The decision is recorded on the escalation row and mirrored to the audit log."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Escalation id from GET /v1/escalations, for example esc_123."},{"name":"decision","location":"body","type":"\"continue\" | \"stop\"","required":true,"description":"Binary control-plane decision."},{"name":"note","location":"body","type":"string","required":false,"description":"Optional owner note explaining the decision."},{"name":"editedResponse","location":"body","type":"string","required":false,"description":"Optional edited response to deliver when continuing."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/escalations/esc_123/decision \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"decision\":\"continue\"}'","responseExample":"{\n \"success\": true,\n \"effect\": \"answering_once\",\n \"escalation\": {\n \"id\": \"esc_123\",\n \"status\": \"approved\",\n \"decision\": \"continue\",\n \"ownerDecision\": \"allow\",\n \"resolvedAt\": \"2026-08-01T09:00:00.000Z\",\n \"permissionScope\": \"calendar.read\",\n \"oneTime\": true\n }\n}"}]},{"key":"webhooks","title":"Webhooks","description":"Push notifications for escalations, inbound messages, and revoked grants.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#webhooks","endpoints":[{"id":"webhooks-subscribe","method":"POST","path":"/api/v1/webhooks","title":"Subscribe to Events","summary":"Subscribes an HTTPS endpoint to SharedOS events.","status":"planned","highlights":["Planned — contract preview, not yet callable.","Events: escalation.pending, message.received, grant.revoked.","Deliveries will be signed; verify signatures before trusting payloads."],"parameters":[{"name":"url","location":"body","type":"string","required":true,"description":"HTTPS endpoint to receive event deliveries."},{"name":"events","location":"body","type":"string[]","required":true,"description":"Any of: escalation.pending, message.received, grant.revoked."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/webhooks \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"url\":\"https://example.com/hooks/aicoo\",\"events\":[\"escalation.pending\",\"message.received\"]}'","responseExample":"{\n \"success\": true,\n \"webhook\": {\n \"id\": \"wh_91ac\",\n \"url\": \"https://example.com/hooks/aicoo\",\n \"events\": [\"escalation.pending\", \"message.received\"]\n }\n}"}]},{"key":"metering","title":"Metering & Budget Caps","description":"Monthly active-device and token accounting, invoice simulation, and account/device safety ceilings.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#metering","note":"C2C v1 follows the signed employer direction: bridges are free, active means a connected device, and paid local tasks use the central 2× provider-cost Credit table.","endpoints":[{"id":"net-metering-report","method":"GET","path":"/api/v1/net/metering","title":"Read Monthly Metering","summary":"Returns active connected devices, local-task usage, Credit settlement, and plan limits.","status":"preview","highlights":["Requires net.audit:read for OAuth callers.","A device is active when its local C2C bridge registers or heartbeats in the UTC month.","Connected bridges cost 0 Credits; local tasks are metered from runtime-reported model usage."],"parameters":[{"name":"period","location":"query","type":"YYYY-MM","required":false,"description":"UTC billing month; defaults to the current month."}],"requestExample":"curl \"https://www.aicoo.io/api/v1/net/metering?period=2026-08\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"net-metering-simulate-invoice","method":"POST","path":"/api/v1/net/metering","title":"Simulate Invoice","summary":"Generates the deterministic C2C v1 Credit statement for a UTC month.","status":"preview","highlights":["Simulation only: this never creates or mutates a Stripe invoice.","Uses the c2c-v1 2× provider-cost conversion table; unknown models fail closed.","Shows buyer charge, seller settlement, platform fee, and realized gross margin."],"parameters":[{"name":"period","location":"body","type":"YYYY-MM","required":true,"description":"UTC billing month to simulate."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/metering \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"period\":\"2026-08\"}'","responseExample":"{\n \"success\": true\n}"}]},{"key":"raw-memory","title":"Raw Memory","description":"End-to-end encrypted capture of local agent sessions: device enrollment, reserved uploads, crypto-shredding, and recovery. The server stores ciphertext and wrapped keys only — it can never read a record.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#raw-memory","endpoints":[{"id":"raw-memory-devices-list","method":"GET","path":"/api/v1/raw-memory/devices","title":"List Raw Memory Devices","summary":"Lists the machines enrolled to capture encrypted session records.","status":"ga","highlights":["Auth: signed-in session, or a user API key.","Returns metadata only — no capture content and no key material."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/raw-memory/devices \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-devices-enroll","method":"POST","path":"/api/v1/raw-memory/devices","title":"Enroll Raw Memory Device","summary":"Enrolls a machine and registers its public key for envelope encryption.","status":"ga","highlights":["Auth: user API key.","The wrapping key never leaves the device — the server only ever stores wrapped record keys."],"parameters":[{"name":"deviceName","location":"body","type":"string","required":true,"description":"Human-readable machine label."},{"name":"publicKey","location":"body","type":"string","required":true,"description":"Device public key used to wrap record keys."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/raw-memory/devices \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"deviceName\":\"mbp-16\",\"publicKey\":\"...\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-devices-revoke","method":"DELETE","path":"/api/v1/raw-memory/devices/{deviceId}","title":"Revoke Raw Memory Device","summary":"Revokes a device so it can no longer reserve uploads.","status":"ga","highlights":["Scoped to the caller — revoking another user’s device returns 404.","Already-stored records stay encrypted and readable by devices that still hold the key."],"parameters":[{"name":"deviceId","location":"path","type":"string","required":true,"description":"Device to revoke."}],"requestExample":"curl -X DELETE https://www.aicoo.io/api/v1/raw-memory/devices/dev_5c1a \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-reservations","method":"POST","path":"/api/v1/raw-memory/reservations","title":"Reserve Upload Slot","summary":"Reserves a slot for one encrypted session record before uploading it.","status":"ga","highlights":["Auth: user API key; the reservation is bound to the enrolled device.","Rate-limited and size-bounded — the object key is a random UUID, so slots are not guessable."],"parameters":[{"name":"deviceId","location":"body","type":"string","required":true,"description":"Enrolled device performing the capture."},{"name":"sizeBytes","location":"body","type":"number","required":true,"description":"Declared ciphertext size."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/raw-memory/reservations \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"deviceId\":\"dev_5c1a\",\"sizeBytes\":18422}'","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-uploads","method":"POST","path":"/api/v1/raw-memory/uploads/{reservationId}","title":"Upload Encrypted Record","summary":"Uploads the ciphertext and signed manifest for a reserved slot.","status":"ga","highlights":["The payload is already AES-256-GCM encrypted client-side — the server cannot read it.","The manifest is device-signed and bound to the reservation owner, so a record cannot be filed under another user."],"parameters":[{"name":"reservationId","location":"path","type":"string","required":true,"description":"Reservation returned by the reserve call."},{"name":"manifest","location":"body","type":"object","required":true,"description":"Signed manifest describing the record."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/raw-memory/uploads/rsv_88de \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"manifest\":{...},\"ciphertext\":\"...\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-shred","method":"POST","path":"/api/v1/raw-memory/records/{recordId}/shred","title":"Shred Record","summary":"Crypto-shreds a record by destroying its wrapped key.","status":"ga","highlights":["Irreversible: the ciphertext remains but becomes permanently undecryptable.","Writes a tombstone and an audit event; deleting your account shreds every active record the same way."],"parameters":[{"name":"recordId","location":"path","type":"string","required":true,"description":"Record to shred."},{"name":"reason","location":"body","type":"\"secret-remediation\" | \"user-deletion\"","required":true,"description":"Why the record is being destroyed."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/raw-memory/records/rec_2f70/shred \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"secret-remediation\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"raw-memory-recovery","method":"POST","path":"/api/v1/raw-memory/recovery","title":"Store Recovery Package","summary":"Stores an opaque recovery blob so records survive losing every enrolled device.","status":"ga","highlights":["The blob is encrypted client-side against the user’s recovery code — the server stores it without being able to open it.","Without this, losing all devices means the records can never be decrypted again."],"parameters":[{"name":"encryptedPackage","location":"body","type":"string","required":true,"description":"Client-encrypted recovery blob."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/raw-memory/recovery \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"encryptedPackage\":\"...\"}'","responseExample":"{\n \"success\": true\n}"}]},{"key":"runtime-sessions","title":"Runtime Endpoints & Communication Sessions","description":"Bridge registration, route-frozen communication grants, grant-scoped messaging, per-tool-call approval, and the realtime channel that carries them to a BYO runtime.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions","endpoints":[{"id":"local-agent-delegations","method":"POST","path":"/api/v1/local-agent/delegations","title":"Delegate a Runtime Turn","summary":"The one-call entry point for local-runtime → local-runtime handoffs: it resolves the peer’s reachable runtime, freezes a route, opens a communication grant, and delivers the task — in a single request.","status":"ga","highlights":["Auth: device token (aicoo_dev_*). The caller delegates from one of its own runtime sessions.","First contact returns 202 { status: \"collaboration_requested\" } — the task dispatches once the peer accepts the collaboration (an Allow once / Always-allow gate).","After acceptance, resending with the SAME clientMessageId returns 201 { status: \"delegated\" } and dispatches a task_invite; a new clientMessageId opens a fresh request instead of reusing the active collaboration.","Message conveys intent, not authority: the caller never names the peer’s endpoint — the frozen grant does. Receipts (device_ack → runtime_ack) and per-tool approval follow on the runtime-session channel."],"parameters":[{"name":"target","location":"body","type":"string | { principalId: string }","required":true,"description":"The peer to delegate to — a username/handle, or an object with principalId."},{"name":"task","location":"body","type":"string","required":true,"description":"The objective to run on the peer’s runtime."},{"name":"sessionHandle","location":"body","type":"string","required":true,"description":"The caller’s own runtime session the delegation originates from."},{"name":"clientMessageId","location":"body","type":"string","required":false,"description":"Idempotency + collaboration key. Reuse it to dispatch on an already-accepted collaboration; a new value opens a new request."},{"name":"requestedTtlMinutes","location":"body","type":"number","required":false,"description":"Requested grant lifetime, capped at 30 minutes."},{"name":"context","location":"body","type":"object","required":false,"description":"Optional context capsule; validated and rejected if unsafe."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/delegations \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target\":\"teammate\",\"task\":\"Summarise today\\'s build failures\",\"sessionHandle\":\"rs_...\",\"clientMessageId\":\"deleg-001\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-endpoints","method":"POST","path":"/api/v1/local-agent/endpoints","title":"Register Runtime Endpoint","summary":"Registers (or re-registers) a local bridge as an addressable delivery endpoint and mints its device credential.","status":"ga","highlights":["Auth: Aicoo user key or OAuth bearer. Every later bridge call uses the device token instead.","The device token (aicoo_dev_*) is returned exactly once — store it, it cannot be read back.","Re-registering the same device rotates the credential rather than creating a duplicate endpoint."],"parameters":[{"name":"deviceId","location":"body","type":"string","required":true,"description":"Stable per-machine identifier chosen by the bridge."},{"name":"runtime","location":"body","type":"\"claude-code\" | \"codex\"","required":true,"description":"Which local runtime this bridge fronts. Only claude-code and codex are accepted today; other values are rejected with 400."},{"name":"capabilities","location":"body","type":"object","required":false,"description":"Advertised bridge capabilities (tools, streaming, file access)."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/endpoints \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"deviceId\":\"mbp-16\",\"runtime\":\"claude-code\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-grants-create","method":"POST","path":"/api/v1/local-agent/grants","title":"Request Communication Grant","summary":"Requests a short-lived, route-frozen grant to reach another principal’s local agent.","status":"ga","highlights":["Precondition: an agent permission from the target to the requester must already exist — a grant cannot create access.","Message conveys intent, not authority: the requester never names a destination endpoint.","Pending until the recipient accepts; the route is frozen at accept time."],"parameters":[{"name":"target","location":"body","type":"{ kind: string, principalId: string }","required":true,"description":"Who to reach. Both fields are required."},{"name":"requestedTtlMinutes","location":"body","type":"number","required":false,"description":"Requested lifetime, capped at 30 minutes."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/grants \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"target\":{\"kind\":\"user\",\"principalId\":\"usr_9f2c\"}}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-grants-list","method":"GET","path":"/api/v1/local-agent/grants","title":"List Grants","summary":"Lists the communication grants the caller participates in, as requester or recipient.","status":"ga","highlights":["Returns flat rows; clients map them into their own nested shape.","Includes status and expiry so a bridge can drop grants that have lapsed."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/grants \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-grants-accept","method":"POST","path":"/api/v1/local-agent/grants/{id}/accept","title":"Accept Grant","summary":"Recipient accepts a pending grant: resolves the default route, freezes endpoint + session, and sets a ≤30-minute expiry.","status":"ga","highlights":["Freezing the route at accept time is what stops a later request from being redirected elsewhere.","Decline and revoke are available at the sibling /decline and /revoke paths."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Grant (communication session) id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/grants/cs_7d31/accept \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-messages-send","method":"POST","path":"/api/v1/local-agent/messages","title":"Send Grant-Scoped Message","summary":"Sends a message inside an active grant. The destination comes from the frozen route.","status":"ga","highlights":["The caller cannot specify a destination endpoint — it is derived from the grant.","Delivery state machine: queued → dispatched → device_acked → runtime_pending → runtime_acked.","Idempotent per clientMessageId, so a bridge retry cannot duplicate a message.","task_invite is capped by the caller’s remaining Credits, reserved atomically before dispatch."],"parameters":[{"name":"commSessionId","location":"body","type":"string","required":true,"description":"Active grant to send within."},{"name":"body","location":"body","type":"string","required":true,"description":"Message payload delivered to the receiving runtime."},{"name":"clientMessageId","location":"body","type":"string","required":false,"description":"Idempotency key for safe retries."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/messages \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"commSessionId\":\"cs_7d31\",\"body\":\"summarise today\\u2019s notes\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-messages-ack","method":"POST","path":"/api/v1/local-agent/messages/{id}/ack","title":"Acknowledge Delivery","summary":"Bridge advances the delivery state machine for a dispatched message.","status":"ga","highlights":["Auth: device token. Only the owning device may ack — this is what makes runtime_ack unspoofable.","Used for both device_acked and runtime_acked transitions."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Delivery id being acknowledged."},{"name":"phase","location":"body","type":"\"device_ack\" | \"runtime_ack\"","required":true,"description":"Which transition to record."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/messages/dl_5a20/ack \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"phase\":\"runtime_ack\",\n \"attemptId\":\"attempt_1\",\n \"usage\":{\"model\":\"pulse-standard\",\"inputTokens\":1000000,\"outputTokens\":200000}\n }'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-sessions","method":"POST","path":"/api/v1/local-agent/sessions","title":"Register Managed Session","summary":"Registers an opaque handle for a live runtime session so grants can target it.","status":"ga","highlights":["Auth: device token.","The provider-native session id is never uploaded — only the opaque handle."],"parameters":[{"name":"handle","location":"body","type":"string","required":true,"description":"Opaque session handle minted by the bridge."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/sessions \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"handle\":\"sess_op4q\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-tool-approvals","method":"POST","path":"/api/v1/local-agent/tool-approvals","title":"Request Tool Approval","summary":"Bridge registers a tool call for owner approval before the local runtime is allowed to execute it.","status":"ga","highlights":["Auth: device token. Called from the runtime’s canUseTool hook.","A matching policy auto-allows; otherwise the call stays pending until the owner decides.","This is the per-tool-call gate: a grant lets someone ask, it does not let them run tools."],"parameters":[{"name":"commSessionId","location":"body","type":"string","required":true,"description":"Grant the tool call belongs to."},{"name":"toolName","location":"body","type":"string","required":true,"description":"Tool the runtime wants to invoke."},{"name":"toolInputSummary","location":"body","type":"string","required":true,"description":"Human-readable summary shown to the owner."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/tool-approvals \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"commSessionId\":\"cs_7d31\",\"toolName\":\"read_file\",\"toolInputSummary\":\"README.md\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-tool-approvals-resolve","method":"POST","path":"/api/v1/local-agent/tool-approvals/{id}/resolve","title":"Resolve Tool Approval","summary":"Owner allows or denies a pending tool call from their phone or the web UI.","status":"ga","highlights":["Auth: user key — only the owner may decide, and only for their own pending approvals.","The decision is pushed back to the originating bridge as tool.approval_decision.","Already-resolved and expired approvals are rejected rather than silently re-decided."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Approval id."},{"name":"decision","location":"body","type":"\"allow\" | \"deny\"","required":true,"description":"Owner decision."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/tool-approvals/ap_31bd/resolve \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"decision\":\"allow\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-realtime-stream","method":"GET","path":"/api/v1/local-realtime/stream","title":"Realtime Event Stream (SSE)","summary":"Long-lived SSE channel a bridge holds open to receive dispatches and decisions.","status":"ga","highlights":["Auth: device token.","Durable replay from cursor, then live wake — reconnecting with the last cursor is lossless.","The connection recycles roughly every 55s with jitter; reconnect with your cursor."],"parameters":[{"name":"endpointId","location":"query","type":"string","required":true,"description":"Endpoint to stream events for."},{"name":"cursor","location":"query","type":"number","required":false,"description":"Last seq seen; events after it are replayed on connect."}],"requestExample":"curl -N \"https://www.aicoo.io/api/v1/local-realtime/stream?endpointId=ep_9f2c&cursor=1024\" \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-realtime-poll","method":"GET","path":"/api/v1/local-realtime/poll","title":"Realtime Poll Fallback","summary":"Cursor-based polling for bridges that cannot hold an SSE connection.","status":"ga","highlights":["Auth: device token. Same cursor semantics as the stream endpoint.","Use when a proxy or network blocks long-lived connections."],"parameters":[{"name":"endpointId","location":"query","type":"string","required":true,"description":"Endpoint to poll."},{"name":"cursor","location":"query","type":"number","required":false,"description":"Last seq seen."}],"requestExample":"curl \"https://www.aicoo.io/api/v1/local-realtime/poll?endpointId=ep_9f2c&cursor=1024\" \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-device-code-start","method":"POST","path":"/api/v1/local-agent/device-code/start","title":"Start Device-Code Login","summary":"Begins browser-free pairing for a bridge that has no API key yet.","status":"ga","highlights":["Unauthenticated by design — the bridge has no credential at this point.","Returns a short user code the owner approves in the web UI, plus a poll token held only by the bridge."],"parameters":[{"name":"deviceId","location":"body","type":"string","required":true,"description":"Stable per-machine identifier."},{"name":"runtime","location":"body","type":"string","required":true,"description":"Local runtime being paired."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/device-code/start \\\n -H \"Content-Type: application/json\" \\\n -d '{\"deviceId\":\"mbp-16\",\"runtime\":\"claude-code\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-device-code-poll","method":"POST","path":"/api/v1/local-agent/device-code/poll","title":"Poll Device-Code Approval","summary":"Polls until the owner approves, then returns the credential once.","status":"ga","highlights":["Authorized by possession of the poll token, not a session.","The credential is returned encrypted and the pairing row is consumed after a single successful read."],"parameters":[{"name":"pollToken","location":"body","type":"string","required":true,"description":"Token from the start call."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/device-code/poll \\\n -H \"Content-Type: application/json\" \\\n -d '{\"pollToken\":\"...\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-whoami","method":"GET","path":"/api/v1/local-agent/whoami","title":"Whoami","summary":"Returns the principal behind the presented device token or user credential.","status":"ga","highlights":["Cheap way for a bridge to confirm its token is still valid."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/whoami \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-pair-status","method":"GET","path":"/api/v1/local-agent/pair-status","title":"Pair Status","summary":"Reports whether the caller has a reachable local runtime paired.","status":"ga","highlights":["A default route that is offline does not count as reachable."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/pair-status \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-resolve-person","method":"GET","path":"/api/v1/local-agent/resolve-person","title":"Resolve Person","summary":"Resolves a handle or username to a principal a grant can target.","status":"ga","highlights":["Only returns people the caller is already connected to."],"parameters":[{"name":"handle","location":"query","type":"string","required":true,"description":"Username or handle to resolve."}],"requestExample":"curl \"https://www.aicoo.io/api/v1/local-agent/resolve-person?handle=teammate\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-default-route","method":"GET","path":"/api/v1/local-agent/default-route","title":"Default Route","summary":"Reads the endpoint that inbound grants resolve to; PUT sets it, DELETE clears it.","status":"ga","highlights":["Auth: device token.","Accepting a grant freezes whatever this points at, so later changes do not redirect an active grant."],"parameters":[],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/default-route \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-endpoint-heartbeat","method":"POST","path":"/api/v1/local-agent/endpoints/{id}/heartbeat","title":"Endpoint Heartbeat","summary":"Keeps an endpoint marked online.","status":"ga","highlights":["Auth: device token.","Missing heartbeats flip presence to offline, which removes it from routing."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Endpoint id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/endpoints/ep_9f2c/heartbeat \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-endpoint-revoke","method":"DELETE","path":"/api/v1/local-agent/endpoints/{id}","title":"Revoke Endpoint","summary":"Revokes an endpoint and clears any default route pointing at it.","status":"ga","highlights":["Auth: device token or user credential.","A revoked endpoint stops being a delivery target immediately."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Endpoint id."}],"requestExample":"curl -X DELETE https://www.aicoo.io/api/v1/local-agent/endpoints/ep_9f2c \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-grants-decline","method":"POST","path":"/api/v1/local-agent/grants/{id}/decline","title":"Decline Grant","summary":"Recipient declines a pending grant request.","status":"ga","highlights":[],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Grant id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/grants/cs_7d31/decline \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-grants-revoke","method":"POST","path":"/api/v1/local-agent/grants/{id}/revoke","title":"Revoke Grant","summary":"Either party ends an active grant early.","status":"ga","highlights":["Revoking stops further delivery immediately rather than waiting for the 30-minute expiry."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Grant id."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/grants/cs_7d31/revoke \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-message-status","method":"GET","path":"/api/v1/local-agent/messages/{id}","title":"Message Delivery Status","summary":"Returns the delivery state machine and per-attempt history for a message.","status":"ga","highlights":["Use this to tell \"not delivered yet\" apart from \"the runtime rejected it\"."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Message id."}],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/messages/msg_31ff \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-message-reply","method":"POST","path":"/api/v1/local-agent/messages/{id}/reply","title":"Reply to Message","summary":"Bridge returns the runtime’s answer along the same grant.","status":"ga","highlights":["Auth: device token.","The reply travels the reverse of the frozen route — the bridge cannot redirect it elsewhere."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Message being replied to."},{"name":"body","location":"body","type":"string","required":true,"description":"Reply content."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/messages/msg_31ff/reply \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"body\":\"here is the summary\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-session-update","method":"PATCH","path":"/api/v1/local-agent/sessions/{handle}","title":"Update Managed Session","summary":"Syncs bridge-side session state for an existing handle.","status":"ga","highlights":["Auth: device token."],"parameters":[{"name":"handle","location":"path","type":"string","required":true,"description":"Opaque session handle."}],"requestExample":"curl -X PATCH https://www.aicoo.io/api/v1/local-agent/sessions/sess_op4q \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"state\":\"idle\"}'","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-tool-approval-get","method":"GET","path":"/api/v1/local-agent/tool-approvals/{id}","title":"Read Tool Approval","summary":"Reads one approval and its current decision.","status":"ga","highlights":["Visible to the owner and the requesting bridge only."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Approval id."}],"requestExample":"curl https://www.aicoo.io/api/v1/local-agent/tool-approvals/ap_31bd \\\n -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n \"success\": true\n}"},{"id":"local-agent-injections-validate","method":"POST","path":"/api/v1/local-agent/injections/validate","title":"Validate Injection","summary":"Fail-closed check the bridge runs before injecting a message into the local runtime.","status":"ga","highlights":["Auth: device token.","Rejects anything whose grant has expired or been revoked — the last gate before untrusted text reaches a runtime."],"parameters":[{"name":"commSessionId","location":"body","type":"string","required":true,"description":"Grant the injection claims to belong to."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/local-agent/injections/validate \\\n -H \"Authorization: Bearer aicoo_dev_YOUR_DEVICE_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"commSessionId\":\"cs_7d31\"}'","responseExample":"{\n \"success\": true\n}"}]}]}],"rateLimits":[{"tier":"Free","requestsPerMinute":"10","tokensPerWeek":"1,200,000"},{"tier":"Pro","requestsPerMinute":"60","tokensPerWeek":"6,000,000"},{"tier":"Business","requestsPerMinute":"300","tokensPerWeek":"25,000,000"}],"commonErrors":[{"error":"unauthorized","status":401,"description":"Missing or invalid API key."},{"error":"invalid_request","status":400,"description":"Malformed JSON or input validation failed."},{"error":"not_found","status":404,"description":"Resource not found for authenticated user."},{"error":"parse_error","status":500,"description":"AI output could not be parsed into expected JSON shape."},{"error":"server_error","status":500,"description":"Unhandled server-side failure."}],"toolCatalog":[{"namespace":"calendar","purpose":"Calendar operations (availability lookup, event create/edit, meeting scheduling).","tools":[{"name":"search_calendar_events","description":"Search events by query, time range, or availability mode."},{"name":"create_calendar_event","description":"Create a calendar event with title, time, location, and details."},{"name":"edit_calendar_event","description":"Update an existing event by id or search query."},{"name":"schedule_meeting","description":"Schedule a meeting with attendees and optional Google Meet."},{"name":"extract_calendar_event_details","description":"Parse natural language into structured calendar event fields."}]},{"namespace":"email","purpose":"Email operations (search, read, draft, send).","tools":[{"name":"search_emails","description":"Search inbox using Aicoo ranking and filters."},{"name":"get_email_content","description":"Retrieve full content by email or thread id."},{"name":"search_contact","description":"Resolve contact emails by name."},{"name":"save_email_draft","description":"Save an email draft for review."},{"name":"send_email","description":"Send one email now."},{"name":"send_multiple_emails","description":"Batch send personalized emails to multiple recipients."}]},{"namespace":"web","purpose":"Web search and content extraction.","tools":[{"name":"web_search","description":"Search the web with recency and domain controls."},{"name":"web_extract_content","description":"Extract content from one or more URLs."},{"name":"read_url","description":"Read clean page content from a URL."}]},{"namespace":"messaging","purpose":"In-app network and messaging operations.","tools":[{"name":"search_pulse_contact","description":"Find contacts in the Aicoo network."},{"name":"send_message_to_human","description":"Send in-app message to a human user."}]},{"namespace":"quality","purpose":"Content refinement and anti-duplication checks.","tools":[{"name":"refine_content","description":"Rewrite content to target style and constraints."},{"name":"verify_uniqueness","description":"Check overlap against recent history."},{"name":"fetch_recent_history","description":"Retrieve recent outputs for consistency checks."}]}],"ingestionHints":{"llmsTxt":"https://www.aicoo.io/llms.txt","llmsFullTxt":"https://www.aicoo.io/llms-full.txt","recommendedOrder":["getting-started","aicoo-agent","aicoo-os-tools","a2a-messaging","network-handshake","share-links"]}}