{"specVersion":"1.0.0","generatedAt":"2026-04-12T23:54:32.080Z","product":"Pulse","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 Pulse 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\":\"list_notes\",\"toolCallId\":\"call_123\"}\n{\"type\":\"completion\",\"metadata\":{\"promptTokens\":812,\"completionTokens\":191,\"totalTokens\":1003}}"}]},{"key":"pulse-agent","title":"Layer 2: Pulse 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 Pulse 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\":\"list_notes\",\"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":"pulse-layer","title":"Layer 3: Pulse Layer","docsUrl":"https://www.aicoo.io/docs/api/layer","endpoints":[{"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":"context-status","method":"GET","path":"/api/v1/context/status","title":"Context 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/context/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":"context-folders-list","method":"GET","path":"/api/v1/context/folders","title":"List Folders","summary":"Lists all folders with metadata and counts.","highlights":["Includes id, name, parentId, fileCount, createdAt.","Sorted by folder name.","Read operation with low token usage tracking."],"parameters":[],"requestExample":"curl -X GET https://www.aicoo.io/api/v1/context/folders \\\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":"context-folders-create","method":"POST","path":"/api/v1/context/folders","title":"Create Folder","summary":"Creates a folder under root or specified parent folder.","highlights":["Returns 201 on create.","Returns 200 if folder already exists on same level.","Validates parent ownership."],"parameters":[{"name":"name","location":"body","type":"string","required":true,"description":"Folder name (required, non-empty)."},{"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/context/folders \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Client Notes\",\"parentId\":null}'","responseExample":"{\n  \"success\": true,\n  \"folder\": { \"id\": 17, \"name\": \"Client Notes\", \"parentId\": null, \"fileCount\": 0 }\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_notes\",\n      \"description\": \"Search through notes using AI-powered multi-query semantic search.\",\n      \"category\": \"notes\",\n      \"parameters\": { \"type\": \"object\", \"properties\": { \"query\": { \"type\": \"string\" } }, \"required\": [\"query\"] }\n    }\n  ],\n  \"usage\": {\n    \"endpoint\": \"POST /api/v1/tools\",\n    \"body\": \"{ \\\"tool\\\": \\\"<tool_name>\\\", \\\"params\\\": { ... } }\"\n  }\n}"},{"id":"tools-execute","method":"POST","path":"/api/v1/tools","title":"Execute Tool","summary":"Executes one tool by name with params.","highlights":["400 for unknown tools or malformed body.","422 when tool returns isError=true.","Response includes executionTimeMs."],"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\":\"list_notes\",\"params\":{\"folderId\":5,\"limit\":20}}'","responseExample":"{\n  \"success\": true,\n  \"tool\": \"list_notes\",\n  \"result\": {\n    \"success\": true,\n    \"folder\": { \"id\": 5, \"name\": \"Research\" },\n    \"notes\": [{ \"id\": 81, \"title\": \"Launch Notes\", \"wordCount\": 421 }],\n    \"totalNotes\": 1,\n    \"limited\": false\n  },\n  \"metadata\": { \"executionTimeMs\": 83 }\n}"},{"id":"share-create","method":"POST","path":"/api/v1/share/create","title":"Create Share Link","summary":"Creates a guest share link for your agent.","highlights":["Default scope=all, access=read, identity=all loaded.","scope=folders requires folderIds.","Returns link token and full URL."],"parameters":[{"name":"scope","location":"body","type":"\"all\" | \"folders\"","required":false,"description":"Context exposure scope."},{"name":"access","location":"body","type":"\"read\" | \"read_calendar\" | \"read_calendar_write\"","required":false,"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."}],"requestExample":"curl -X POST https://www.aicoo.io/api/v1/share/create \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"scope\":\"all\",\"access\":\"read_calendar\",\"expiresIn\":\"7d\",\"identity\":{\"loadCoo\":true,\"loadUser\":true,\"loadPolicy\":true}}'","responseExample":"{\n  \"success\": true,\n  \"shareLink\": {\n    \"id\": \"f7d6d8cc-7305-4385-a5c7-df7c30a4d377\",\n    \"token\": \"f4c8...ab91\",\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    \"anonymous\": true,\n    \"expiresAt\": \"2026-04-17T09:30:00.000Z\",\n    \"createdAt\": \"2026-04-10T09:30:00.000Z\"\n  }\n}"},{"id":"share-list","method":"GET","path":"/api/v1/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/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":"share-update","method":"PATCH","path":"/api/v1/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/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":"share-revoke","method":"DELETE","path":"/api/v1/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/share/LINK_ID_HERE \\\n  -H \"Authorization: Bearer YOUR_API_KEY\"","responseExample":"{\n  \"success\": true,\n  \"message\": \"Share link revoked\"\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":[{"category":"Notes Tools","purpose":"Search, read, create, edit, and pin note content.","tools":[{"name":"search_notes","description":"AI-powered multi-query semantic search across notes."},{"name":"get_note_content","description":"Retrieve full content for a note by ID."},{"name":"create_note","description":"Create a new note with markdown/plain/HTML content."},{"name":"edit_note","description":"Update existing note content/title/folder with backup behavior."},{"name":"pin_note","description":"Pin or unpin a note."}]},{"category":"Memory Tools","purpose":"Retrieve historical episodic context.","tools":[{"name":"memory_search","description":"Search episodic memories and stored context."}]},{"category":"Workspace Primitives","purpose":"Inspect folders and note listings like filesystem commands.","tools":[{"name":"list_folders","description":"List folders with metadata and file counts."},{"name":"list_notes","description":"List notes in a folder with summary metadata."}]},{"category":"Sharing Primitive","purpose":"Create share links from tool-call workflows.","tools":[{"name":"share_agent","description":"Create guest share links with scope/access/identity settings. Control COO.md, USER.md, POLICY.md loading per link."}]}],"ingestionHints":{"llmsTxt":"https://www.aicoo.io/llms.txt","llmsFullTxt":"https://www.aicoo.io/llms-full.txt","recommendedOrder":["getting-started","pulse-agent","pulse-layer"]}}