{"specVersion":"2.0.0","generatedAt":"2026-07-28T05:01:21.433Z","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\": \"<h3>Today's Focus</h3><ul><li>Finalize partner brief</li></ul>\",\n  \"todoSummary\": \"<ul><li>Finish Q3 review</li></ul>\",\n  \"calendarSummary\": \"<ul><li>Client sync at 2:00 PM</li></ul>\",\n  \"notesSummary\": \"<ul><li>Roadmap draft updated</li></ul>\",\n  \"emailAttentionSummary\": \"<ul><li>P5 - Investor follow-up required</li></ul>\",\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\": \"<h3>Today's Focus</h3><ul><li>...</li></ul>\",\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\": \"<ul><li><strong>Roadmap Decisions</strong> [pinned] <span>(2 hours ago)</span></li></ul>\"\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 workspace data: 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\\\": \\\"<tool_name>\\\", \\\"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}"}]}]},{"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:<id>\" (\"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:<conversationId>\"."},{"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/<token> 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":"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."}],"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    \"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 may change before GA.","The returned apiKey authenticates the managed agent on the v1 surface.","The handle is addressable on /v1/agent/message like any other agent."],"parameters":[{"name":"name","location":"body","type":"string","required":true,"description":"Display name for the managed agent."},{"name":"persona","location":"body","type":"string","required":false,"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":"planned","highlights":["Planned — contract preview, not yet callable.","Control-plane decisions are binary: continue or stop.","Pair with the escalation.pending webhook event to avoid polling."],"parameters":[],"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_5f21\",\n      \"agent\": \"atlas_coo\",\n      \"summary\": \"Wants to send a purchase confirmation to vendor@example.com\",\n      \"intent\": \"commit\",\n      \"requestedAt\": \"2026-07-20T08:41:00.000Z\",\n      \"status\": \"pending\"\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":"planned","highlights":["Planned — contract preview, not yet callable.","\"continue\" resumes the paused action; \"stop\" cancels it."],"parameters":[{"name":"id","location":"path","type":"string","required":true,"description":"Escalation id from GET /v1/escalations."},{"name":"decision","location":"body","type":"\"continue\" | \"stop\"","required":true,"description":"Binary control-plane decision."}],"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  \"id\": \"esc_5f21\",\n  \"decision\": \"continue\"\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":"runtime-sessions","title":"Runtime Endpoints & Communication Sessions","description":"Device/runtime registration and 30-minute communication grants for realtime delivery to BYO runtimes.","docsUrl":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions","endpoints":[{"id":"net-endpoints","method":"POST","path":"/api/v1/net/endpoints","title":"Register Runtime Endpoint","summary":"Registers a device or runtime as an addressable delivery endpoint for realtime agent messaging.","status":"planned","highlights":["Planned — contract preview from the realtime messaging spec, not yet callable.","An endpoint is where messages get dispatched: a phone, a desktop app, or a BYO agent runtime."],"parameters":[{"name":"kind","location":"body","type":"\"device\" | \"runtime\"","required":true,"description":"Endpoint class being registered."},{"name":"name","location":"body","type":"string","required":false,"description":"Human-readable endpoint label."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/endpoints \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"kind\":\"runtime\",\"name\":\"claude-code-desktop\"}'","responseExample":"{\n  \"success\": true,\n  \"endpoint\": {\n    \"id\": \"ep_9f2c\",\n    \"kind\": \"runtime\",\n    \"name\": \"claude-code-desktop\",\n    \"status\": \"registered\"\n  }\n}"},{"id":"net-sessions","method":"POST","path":"/api/v1/net/sessions","title":"Open Communication Session","summary":"Opens a short-lived communication grant (30 minutes) between two endpoints for realtime delivery.","status":"planned","highlights":["Planned — contract preview, not yet callable.","Delivery state machine: queued → dispatched → device_acked → runtime_pending → runtime_acked.","Sessions expire after 30 minutes; re-open to continue the conversation."],"parameters":[{"name":"endpointId","location":"body","type":"string","required":true,"description":"Target endpoint id from POST /v1/net/endpoints."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/net/sessions \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"endpointId\":\"ep_9f2c\"}'","responseExample":"{\n  \"success\": true,\n  \"session\": {\n    \"id\": \"cs_44d1\",\n    \"endpointId\": \"ep_9f2c\",\n    \"state\": \"queued\",\n    \"expiresInSeconds\": 1800\n  }\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"]}}