{"specVersion":"1.0.0","generatedAt":"2026-07-12T19:46:50.983Z","product":"Aicoo","apiVersion":"v1","docsUrl":"https://www.aicoo.io/docs/api","baseUrl":"https://www.aicoo.io/api/v1","authentication":{"type":"bearer","header":"Authorization","format":"Bearer YOUR_API_KEY","apiKeySetupUrl":"https://www.aicoo.io/settings/api-keys"},"layers":[{"key":"getting-started","title":"Layer 1: Intro + API Key","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.","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.","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":"Layer 2: Aicoo 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.","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.","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.","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.","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.","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.","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":"Layer 3: Aicoo OS + Tools","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.","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.","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.","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.","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.","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.","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.","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.","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.","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.","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.","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.","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.","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.","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-share-create","method":"POST","path":"/api/v1/os/share","title":"Create Share Link","summary":"Creates a guest share link for your agent.","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.","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.","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.","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}"},{"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.","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.","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.","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.","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.","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.","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}"}]}],"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"]}}