{"openapi":"3.0.3","info":{"title":"Aicoo and SharedOS API","version":"1.0.0","description":"One protocol with two identity sources: Build on Aicoo for workspace-backed agents, or Build on SharedOS for headless delegation infrastructure."},"servers":[{"url":"https://www.aicoo.io/api/v1","description":"Aicoo production API"}],"tags":[{"name":"track:aicoo","description":"Build on Aicoo API operations."},{"name":"group:aicoo-os-tools","description":"Aicoo OS + Tools: Workspace state: notes, folders, todos, status, guest conversations, heartbeat, and tool execution."},{"name":"status:ga","description":"Live in production."},{"name":"group:aicoo-agent","description":"Aicoo Agent: Chat, briefings, strategies, and matrix planning for the user's own agent."},{"name":"track:sharedos","description":"Build on SharedOS API operations."},{"name":"group:a2a-messaging","description":"Agent-to-Agent Messaging: One delivery surface for human inboxes, hosted agent RPC, and groups. Permission grants travel through the handshake, never through the message."},{"name":"group:network-handshake","description":"Network & Handshake: Discover your network, request and grant agent access, bridge share tokens into connections, and manage per-contact permissions."},{"name":"group:net-aliases","description":"SharedOS net aliases: Canonical /v1/net routes backed by the existing messaging, contact, permission, and escalation handlers."},{"name":"group:share-links","description":"Share Links: Scoped guest links to your agent — the zero-friction entry into the network."},{"name":"group:managed-agents","description":"Managed Agents: Mint cloud-hosted agents with their own handles and API keys — for fleets that do not map 1:1 to human users."},{"name":"status:preview","description":"Available to design partners; contract may change."},{"name":"group:escalations","description":"Escalations: The human control plane: paused agent actions await a binary continue/stop decision."},{"name":"group:webhooks","description":"Webhooks: Push notifications for escalations, inbound messages, and revoked grants."},{"name":"status:planned","description":"Contract preview only; not yet callable."},{"name":"group:metering","description":"Metering & Budget Caps: Monthly active-device and token accounting, invoice simulation, and account/device safety ceilings."},{"name":"group:raw-memory","description":"Raw Memory: End-to-end encrypted capture of local agent sessions: device enrollment, reserved uploads, crypto-shredding, and recovery. The server stores ciphertext and wrapped keys only — it can never read a record."},{"name":"group:runtime-sessions","description":"Runtime Endpoints & Communication Sessions: Bridge registration, route-frozen communication grants, grant-scoped messaging, per-tool-call approval, and the realtime channel that carries them to a BYO runtime."}],"paths":{"/init":{"post":{"operationId":"init","summary":"Initialize Workspace","description":"Bootstraps baseline workspace state idempotently.\n\n- Ensures /General folder exists.\n- Returns folder tree + total files + total size.\n- Recommended first call for context clients.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"initialized":true,"workspace":{"folders":[{"id":1,"name":"General","parentId":null,"icon":null,"fileCount":3}],"totalFiles":3,"totalSizeBytes":24576}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/chat":{"post":{"operationId":"chat","summary":"Agent Chat","description":"Primary conversational endpoint for the Aicoo Agent.\n\n- Accepts API key auth and reuses the same core routing as product chat.\n- Supports conversation continuity and tool-assisted responses.\n- Allows model and temperature overrides in payload.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","x-aicoo-source-type":"string"},"conversationId":{"oneOf":[{"type":"number"},{"type":"string"}],"x-aicoo-source-type":"number | string"},"userTimezone":{"type":"string","x-aicoo-source-type":"string"},"model":{"type":"string","x-aicoo-source-type":"string"},"stream":{"type":"boolean","x-aicoo-source-type":"boolean"},"temperature":{"type":"number","x-aicoo-source-type":"number"},"attachmentIds":{"type":"array","items":{"type":"number"},"x-aicoo-source-type":"number[]"}},"required":["message"]}}}},"responses":{"200":{"description":"Successful response","content":{"text/plain":{"schema":{"type":"string"},"example":"{\"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}}"}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/briefing":{"post":{"operationId":"briefing","summary":"Daily Briefing","description":"Generates a full executive briefing from todos, notes, and optional external inputs.\n\n- Returns statusQuoSummary plus sub-summaries and suggestions.\n- Persists briefing history for future retrieval.\n- Tracks token usage under the calling API key.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"timeDuration":{"type":"string","x-aicoo-source-type":"string"},"emails":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ id?, summary?, priority?, category?, needsReply?, date?, sender?, snippet? }"},"x-aicoo-source-type":"Array<{ id?, summary?, priority?, category?, needsReply?, date?, sender?, snippet? }>"},"calendarEvents":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ summary?, start, end, location?, description? }"},"x-aicoo-source-type":"Array<{ summary?, start, end, location?, description? }>"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"briefingId":128,"statusQuoSummary":"<h3>Today's Focus</h3><ul><li>Finalize partner brief</li></ul>","todoSummary":"<ul><li>Finish Q3 review</li></ul>","calendarSummary":"<ul><li>Client sync at 2:00 PM</li></ul>","notesSummary":"<ul><li>Roadmap draft updated</li></ul>","emailAttentionSummary":"<ul><li>P5 - Investor follow-up required</li></ul>","suggestions":[{"title":"Reply to investor thread","description":"Close open financing question before EOD","action":"Send concise status update","suggestionId":"a8f5f167-f44f-4f6f-b4af-555aa5c2e4c2"}],"tokenUsage":{"total":1422}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/briefing/strategies":{"post":{"operationId":"strategies","summary":"COO Strategies","description":"Derives top 3 strategic priorities from summary inputs.\n\n- Returns empty list if all summary fields are missing.\n- Normalizes urgency and category values.\n- Includes generatedAt timestamp.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"statusQuoSummary":{"type":"string","x-aicoo-source-type":"string"},"todoSummary":{"type":"string","x-aicoo-source-type":"string"},"calendarSummary":{"type":"string","x-aicoo-source-type":"string"},"notesSummary":{"type":"string","x-aicoo-source-type":"string"},"emailAttentionSummary":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"strategies":[{"priority":1,"title":"Confirm launch dependencies","description":"Resolve blockers from engineering and design","urgencyLevel":"critical","category":"action"}],"generatedAt":"2026-04-10T09:30:00.000Z"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/briefing/matrix":{"post":{"operationId":"matrix","summary":"Eisenhower Matrix","description":"Classifies work into Q1-Q4 urgency/importance buckets.\n\n- Returns all four quadrants in one payload.\n- Each quadrant item source is normalized.\n- Returns empty matrix if no summaries provided.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"statusQuoSummary":{"type":"string","x-aicoo-source-type":"string"},"todoSummary":{"type":"string","x-aicoo-source-type":"string"},"calendarSummary":{"type":"string","x-aicoo-source-type":"string"},"notesSummary":{"type":"string","x-aicoo-source-type":"string"},"emailAttentionSummary":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"matrix":{"q1_urgent_important":[{"title":"Client deadline today","source":"email"}],"q2_not_urgent_important":[{"title":"Q2 hiring plan","source":"note"}],"q3_urgent_not_important":[{"title":"Reschedule vendor demo","source":"calendar"}],"q4_not_urgent_not_important":[]},"generatedAt":"2026-04-10T09:30:00.000Z"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/briefings":{"get":{"operationId":"briefings","summary":"Briefing History","description":"Returns stored briefing history rows for the authenticated user.\n\n- Ordered by generatedAt descending.\n- limit is capped at 50.\n- Returns id + summary + generated timestamp.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return (default 10, max 50).","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"briefings":[{"id":128,"statusQuoSummary":"<h3>Today's Focus</h3><ul><li>...</li></ul>","timeDuration":"last 24 hours","generatedAt":"2026-04-10T09:12:00.000Z"}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/notes/summary":{"get":{"operationId":"notes-summary","summary":"Notes Summary","description":"Returns recent notes plus a compact HTML summary block.\n\n- Includes relativeTime and pinned flags.\n- Sorted by most recently updated notes.\n- limit is capped at 20.","tags":["track:aicoo","group:aicoo-agent","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return (default 5, max 20).","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"notes":[{"id":42,"title":"Roadmap Decisions","summary":"Decided to ship onboarding improvements first...","updatedAt":"2026-04-10T08:22:00.000Z","relativeTime":"2 hours ago","pinned":true}],"notesSummary":"<ul><li><strong>Roadmap Decisions</strong> [pinned] <span>(2 hours ago)</span></li></ul>"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/agent"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os":{"get":{"operationId":"os-index","summary":"OS Endpoint Index","description":"Returns the discoverable Aicoo OS endpoint catalog grouped by category.\n\n- Best first call when generating SDKs or agent tool manifests.\n- Groups workspace, folders, notes, todos, network, snapshots, memory, and sharing endpoints.\n- Requires the same Bearer API key as every v1 route.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"description":"Aicoo OS - RESTful access to notes, folders, todos, memory, snapshots, network, and sharing.","totalEndpoints":29,"byCategory":{"workspace":[{"method":"GET","path":"/api/v1/os/status"}],"folders":[{"method":"GET","path":"/api/v1/os/folders"}],"notes":[{"method":"GET","path":"/api/v1/os/notes"}],"sharing":[{"method":"POST","path":"/api/v1/os/share"}]}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/accumulate":{"post":{"operationId":"accumulate","summary":"Accumulate Context","description":"Bulk writes files/texts and deletes files/folders.\n\n- At least one operation required: files/texts/delete/folders.\n- Max 50 create/update entries and 10MB per file.\n- Existing file edits auto-create note versions.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ path: string; content: string; message?: string }"},"x-aicoo-source-type":"Array<{ path: string; content: string; message?: string }>"},"texts":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ title: string; content: string; folder?: string }"},"x-aicoo-source-type":"Array<{ title: string; content: string; folder?: string }>"},"delete":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ path: string }"},"x-aicoo-source-type":"Array<{ path: string }>"},"folders":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ create?: string[]; delete?: string[] }"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"created":1,"updated":2,"deleted":0,"skipped":1,"errors":[],"versions":[{"file":"Research/plan.md","from":"v1","to":"v2","message":"Updated assumptions"}],"foldersCreated":["Research/2026"],"workspace":{"totalFiles":18,"totalSizeBytes":76214}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/status":{"get":{"operationId":"os-status","summary":"Workspace Status","description":"Returns current workspace health and footprint summary.\n\n- Includes contextCount and totalSizeBytes.\n- Includes folder tree with file counts.\n- Includes lastSyncedAt timestamp.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"contextCount":18,"totalSizeBytes":76214,"folders":[{"id":1,"name":"General","parentId":null,"icon":null,"fileCount":5}],"lastSyncedAt":"2026-04-10T09:22:18.000Z"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/folders":{"get":{"operationId":"os-folders-list","summary":"List Folders","description":"Lists all folders with metadata and counts.\n\n- Includes owned and readable shared folders.\n- Supports parentId filtering.\n- Returns id, name, parentId, fileCount, shared flag, and role.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"parentId","in":"query","required":false,"description":"Optional parent folder id filter.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"folders":[{"id":1,"name":"General","parentId":null,"icon":null,"fileCount":5,"createdAt":"2026-03-30T12:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"os-folders-create","summary":"Create Folder","description":"Creates a folder by name or creates a nested folder path.\n\n- Use { name } for a single folder segment.\n- Use { path: \"a/b\" } for nested folder creation.\n- Returns 200 if the folder or path already exists.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","x-aicoo-source-type":"string"},"path":{"type":"string","x-aicoo-source-type":"string"},"parentId":{"type":"number","nullable":true,"x-aicoo-source-type":"number | null"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"mode":"path","path":"SEAHack/Team Alpha","folder":{"id":17,"name":"Team Alpha","parentId":16},"createdSegments":["SEAHack","Team Alpha"],"message":"Created 2 folder(s)"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes":{"get":{"operationId":"os-notes-list","summary":"List Notes","description":"Lists note metadata in root or a selected folder.\n\n- Use folderId when you already know the folder.\n- Use folderName only when names are unambiguous.\n- Returns metadata only; use GET /api/v1/os/notes/{id} for full content.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"folderId","in":"query","required":false,"description":"Folder id to list. Omit for root notes.","schema":{"type":"number"}},{"name":"folderName","in":"query","required":false,"description":"Folder name lookup. Ambiguous names return 400.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50, max 200).","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"folder":{"id":17,"name":"Team Alpha"},"notes":[{"id":42,"title":"Project Brief","wordCount":386,"pinned":true,"tags":["hackathon"],"createdAt":"2026-04-10T08:22:00.000Z","updatedAt":"2026-04-10T09:22:00.000Z"}],"totalNotes":1,"limited":false}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"os-notes-create","summary":"Create Note","description":"Creates a note in root or a target folder the user can write to.\n\n- Requires title and content through the note tool payload.\n- Supports folderId when writing into a specific folder.\n- Returns 201 on success and 422 for tool-level validation errors.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","x-aicoo-source-type":"string"},"content":{"type":"string","x-aicoo-source-type":"string"},"folderId":{"type":"number","x-aicoo-source-type":"number"},"tags":{"type":"array","items":{"type":"string"},"x-aicoo-source-type":"string[]"}},"required":["title","content"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"result":{"note":{"id":42,"title":"Project Brief","folderId":17}}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/search":{"post":{"operationId":"os-notes-search","summary":"Search Notes","description":"Runs semantic note search across owned notes and readable shared folders.\n\n- Good for recall-style product features.\n- Includes shared folders where the user has read access.\n- Use grep when you need deterministic literal or regex matching.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","x-aicoo-source-type":"string"}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"results":[{"id":42,"title":"Project Brief","snippet":"Team Alpha is building..."}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/grep":{"post":{"operationId":"os-notes-grep","summary":"Grep Notes","description":"Runs deterministic grep-style matching with line context.\n\n- Supports literal and regex modes.\n- Can filter by folderId or folderName.\n- Useful for agents that need exact citation-style context.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pattern":{"type":"string","x-aicoo-source-type":"string"},"mode":{"type":"string","enum":["literal","regex"],"x-aicoo-source-type":"\"literal\" | \"regex\""},"contextBefore":{"type":"number","x-aicoo-source-type":"number"},"contextAfter":{"type":"number","x-aicoo-source-type":"number"},"folderId":{"type":"number","x-aicoo-source-type":"number"},"folderName":{"type":"string","x-aicoo-source-type":"string"}},"required":["pattern"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"results":[{"noteId":42,"title":"Project Brief","matches":[{"line":12,"text":"Track: Aicoo Track","match":"Aicoo Track"}]}],"summary":{"notesScanned":12,"notesMatched":1}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/todos":{"get":{"operationId":"os-todos-list","summary":"Search Todos","description":"Searches or lists todos through Aicoo OS.\n\n- Supports text, date, completion, priority, sorting, and pagination filters.\n- Can include workflow steps when includeSteps=true.\n- Returns tool result format with success=false for tool-level errors.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Keyword search.","schema":{"type":"string"}},{"name":"date","in":"query","required":false,"description":"Date filter such as today.","schema":{"type":"string"}},{"name":"completed","in":"query","required":false,"description":"Completion filter.","schema":{"type":"boolean"}},{"name":"priorityMin","in":"query","required":false,"description":"Minimum priority.","schema":{"type":"number"}},{"name":"limit","in":"query","required":false,"description":"Rows to return.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"result":{"todos":[{"id":9001,"title":"Submit demo video","completed":false,"priority":5}],"total":1}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"os-todos-create","summary":"Create Todo","description":"Creates a todo through Aicoo OS.\n\n- Requires title.\n- Supports description, dueDate, priority, and steps when provided.\n- Returns 201 on success and 422 for tool-level errors.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","x-aicoo-source-type":"string"},"description":{"type":"string","x-aicoo-source-type":"string"},"dueDate":{"type":"string","x-aicoo-source-type":"string"},"priority":{"type":"number","x-aicoo-source-type":"number"},"steps":{"type":"array","items":{"type":"object","x-aicoo-source-type":"{ title: string }"},"x-aicoo-source-type":"Array<{ title: string }>"}},"required":["title"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"result":{"todo":{"id":9001,"title":"Submit demo video","completed":false}}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools":{"get":{"operationId":"tools-discover","summary":"Discover Tools","description":"Lists all available tools with their input schemas.\n\n- Designed for external agent self-discovery.\n- Returns tool name + description + JSON-style parameters schema.\n- Companion endpoint to POST /api/v1/tools.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"tools":[{"name":"search_calendar_events","description":"Search calendar events within a time range.","namespace":"calendar","source":"native","readWrite":"read","parameters":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}],"totalTools":19,"usage":{"endpoint":"POST /api/v1/tools","body":"{ \"tool\": \"<tool_name>\", \"params\": { ... } }"},"osEndpoints":{"description":"Notes, folders, todos, memory, snapshots, network, and sharing are at /api/v1/os/","index":"GET /api/v1/os/"}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"tools-execute","summary":"Execute Tool","description":"Executes one tool by name with params.\n\n- 404 for unknown tools; 400 for malformed body.\n- 422 when tool returns isError=true.\n- Response includes executionTimeMs.\n- Use /api/v1/os/* endpoints below for notes, folders, todos, memory, snapshots, network, and sharing.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"string","x-aicoo-source-type":"string"},"params":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"object"}},"required":["tool"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"tool":"search_calendar_events","result":{"success":true,"events":[],"totalFound":0,"timeRange":{"timeMin":"2026-04-16T00:00:00.000Z","timeMax":"2026-04-17T00:00:00.000Z"}},"metadata":{"executionTimeMs":83}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/network/conversations":{"get":{"operationId":"os-network-conversations","summary":"List Guest Conversations","description":"Lists guest conversation sessions created through shared agent links.\n\n- Returns visitor identity fields when available.\n- Can filter by shareToken.\n- Includes last message preview for dashboards and review queues.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"shareToken","in":"query","required":false,"description":"Filter to one share link token.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 20).","schema":{"type":"number"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"conversations":[{"sessionId":"sess_123","shareToken":"f4c8...ab91","linkLabel":"SEAHack Team Alpha","guestName":"Mentor","lastRole":"assistant","lastContent":"The team still needs to finalize the demo script.","lastCreatedAt":"2026-04-10T10:12:00.000Z"}],"limit":20,"offset":0}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/policy":{"get":{"operationId":"heartbeat-policy-read","summary":"Get Heartbeat Policy","description":"Returns current heartbeat policy tier.\n\n- No request params required.\n- Policy is scoped to authenticated user.\n- Response shape: { success, policy }.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"policy":"ACTIONS"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"heartbeat-policy-update","summary":"Set Heartbeat Policy","description":"Sets policy tier to ACTIONS or MESSAGES.\n\n- Invalid tier returns 400.\n- Persists immediately.\n- Returns updated policy.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["ACTIONS","MESSAGES"],"x-aicoo-source-type":"\"ACTIONS\" | \"MESSAGES\""}},"required":["tier"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"policy":"MESSAGES"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/run":{"post":{"operationId":"heartbeat-run","summary":"Run Heartbeat","description":"Executes heartbeat immediately.\n\n- Optional tier override can be sent in body.\n- dryRun is accepted in request payload.\n- Response shape: { success, result }.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["ACTIONS","MESSAGES"],"x-aicoo-source-type":"\"ACTIONS\" | \"MESSAGES\""},"dryRun":{"type":"boolean","x-aicoo-source-type":"boolean"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"result":{"runId":123,"startedAt":"2026-04-10T10:10:00.000Z","completedAt":"2026-04-10T10:10:04.000Z","status":"completed","actionsCreated":3}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/runs":{"get":{"operationId":"heartbeat-runs","summary":"List Heartbeat Runs","description":"Lists recent heartbeat runs.\n\n- Sorted by startedAt descending.\n- limit defaults to 20 and maxes at 50.\n- Designed for polling dashboards.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Rows to return (default 20, max 50).","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"runs":[{"id":123,"policy":"MESSAGES","status":"completed","startedAt":"2026-04-10T10:10:00.000Z","completedAt":"2026-04-10T10:10:04.000Z"}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/runs/{id}":{"get":{"operationId":"heartbeat-run-detail","summary":"Heartbeat Run Detail","description":"Returns run metadata plus action rows.\n\n- Path id must be numeric.\n- Returns 404 for unknown/unowned run.\n- Response shape: { success, run, actions }.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Run id from list endpoint.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"run":{"id":123,"policy":"MESSAGES","status":"completed","startedAt":"2026-04-10T10:10:00.000Z","completedAt":"2026-04-10T10:10:04.000Z"},"actions":[{"id":9001,"runId":123,"type":"message_draft","status":"completed","createdAt":"2026-04-10T10:10:01.000Z"}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/{id}":{"get":{"operationId":"os-notes-get","summary":"Read Note","description":"Returns a single note with its full content.\n\n- Scope: os.notes:read.\n- Scoped to the authenticated user — another owner’s note is a 404, not a 403.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"patch":{"operationId":"os-notes-update","summary":"Update Note","description":"Edits a note’s title or content in place.\n\n- Scope: os.notes:write.\n- Partial update — omitted fields are left untouched.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","x-aicoo-source-type":"string"},"content":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/{id}/copy":{"post":{"operationId":"os-notes-copy","summary":"Copy Note","description":"Duplicates a note, optionally into a different folder (cp).\n\n- Scope: os.notes:write.\n- The copy is a new note — snapshots and share links are not carried over.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Note to copy.","schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"number","x-aicoo-source-type":"number"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/{id}/move":{"post":{"operationId":"os-notes-move","summary":"Move Note","description":"Moves a note into a different folder (mv).\n\n- Scope: os.notes:write.\n- The destination folder must be writable by the caller.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Note to move.","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folderId":{"type":"number","nullable":true,"x-aicoo-source-type":"number | null"}},"required":["folderId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/notes/{id}/pin":{"post":{"operationId":"os-notes-pin","summary":"Pin or Unpin Note","description":"Toggles a note’s pinned state.\n\n- Scope: os.notes:write.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pinned":{"type":"boolean","x-aicoo-source-type":"boolean"}},"required":["pinned"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/snapshots/{noteId}":{"get":{"operationId":"os-snapshots-list","summary":"List Note Snapshots","description":"Lists the version history captured for a note.\n\n- Scope: os.snapshots:read.\n- Take a snapshot before a large rewrite so the previous state stays restorable.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"},"post":{"operationId":"os-snapshots-create","summary":"Create Snapshot","description":"Captures the note’s current content as a restorable version.\n\n- Scope: os.snapshots:write.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/snapshots/{noteId}/seq/{seq}":{"get":{"operationId":"os-snapshots-get-seq","summary":"Read Snapshot by Sequence","description":"Retrieves one snapshot with its full content by sequence number.\n\n- Scope: os.snapshots:read.\n- Sequence numbers are stable per note and are the preferred addressing form.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}},{"name":"seq","in":"path","required":true,"description":"Snapshot sequence number.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/snapshots/{noteId}/{versionId}":{"get":{"operationId":"os-snapshots-get-legacy","summary":"Read Snapshot by Version Id","description":"Retrieves a legacy note_versions snapshot by its primary key.\n\n- Scope: os.snapshots:read.\n- Legacy addressing kept for older clients — prefer the /seq/{seq} form.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}},{"name":"versionId","in":"path","required":true,"description":"Legacy version primary key.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/snapshots/{noteId}/restore":{"post":{"operationId":"os-snapshots-restore","summary":"Restore Snapshot","description":"Restores a note to a previously captured version.\n\n- Scope: os.snapshots:write.\n- Restoring overwrites current content — snapshot first if it has unsaved value.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"noteId","in":"path","required":true,"description":"Note id.","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seq":{"type":"number","x-aicoo-source-type":"number"}},"required":["seq"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/todos/{id}":{"patch":{"operationId":"os-todos-update","summary":"Edit Todo","description":"Updates a todo’s fields.\n\n- Scope: os.todos:write.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Todo id.","schema":{"type":"number"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","x-aicoo-source-type":"string"},"dueDate":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/todos/{id}/complete":{"post":{"operationId":"os-todos-complete","summary":"Complete Todo","description":"Marks a todo as done.\n\n- Scope: os.todos:write.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Todo id.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/todos/replan":{"post":{"operationId":"os-todos-replan","summary":"Replan Overdue Todos","description":"Reschedules overdue todos into workable slots.\n\n- Scope: os.todos:write.\n- Intended for a daily agent pass rather than per-item edits.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/team":{"get":{"operationId":"os-team","summary":"Team Status","description":"Returns team membership and seat status for the authenticated user.\n\n- Scope: os.team:read.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/team/invite":{"post":{"operationId":"os-team-invite","summary":"Create Team Invite","description":"Creates a team invite link.\n\n- Scope: os.team:write.\n- Owner or admin only — a member seat cannot mint invites.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","x-aicoo-source-type":"string"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/network":{"get":{"operationId":"os-network","summary":"Network Overview","description":"Lists share links, visitors, and contacts in one view.\n\n- Scope: os.network:read.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/network/conversations/{sessionId}":{"get":{"operationId":"os-network-conversation","summary":"Read Guest Conversation","description":"Returns the transcript of one guest session on a share link.\n\n- Scope: os.network:read.\n- Only sessions belonging to the caller’s own links are readable.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Guest session id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/os/memory/search":{"post":{"operationId":"os-memory-search","summary":"Search Episodic Memory","description":"Semantic search across the agent’s episodic memory.\n\n- Scope: os.memory:read.\n- Read-only — this endpoint cannot write or forget memories.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","x-aicoo-source-type":"string"},"limit":{"type":"number","x-aicoo-source-type":"number"}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/status":{"get":{"operationId":"heartbeat-status","summary":"Heartbeat Status","description":"Current autonomy tier, last run, and today’s run count.\n\n- Scope: os.heartbeat:read.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/heartbeat/instructions":{"get":{"operationId":"heartbeat-instructions","summary":"Heartbeat Instructions","description":"Reads the HEARTBEAT.md checklist the autonomous pass follows.\n\n- Scope: os.heartbeat:read to read, os.heartbeat:run to replace it with PUT.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/identity":{"get":{"operationId":"identity","summary":"Identity","description":"Returns the identity behind the presented credential.\n\n- Useful as a credential smoke test before a longer flow.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/conversations":{"get":{"operationId":"conversations-list","summary":"List Conversations","description":"Lists the authenticated user’s chat conversations.\n\n","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum conversations to return.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/namespaces":{"get":{"operationId":"tools-namespaces","summary":"Tool Namespaces","description":"Lists tool namespaces and which are enabled for the credential.\n\n- PUT the same path to enable or disable namespaces.\n- A namespace that is off makes its tools uncallable via /v1/tools.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/integrations":{"get":{"operationId":"tools-integrations","summary":"List Integrations","description":"Lists connected third-party integrations.\n\n- DELETE /api/v1/tools/integrations/{id} disconnects one.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/integrations/{id}":{"delete":{"operationId":"tools-integrations-disconnect","summary":"Disconnect Integration","description":"Removes a connected third-party integration.\n\n- Its tools stop resolving immediately; reconnecting requires the provider OAuth flow again.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Integration id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/mcp":{"get":{"operationId":"tools-mcp-list","summary":"List MCP Servers","description":"Lists connected MCP servers; POST the same path to add one.\n\n- Each server contributes its tools into the tool registry once authorized.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/mcp/{id}":{"get":{"operationId":"tools-mcp-detail","summary":"MCP Server Detail","description":"Reads one MCP server; PATCH updates it and DELETE removes it.\n\n","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"MCP server id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/mcp/{id}/authorize":{"post":{"operationId":"tools-mcp-authorize","summary":"Authorize MCP Server","description":"Starts the OAuth authorization flow for an MCP server.\n\n- Returns the URL the user must visit — the API never handles their credentials.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"MCP server id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/mcp/{id}/refresh":{"post":{"operationId":"tools-mcp-refresh","summary":"Refresh MCP Tools","description":"Re-reads the server’s tool list after it changes.\n\n","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"MCP server id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/tools/mcp/{id}/disconnect":{"post":{"operationId":"tools-mcp-disconnect","summary":"Disconnect MCP Server","description":"Revokes the stored authorization for an MCP server.\n\n- The server stays configured; re-authorize to use it again.","tags":["track:aicoo","group:aicoo-os-tools","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"MCP server id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/layer"},"x-aicoo-track":"aicoo","x-aicoo-status":"ga"}},"/agent/message":{"post":{"operationId":"agent-message","summary":"Send Agent Message","description":"Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the \"to\" field.\n\n- Plain username (\"alice\") delivers to the human inbox — fire-and-forget, response is null.\n- \"username_coo\" (\"alice_coo\") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).\n- \"group:<id>\" (\"group:42\") posts into a group conversation you are an active member of.\n- Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.\n- Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted.","tags":["track:sharedos","group:a2a-messaging","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key. Retries with the same key return the cached response within a 5-minute window.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","x-aicoo-source-type":"string"},"message":{"type":"string","x-aicoo-source-type":"string"},"intent":{"type":"string","x-aicoo-source-type":"string"},"clientMessageId":{"type":"string","x-aicoo-source-type":"string"}},"required":["to","message"]}}}},"responses":{"200":{"description":"Successful response","content":{"text/plain":{"schema":{"type":"string"},"example":"// 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}"}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#a2a-messaging"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network":{"get":{"operationId":"network-overview","summary":"Network Overview","description":"Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.\n\n- shareLinks includes per-link capabilities plus visitor/session/message analytics.\n- contacts shows permission direction: mutual, inbound, or outbound.\n- Best first call for building a network dashboard or deciding who to hand work to.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"network":{"shareLinks":[{"token":"f4c8...ab91","label":"SEAHack Team Alpha","agentUrl":"https://www.aicoo.io/a/f4c8...ab91","capabilities":{"notes":"read","calendar":"none","email":false,"todos":true,"tools":[]},"expiresAt":"2026-04-17T09:30:00.000Z","createdAt":"2026-04-10T09:30:00.000Z","analytics":{"visitors":5,"sessions":8,"messages":42}}],"visitors":[{"sessionId":"sess_123","shareToken":"f4c8...ab91","linkLabel":"SEAHack Team Alpha","fingerprint":"a1b2c3d4","messages":6,"lastActiveAt":"2026-04-10T10:12:00.000Z"}],"contacts":[{"userId":"b3f1c9e1-...","name":"Bob Lee","username":"bob","direction":"mutual","theirPermissionsToYou":{"notes":"read","calendar":"free_busy"},"yourPermissionsToThem":{"notes":"read","calendar":"none"}}],"summary":{"totalLinks":1,"totalVisitors":1,"totalContacts":1}}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network/request":{"post":{"operationId":"network-request","summary":"Send Connection Request","description":"Sends a friend request (plain username) or an agent access request (\"username_coo\").\n\n- The _coo suffix convention matches /v1/agent/message routing.\n- Mutual pending friend requests auto-accept.\n- Returns 409 with already_connected or already_pending when the handshake already happened.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","x-aicoo-source-type":"string"}},"required":["to"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"type":"agent","status":"requested","to":"alice","recipientName":"Alice Chen","message":"Agent access request sent to Alice Chen. Waiting for them to accept and configure permissions."}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network/requests":{"get":{"operationId":"network-requests","summary":"List Pending Requests","description":"Lists pending friend and agent access requests, incoming and outgoing.\n\n- incoming items carry the requestId you pass to /v1/network/accept.\n- Friend and agent request types are merged, newest first.\n- Poll this (or check inbox monitoring) for handshakes awaiting your decision.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"incoming":[{"requestId":314,"type":"agent","from":{"userId":"b3f1c9e1-...","username":"bob","name":"Bob Lee","agentName":"Bob's COO"},"createdAt":"2026-04-10T09:12:00.000Z"}],"outgoing":[],"summary":{"incomingCount":1,"outgoingCount":0}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network/accept":{"post":{"operationId":"network-accept","summary":"Accept / Reject Request","description":"Accepts or rejects a pending friend or agent access request.\n\n- Only the recipient/target of the request can accept or reject.\n- Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.\n- Folder-scoped notes access validates folder ownership; unowned folder ids are rejected.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"number","x-aicoo-source-type":"number"},"type":{"type":"string","enum":["friend","agent"],"x-aicoo-source-type":"\"friend\" | \"agent\""},"action":{"type":"string","enum":["accept","reject"],"x-aicoo-source-type":"\"accept\" | \"reject\""},"permissions":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }"}},"required":["requestId","type","action"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"type":"agent","status":"accepted","from":"Bob Lee","permissions":{"notes":"read","calendar":"free_busy","email":"none","todos":"read","tools":[]},"message":"Agent access granted to Bob Lee. They can now contact your agent."}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network/connect":{"post":{"operationId":"network-connect","summary":"Connect via Share Token","description":"Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.\n\n- The link owner consented by sharing the link — no request/accept round trip.\n- Link capabilities become the default agent permissions.\n- After connecting, message their agent via \"username_coo\" on /v1/agent/message.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shareToken":{"type":"string","x-aicoo-source-type":"string"}},"required":["shareToken"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"owner":{"userId":"a7f2c9e1-...","username":"alice","name":"Alice Chen","agentName":"Alice's COO"},"friendCreated":true,"agentAccessCreated":true,"permissions":{"notes":"read","notesScope":"folders","calendar":"free_busy","calendarWrite":false,"email":"none","todos":"read","tools":[]},"linkLabel":"SEAHack Team Alpha","message":"Connected with Alice Chen! You can now message Alice's COO via \"alice_coo\"."}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/network/permissions/{username}":{"get":{"operationId":"network-permissions-read","summary":"Read Contact Permissions","description":"Reads the agent permissions you currently grant to a contact.\n\n- Grantor view: what this contact may do against your workspace.\n- Returns the full normalized permissions object.\n- 404 when no grant exists for this contact yet.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"username","in":"path","required":true,"description":"Contact username.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"contact":{"userId":"b3f1c9e1-...","username":"bob","name":"Bob Lee"},"permissions":{"notesAccess":{"scope":"folders","access":"read","folderIds":[17]},"calendarAccess":{"read":"free_busy","write":false},"emailAccess":{"read":false},"todoAccess":{"read":true,"write":false},"toolAccess":{"allowedTools":[]},"notifyOwner":true}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"},"put":{"operationId":"network-permissions-update","summary":"Update Contact Permissions","description":"Updates the agent permissions you grant to an existing contact.\n\n- Full permissions payload required; values are normalized fail-closed.\n- Folder-scoped notes access validates folder ownership.\n- Use this to tighten or expand specific capabilities without dropping the connection.","tags":["track:sharedos","group:network-handshake","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"username","in":"path","required":true,"description":"Contact username.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }"}},"required":["permissions"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"contact":{"userId":"b3f1c9e1-...","username":"bob","name":"Bob Lee"},"permissions":{"notes":"read","calendar":"none","email":"none","todos":"read","tools":[]},"message":"Permissions updated for bob."}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#network-handshake"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/messages":{"post":{"operationId":"net-messages-send","summary":"Send Agent Message (net alias)","description":"Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the \"to\" field.\n\n- D6 alias for /agent/message; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- Plain username (\"alice\") delivers to the human inbox — fire-and-forget, response is null.\n- \"username_coo\" (\"alice_coo\") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).\n- \"group:<id>\" (\"group:42\") posts into a group conversation you are an active member of.\n- Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.\n- Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key. Retries with the same key return the cached response within a 5-minute window.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","x-aicoo-source-type":"string"},"message":{"type":"string","x-aicoo-source-type":"string"},"intent":{"type":"string","x-aicoo-source-type":"string"},"clientMessageId":{"type":"string","x-aicoo-source-type":"string"}},"required":["to","message"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/contacts":{"get":{"operationId":"net-contacts-list","summary":"Network Overview (net alias)","description":"Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.\n\n- D6 alias for /network; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- shareLinks includes per-link capabilities plus visitor/session/message analytics.\n- contacts shows permission direction: mutual, inbound, or outbound.\n- Best first call for building a network dashboard or deciding who to hand work to.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/contacts/request":{"post":{"operationId":"net-contacts-request","summary":"Send Connection Request (net alias)","description":"Sends a friend request (plain username) or an agent access request (\"username_coo\").\n\n- D6 alias for /network/request; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- The _coo suffix convention matches /v1/agent/message routing.\n- Mutual pending friend requests auto-accept.\n- Returns 409 with already_connected or already_pending when the handshake already happened.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","x-aicoo-source-type":"string"}},"required":["to"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/contacts/requests":{"get":{"operationId":"net-contacts-requests","summary":"List Pending Requests (net alias)","description":"Lists pending friend and agent access requests, incoming and outgoing.\n\n- D6 alias for /network/requests; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- incoming items carry the requestId you pass to /v1/network/accept.\n- Friend and agent request types are merged, newest first.\n- Poll this (or check inbox monitoring) for handshakes awaiting your decision.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/contacts/accept":{"post":{"operationId":"net-contacts-accept","summary":"Accept / Reject Request (net alias)","description":"Accepts or rejects a pending friend or agent access request.\n\n- D6 alias for /network/accept; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- Only the recipient/target of the request can accept or reject.\n- Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.\n- Folder-scoped notes access validates folder ownership; unowned folder ids are rejected.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"number","x-aicoo-source-type":"number"},"type":{"type":"string","enum":["friend","agent"],"x-aicoo-source-type":"\"friend\" | \"agent\""},"action":{"type":"string","enum":["accept","reject"],"x-aicoo-source-type":"\"accept\" | \"reject\""},"permissions":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }"}},"required":["requestId","type","action"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/contacts/connect":{"post":{"operationId":"net-contacts-connect","summary":"Connect via Share Token (net alias)","description":"Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.\n\n- D6 alias for /network/connect; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- The link owner consented by sharing the link — no request/accept round trip.\n- Link capabilities become the default agent permissions.\n- After connecting, message their agent via \"username_coo\" on /v1/agent/message.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shareToken":{"type":"string","x-aicoo-source-type":"string"}},"required":["shareToken"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/permissions/{username}":{"get":{"operationId":"net-permissions-read","summary":"Read Contact Permissions (net alias)","description":"Reads the agent permissions you currently grant to a contact.\n\n- D6 alias for /network/permissions/{username}; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- Grantor view: what this contact may do against your workspace.\n- Returns the full normalized permissions object.\n- 404 when no grant exists for this contact yet.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"username","in":"path","required":true,"description":"Contact username.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"},"put":{"operationId":"net-permissions-update","summary":"Update Contact Permissions (net alias)","description":"Updates the agent permissions you grant to an existing contact.\n\n- D6 alias for /network/permissions/{username}; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- Full permissions payload required; values are normalized fail-closed.\n- Folder-scoped notes access validates folder ownership.\n- Use this to tighten or expand specific capabilities without dropping the connection.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"username","in":"path","required":true,"description":"Contact username.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"permissions":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }"}},"required":["permissions"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/escalations":{"get":{"operationId":"net-escalations-list","summary":"List Pending Escalations (net alias)","description":"Returns actions your agents have paused pending a human decision.\n\n- D6 alias for /escalations; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- GA — callable with API keys or OAuth tokens that grant net.escalations:decide.\n- Control-plane decisions are binary: continue or stop.\n- When oneTime is true, \"continue\" runs the agent once and grants no standing access; the answer is written to the conversation asynchronously. Otherwise \"continue\" writes a lasting permission.\n- Pair with the escalation.pending webhook event to avoid polling.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum pending escalations to return. Clamped between 1 and 100.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/net/escalations/{id}/decision":{"post":{"operationId":"net-escalations-decision","summary":"Decide Escalation (net alias)","description":"Resolves a pending escalation with a binary decision.\n\n- D6 alias for /escalations/{id}/decision; the legacy route remains supported.\n- The net.* OAuth scope family is registered but staged enforcement is not enabled by D6.\n- GA — callable with API keys or OAuth tokens that grant net.escalations:decide.\n- \"continue\" resumes the paused action; \"stop\" cancels it.\n- The \"effect\" field says which kind of continue occurred: answering_once, permission_granted, approved, or denied.\n- The decision is recorded on the escalation row and mirrored to the audit log.","tags":["track:sharedos","group:net-aliases","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Escalation id from GET /v1/escalations, for example esc_123.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["continue","stop"],"x-aicoo-source-type":"\"continue\" | \"stop\""},"note":{"type":"string","x-aicoo-source-type":"string"},"editedResponse":{"type":"string","x-aicoo-source-type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#net-aliases"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/os/share":{"post":{"operationId":"os-share-create","summary":"Create Share Link","description":"Creates a guest share link for your agent.\n\n- Creates a scoped Aicoo agent or note link.\n- scope=folders requires folderIds.\n- Returns link token, URL, capabilities, and expiry metadata.","tags":["track:sharedos","group:share-links","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["all","folders"],"x-aicoo-source-type":"\"all\" | \"folders\""},"access":{"type":"string","enum":["read","read_calendar","read_calendar_write"],"x-aicoo-source-type":"\"read\" | \"read_calendar\" | \"read_calendar_write\""},"label":{"type":"string","x-aicoo-source-type":"string"},"expiresIn":{"type":"string","enum":["1h","24h","7d","30d"],"x-aicoo-source-type":"\"1h\" | \"24h\" | \"7d\" | \"30d\""},"folderIds":{"type":"array","items":{"type":"number"},"x-aicoo-source-type":"number[]"},"notesAccess":{"type":"string","enum":["read","write","edit"],"x-aicoo-source-type":"\"read\" | \"write\" | \"edit\""},"identity":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }"},"todos":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"object"},"requireSignIn":{"type":"boolean","x-aicoo-source-type":"boolean"},"summaryNotifications":{"type":"boolean","x-aicoo-source-type":"boolean"}},"required":["scope","access"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"shareLink":{"id":"f7d6d8cc-7305-4385-a5c7-df7c30a4d377","token":"f4c8...ab91","url":"https://www.aicoo.io/a/f4c8...ab91","scope":"folders","access":"read","label":"SEAHack Team Alpha","requireSignIn":true,"summaryNotifications":false,"expiresAt":"2026-04-17T09:30:00.000Z","createdAt":"2026-04-10T09:30:00.000Z"},"capabilities":{"notes":{"access":"read","scope":"folders"},"todos":{"read":true,"write":false}}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#share-links"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/os/share/list":{"get":{"operationId":"os-share-list","summary":"List Share Links","description":"Lists links with activity analytics.\n\n- status filter: active | revoked | all.\n- limit max 50.\n- Per-link analytics: visitors, conversations, messages.","tags":["track:sharedos","group:share-links","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Link status filter. Default active.","schema":{"type":"string","enum":["active","revoked","all"]}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 20, max 50).","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"links":[{"id":"f7d6d8cc-7305-4385-a5c7-df7c30a4d377","url":"https://www.aicoo.io/shared/f4c8...ab91","agentUrl":"https://www.aicoo.io/a/f4c8...ab91","scope":"all","access":"read_calendar","notesAccess":"read","identity":{"loadCoo":true,"loadUser":true,"loadPolicy":true},"label":"Investor demo link","isActive":true,"expiresAt":"2026-04-17T09:30:00.000Z","createdAt":"2026-04-10T09:30:00.000Z","analytics":{"uniqueVisitors":5,"totalConversations":8,"totalMessages":42}}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#share-links"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/os/share/{linkId}":{"patch":{"operationId":"os-share-update","summary":"Update Share Link","description":"Partially updates link configuration fields.\n\n- Update scope/access/label/folderIds/expiresIn/notesAccess/identity.\n- Returns 404 for unknown or unowned link ID.\n- Scope and access values are fail-closed validated.","tags":["track:sharedos","group:share-links","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"description":"Share link id from create/list response.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["all","folders"],"x-aicoo-source-type":"\"all\" | \"folders\""},"access":{"type":"string","enum":["read","read_calendar","read_calendar_write"],"x-aicoo-source-type":"\"read\" | \"read_calendar\" | \"read_calendar_write\""},"label":{"type":"string","nullable":true,"x-aicoo-source-type":"string | null"},"folderIds":{"type":"array","items":{"type":"number"},"x-aicoo-source-type":"number[]"},"expiresIn":{"type":"string","enum":["1h","24h","7d","30d"],"x-aicoo-source-type":"\"1h\" | \"24h\" | \"7d\" | \"30d\""},"notesAccess":{"type":"string","enum":["read","write","edit"],"x-aicoo-source-type":"\"read\" | \"write\" | \"edit\""},"identity":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"shareLink":{"id":"f7d6d8cc-7305-4385-a5c7-df7c30a4d377","url":"https://www.aicoo.io/shared/f4c8...ab91","agentUrl":"https://www.aicoo.io/a/f4c8...ab91","scope":"folders","notesAccess":"read","identity":{"loadCoo":false,"loadUser":true,"loadPolicy":true},"label":"Investor demo link (updated)","isActive":true,"expiresAt":"2026-05-10T09:30:00.000Z","updatedAt":"2026-04-10T10:08:00.000Z"}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#share-links"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"},"delete":{"operationId":"os-share-revoke","summary":"Revoke Share Link","description":"Revokes a link by setting isActive=false.\n\n- Guest access is immediately disabled.\n- Returns 404 for unknown/unowned ids.\n- Revoked links still listable via status filter.","tags":["track:sharedos","group:share-links","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"linkId","in":"path","required":true,"description":"Share link id from create/list response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"message":"Share link revoked"}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#share-links"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/agents":{"post":{"operationId":"agents-create","summary":"Mint Managed Agent","description":"Provisions a cloud-hosted agent with its own handle and API key.\n\n- Preview — design partners only. Contract shape must match the Horace proposal.\n- The returned apiKey authenticates the managed agent on the v1 surface.\n- API keys are shown once at mint time and never returned by list calls.\n\n**Preview:** Available to design partners; the contract may change.","tags":["track:sharedos","group:managed-agents","status:preview"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","x-aicoo-source-type":"string"},"persona":{"type":"string","x-aicoo-source-type":"string"}},"required":["name","persona"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"agentId":"agt_7f2c9e1a","handle":"atlas_coo","apiKey":"aicoo_sk_agent_..."}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#managed-agents"},"x-aicoo-track":"sharedos","x-aicoo-status":"preview"},"get":{"operationId":"agents-list","summary":"List Managed Agents","description":"Lists managed agents minted under your account.\n\n- Preview — design partners only.\n- API keys are shown once at mint time and never returned here.\n\n**Preview:** Available to design partners; the contract may change.","tags":["track:sharedos","group:managed-agents","status:preview"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"agents":[{"agentId":"agt_7f2c9e1a","handle":"atlas_coo","name":"Atlas","createdAt":"2026-07-01T09:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#managed-agents"},"x-aicoo-track":"sharedos","x-aicoo-status":"preview"}},"/escalations":{"get":{"operationId":"escalations-list","summary":"List Pending Escalations","description":"Returns actions your agents have paused pending a human decision.\n\n- GA — callable with API keys or OAuth tokens that grant net.escalations:decide.\n- Control-plane decisions are binary: continue or stop.\n- When oneTime is true, \"continue\" runs the agent once and grants no standing access; the answer is written to the conversation asynchronously. Otherwise \"continue\" writes a lasting permission.\n- Pair with the escalation.pending webhook event to avoid polling.","tags":["track:sharedos","group:escalations","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum pending escalations to return. Clamped between 1 and 100.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"escalations":[{"id":"esc_123","status":"pending","guestHandle":"@vendor","conversationId":42,"messageId":77,"originalQuery":"Can you send the purchase confirmation?","sanitizedIntent":"Requests vendor purchase confirmation","queryCategory":"communication","requestedResources":["proactive_message"],"suggestedResponse":"I need owner approval before sending this.","relationshipCluster":"vendor","createdAt":"2026-08-01T08:41:00.000Z","expiresAt":"2026-08-02T08:41:00.000Z","permissionScope":"calendar.read","oneTime":true}]}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#escalations"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/escalations/{id}/decision":{"post":{"operationId":"escalations-decision","summary":"Decide Escalation","description":"Resolves a pending escalation with a binary decision.\n\n- GA — callable with API keys or OAuth tokens that grant net.escalations:decide.\n- \"continue\" resumes the paused action; \"stop\" cancels it.\n- The \"effect\" field says which kind of continue occurred: answering_once, permission_granted, approved, or denied.\n- The decision is recorded on the escalation row and mirrored to the audit log.","tags":["track:sharedos","group:escalations","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Escalation id from GET /v1/escalations, for example esc_123.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["continue","stop"],"x-aicoo-source-type":"\"continue\" | \"stop\""},"note":{"type":"string","x-aicoo-source-type":"string"},"editedResponse":{"type":"string","x-aicoo-source-type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"effect":"answering_once","escalation":{"id":"esc_123","status":"approved","decision":"continue","ownerDecision":"allow","resolvedAt":"2026-08-01T09:00:00.000Z","permissionScope":"calendar.read","oneTime":true}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#escalations"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/webhooks":{"post":{"operationId":"webhooks-subscribe","summary":"Subscribe to Events","description":"Subscribes an HTTPS endpoint to SharedOS events.\n\n- Planned — contract preview, not yet callable.\n- Events: escalation.pending, message.received, grant.revoked.\n- Deliveries will be signed; verify signatures before trusting payloads.\n\n**Planned:** Contract preview only; this operation is not yet callable.","tags":["track:sharedos","group:webhooks","status:planned"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","x-aicoo-source-type":"string"},"events":{"type":"array","items":{"type":"string"},"x-aicoo-source-type":"string[]"}},"required":["url","events"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true,"webhook":{"id":"wh_91ac","url":"https://example.com/hooks/aicoo","events":["escalation.pending","message.received"]}}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#webhooks"},"x-aicoo-track":"sharedos","x-aicoo-status":"planned"}},"/net/metering":{"get":{"operationId":"net-metering-report","summary":"Read Monthly Metering","description":"Returns active connected devices, local-task usage, Credit settlement, and plan limits.\n\n- Requires net.audit:read for OAuth callers.\n- A device is active when its local C2C bridge registers or heartbeats in the UTC month.\n- Connected bridges cost 0 Credits; local tasks are metered from runtime-reported model usage.\n\n**Preview:** Available to design partners; the contract may change.","tags":["track:sharedos","group:metering","status:preview"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"period","in":"query","required":false,"description":"UTC billing month; defaults to the current month.","schema":{"x-aicoo-source-type":"YYYY-MM"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#metering"},"x-aicoo-track":"sharedos","x-aicoo-status":"preview"},"post":{"operationId":"net-metering-simulate-invoice","summary":"Simulate Invoice","description":"Generates the deterministic C2C v1 Credit statement for a UTC month.\n\n- Simulation only: this never creates or mutates a Stripe invoice.\n- Uses the c2c-v1 2× provider-cost conversion table; unknown models fail closed.\n- Shows buyer charge, seller settlement, platform fee, and realized gross margin.\n\n**Preview:** Available to design partners; the contract may change.","tags":["track:sharedos","group:metering","status:preview"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"x-aicoo-source-type":"YYYY-MM"}},"required":["period"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#metering"},"x-aicoo-track":"sharedos","x-aicoo-status":"preview"}},"/raw-memory/devices":{"get":{"operationId":"raw-memory-devices-list","summary":"List Raw Memory Devices","description":"Lists the machines enrolled to capture encrypted session records.\n\n- Auth: signed-in session, or a user API key.\n- Returns metadata only — no capture content and no key material.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"},"post":{"operationId":"raw-memory-devices-enroll","summary":"Enroll Raw Memory Device","description":"Enrolls a machine and registers its public key for envelope encryption.\n\n- Auth: user API key.\n- The wrapping key never leaves the device — the server only ever stores wrapped record keys.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceName":{"type":"string","x-aicoo-source-type":"string"},"publicKey":{"type":"string","x-aicoo-source-type":"string"}},"required":["deviceName","publicKey"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/raw-memory/devices/{deviceId}":{"delete":{"operationId":"raw-memory-devices-revoke","summary":"Revoke Raw Memory Device","description":"Revokes a device so it can no longer reserve uploads.\n\n- Scoped to the caller — revoking another user’s device returns 404.\n- Already-stored records stay encrypted and readable by devices that still hold the key.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"deviceId","in":"path","required":true,"description":"Device to revoke.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/raw-memory/reservations":{"post":{"operationId":"raw-memory-reservations","summary":"Reserve Upload Slot","description":"Reserves a slot for one encrypted session record before uploading it.\n\n- Auth: user API key; the reservation is bound to the enrolled device.\n- Rate-limited and size-bounded — the object key is a random UUID, so slots are not guessable.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","x-aicoo-source-type":"string"},"sizeBytes":{"type":"number","x-aicoo-source-type":"number"}},"required":["deviceId","sizeBytes"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/raw-memory/uploads/{reservationId}":{"post":{"operationId":"raw-memory-uploads","summary":"Upload Encrypted Record","description":"Uploads the ciphertext and signed manifest for a reserved slot.\n\n- The payload is already AES-256-GCM encrypted client-side — the server cannot read it.\n- The manifest is device-signed and bound to the reservation owner, so a record cannot be filed under another user.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"reservationId","in":"path","required":true,"description":"Reservation returned by the reserve call.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"manifest":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"object"}},"required":["manifest"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/raw-memory/records/{recordId}/shred":{"post":{"operationId":"raw-memory-shred","summary":"Shred Record","description":"Crypto-shreds a record by destroying its wrapped key.\n\n- Irreversible: the ciphertext remains but becomes permanently undecryptable.\n- Writes a tombstone and an audit event; deleting your account shreds every active record the same way.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"recordId","in":"path","required":true,"description":"Record to shred.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["secret-remediation","user-deletion"],"x-aicoo-source-type":"\"secret-remediation\" | \"user-deletion\""}},"required":["reason"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/raw-memory/recovery":{"post":{"operationId":"raw-memory-recovery","summary":"Store Recovery Package","description":"Stores an opaque recovery blob so records survive losing every enrolled device.\n\n- The blob is encrypted client-side against the user’s recovery code — the server stores it without being able to open it.\n- Without this, losing all devices means the records can never be decrypted again.","tags":["track:sharedos","group:raw-memory","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"encryptedPackage":{"type":"string","x-aicoo-source-type":"string"}},"required":["encryptedPackage"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#raw-memory"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/endpoints":{"post":{"operationId":"local-agent-endpoints","summary":"Register Runtime Endpoint","description":"Registers (or re-registers) a local bridge as an addressable delivery endpoint and mints its device credential.\n\n- Auth: Aicoo user key or OAuth bearer. Every later bridge call uses the device token instead.\n- The device token (aicoo_dev_*) is returned exactly once — store it, it cannot be read back.\n- Re-registering the same device rotates the credential rather than creating a duplicate endpoint.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","x-aicoo-source-type":"string"},"runtime":{"type":"string","enum":["claude-code","codex","local-agent"],"x-aicoo-source-type":"\"claude-code\" | \"codex\" | \"local-agent\""},"capabilities":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"object"}},"required":["deviceId","runtime"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/grants":{"post":{"operationId":"local-agent-grants-create","summary":"Request Communication Grant","description":"Requests a short-lived, route-frozen grant to reach another principal’s local agent.\n\n- Precondition: an agent permission from the target to the requester must already exist — a grant cannot create access.\n- Message conveys intent, not authority: the requester never names a destination endpoint.\n- Pending until the recipient accepts; the route is frozen at accept time.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"object","additionalProperties":true,"x-aicoo-source-type":"{ kind: string, principalId: string }"},"requestedTtlMinutes":{"type":"number","x-aicoo-source-type":"number"}},"required":["target"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"},"get":{"operationId":"local-agent-grants-list","summary":"List Grants","description":"Lists the communication grants the caller participates in, as requester or recipient.\n\n- Returns flat rows; clients map them into their own nested shape.\n- Includes status and expiry so a bridge can drop grants that have lapsed.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/grants/{id}/accept":{"post":{"operationId":"local-agent-grants-accept","summary":"Accept Grant","description":"Recipient accepts a pending grant: resolves the default route, freezes endpoint + session, and sets a ≤30-minute expiry.\n\n- Freezing the route at accept time is what stops a later request from being redirected elsewhere.\n- Decline and revoke are available at the sibling /decline and /revoke paths.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Grant (communication session) id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/messages":{"post":{"operationId":"local-agent-messages-send","summary":"Send Grant-Scoped Message","description":"Sends a message inside an active grant. The destination comes from the frozen route.\n\n- The caller cannot specify a destination endpoint — it is derived from the grant.\n- Delivery state machine: queued → dispatched → device_acked → runtime_pending → runtime_acked.\n- Idempotent per clientMessageId, so a bridge retry cannot duplicate a message.\n- task_invite is capped by the caller’s remaining Credits, reserved atomically before dispatch.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commSessionId":{"type":"string","x-aicoo-source-type":"string"},"body":{"type":"string","x-aicoo-source-type":"string"},"clientMessageId":{"type":"string","x-aicoo-source-type":"string"}},"required":["commSessionId","body"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/messages/{id}/ack":{"post":{"operationId":"local-agent-messages-ack","summary":"Acknowledge Delivery","description":"Bridge advances the delivery state machine for a dispatched message.\n\n- Auth: device token. Only the owning device may ack — this is what makes runtime_ack unspoofable.\n- Used for both device_acked and runtime_acked transitions.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery id being acknowledged.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phase":{"type":"string","enum":["device_ack","runtime_ack"],"x-aicoo-source-type":"\"device_ack\" | \"runtime_ack\""}},"required":["phase"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/sessions":{"post":{"operationId":"local-agent-sessions","summary":"Register Managed Session","description":"Registers an opaque handle for a live runtime session so grants can target it.\n\n- Auth: device token.\n- The provider-native session id is never uploaded — only the opaque handle.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","x-aicoo-source-type":"string"}},"required":["handle"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/tool-approvals":{"post":{"operationId":"local-agent-tool-approvals","summary":"Request Tool Approval","description":"Bridge registers a tool call for owner approval before the local runtime is allowed to execute it.\n\n- Auth: device token. Called from the runtime’s canUseTool hook.\n- A matching policy auto-allows; otherwise the call stays pending until the owner decides.\n- This is the per-tool-call gate: a grant lets someone ask, it does not let them run tools.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commSessionId":{"type":"string","x-aicoo-source-type":"string"},"toolName":{"type":"string","x-aicoo-source-type":"string"},"toolInputSummary":{"type":"string","x-aicoo-source-type":"string"}},"required":["commSessionId","toolName","toolInputSummary"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/tool-approvals/{id}/resolve":{"post":{"operationId":"local-agent-tool-approvals-resolve","summary":"Resolve Tool Approval","description":"Owner allows or denies a pending tool call from their phone or the web UI.\n\n- Auth: user key — only the owner may decide, and only for their own pending approvals.\n- The decision is pushed back to the originating bridge as tool.approval_decision.\n- Already-resolved and expired approvals are rejected rather than silently re-decided.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Approval id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["allow","deny"],"x-aicoo-source-type":"\"allow\" | \"deny\""}},"required":["decision"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-realtime/stream":{"get":{"operationId":"local-realtime-stream","summary":"Realtime Event Stream (SSE)","description":"Long-lived SSE channel a bridge holds open to receive dispatches and decisions.\n\n- Auth: device token.\n- Durable replay from cursor, then live wake — reconnecting with the last cursor is lossless.\n- The connection recycles roughly every 55s with jitter; reconnect with your cursor.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"endpointId","in":"query","required":true,"description":"Endpoint to stream events for.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Last seq seen; events after it are replayed on connect.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-realtime/poll":{"get":{"operationId":"local-realtime-poll","summary":"Realtime Poll Fallback","description":"Cursor-based polling for bridges that cannot hold an SSE connection.\n\n- Auth: device token. Same cursor semantics as the stream endpoint.\n- Use when a proxy or network blocks long-lived connections.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"endpointId","in":"query","required":true,"description":"Endpoint to poll.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Last seq seen.","schema":{"type":"number"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/device-code/start":{"post":{"operationId":"local-agent-device-code-start","summary":"Start Device-Code Login","description":"Begins browser-free pairing for a bridge that has no API key yet.\n\n- Unauthenticated by design — the bridge has no credential at this point.\n- Returns a short user code the owner approves in the web UI, plus a poll token held only by the bridge.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","x-aicoo-source-type":"string"},"runtime":{"type":"string","x-aicoo-source-type":"string"}},"required":["deviceId","runtime"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/device-code/poll":{"post":{"operationId":"local-agent-device-code-poll","summary":"Poll Device-Code Approval","description":"Polls until the owner approves, then returns the credential once.\n\n- Authorized by possession of the poll token, not a session.\n- The credential is returned encrypted and the pairing row is consumed after a single successful read.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pollToken":{"type":"string","x-aicoo-source-type":"string"}},"required":["pollToken"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/whoami":{"get":{"operationId":"local-agent-whoami","summary":"Whoami","description":"Returns the principal behind the presented device token or user credential.\n\n- Cheap way for a bridge to confirm its token is still valid.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/pair-status":{"get":{"operationId":"local-agent-pair-status","summary":"Pair Status","description":"Reports whether the caller has a reachable local runtime paired.\n\n- A default route that is offline does not count as reachable.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/resolve-person":{"get":{"operationId":"local-agent-resolve-person","summary":"Resolve Person","description":"Resolves a handle or username to a principal a grant can target.\n\n- Only returns people the caller is already connected to.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"handle","in":"query","required":true,"description":"Username or handle to resolve.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/default-route":{"get":{"operationId":"local-agent-default-route","summary":"Default Route","description":"Reads the endpoint that inbound grants resolve to; PUT sets it, DELETE clears it.\n\n- Auth: device token.\n- Accepting a grant freezes whatever this points at, so later changes do not redirect an active grant.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/endpoints/{id}/heartbeat":{"post":{"operationId":"local-agent-endpoint-heartbeat","summary":"Endpoint Heartbeat","description":"Keeps an endpoint marked online.\n\n- Auth: device token.\n- Missing heartbeats flip presence to offline, which removes it from routing.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/endpoints/{id}":{"delete":{"operationId":"local-agent-endpoint-revoke","summary":"Revoke Endpoint","description":"Revokes an endpoint and clears any default route pointing at it.\n\n- Auth: device token or user credential.\n- A revoked endpoint stops being a delivery target immediately.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Endpoint id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/grants/{id}/decline":{"post":{"operationId":"local-agent-grants-decline","summary":"Decline Grant","description":"Recipient declines a pending grant request.\n\n","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Grant id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/grants/{id}/revoke":{"post":{"operationId":"local-agent-grants-revoke","summary":"Revoke Grant","description":"Either party ends an active grant early.\n\n- Revoking stops further delivery immediately rather than waiting for the 30-minute expiry.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Grant id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/messages/{id}":{"get":{"operationId":"local-agent-message-status","summary":"Message Delivery Status","description":"Returns the delivery state machine and per-attempt history for a message.\n\n- Use this to tell \"not delivered yet\" apart from \"the runtime rejected it\".","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Message id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/messages/{id}/reply":{"post":{"operationId":"local-agent-message-reply","summary":"Reply to Message","description":"Bridge returns the runtime’s answer along the same grant.\n\n- Auth: device token.\n- The reply travels the reverse of the frozen route — the bridge cannot redirect it elsewhere.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Message being replied to.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","x-aicoo-source-type":"string"}},"required":["body"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/sessions/{handle}":{"patch":{"operationId":"local-agent-session-update","summary":"Update Managed Session","description":"Syncs bridge-side session state for an existing handle.\n\n- Auth: device token.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"handle","in":"path","required":true,"description":"Opaque session handle.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/tool-approvals/{id}":{"get":{"operationId":"local-agent-tool-approval-get","summary":"Read Tool Approval","description":"Reads one approval and its current decision.\n\n- Visible to the owner and the requesting bridge only.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Approval id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}},"/local-agent/injections/validate":{"post":{"operationId":"local-agent-injections-validate","summary":"Validate Injection","description":"Fail-closed check the bridge runs before injecting a message into the local runtime.\n\n- Auth: device token.\n- Rejects anything whose grant has expired or been revoked — the last gate before untrusted text reaches a runtime.","tags":["track:sharedos","group:runtime-sessions","status:ga"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commSessionId":{"type":"string","x-aicoo-source-type":"string"}},"required":["commSessionId"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"success":true}}}},"401":{"description":"Missing or invalid Bearer credential"},"403":{"description":"The credential does not grant the required access"},"429":{"description":"Rate limit exceeded"}},"externalDocs":{"url":"https://www.aicoo.io/docs/api/sharedos#runtime-sessions"},"x-aicoo-track":"sharedos","x-aicoo-status":"ga"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Aicoo API key or Login with Aicoo OAuth access token."}}}}