Aicoo API

Layer 3: Aicoo OS + Tools

This layer handles persistent workspace state, notes, folders, todos, guest conversations, heartbeat automation, and tool execution.

Build on AicooOverview 1. Intro + API Key 2. Aicoo Agent 3. Aicoo OS + Tools 4. OAuth / OIDC

Build on SharedOSAgent Network API

ReferenceAPI Status OpenAPI 3.0 JSON

Layer Scope

Coordination, state, and execution

Aicoo OS is the operational surface around the core agent: workspace status, folders, notes, todos, conversations, and heartbeat runs.

Use it to sync product context, read back outcomes, and run predictable background coordination tasks.

It also exposes a tool bridge so external clients can discover and execute available Aicoo tools safely.

Bridges Both Tracks

Share links are documented under Build on SharedOS

The /v1/os/share endpoints are part of the workspace surface, but they double as the handshake entry point for network connections (/v1/network/connect), so their reference now lives in the SharedOS track.

Open Share Links reference

Tools First

How to use Aicoo tools in practice

1. Call GET /api/v1/tools to fetch names and parameter schemas.

2. Pick one tool and validate your params against the schema.

3. Call POST /api/v1/tools with tool and params.

4. Handle 422 responses as tool-level execution errors and display message details to users.

Tool Catalog

Tools are discovered via `GET /api/v1/tools` and executed via `POST /api/v1/tools`.

calendar

Calendar operations (availability lookup, event create/edit, meeting scheduling).

search_calendar_events

Search events by query, time range, or availability mode.

create_calendar_event

Create a calendar event with title, time, location, and details.

edit_calendar_event

Update an existing event by id or search query.

schedule_meeting

Schedule a meeting with attendees and optional Google Meet.

extract_calendar_event_details

Parse natural language into structured calendar event fields.

email

Email operations (search, read, draft, send).

search_emails

Search inbox using Aicoo ranking and filters.

get_email_content

Retrieve full content by email or thread id.

search_contact

Resolve contact emails by name.

save_email_draft

Save an email draft for review.

send_email

Send one email now.

send_multiple_emails

Batch send personalized emails to multiple recipients.

web

Web search and content extraction.

web_search

Search the web with recency and domain controls.

web_extract_content

Extract content from one or more URLs.

read_url

Read clean page content from a URL.

messaging

In-app network and messaging operations.

search_pulse_contact

Find contacts in the Aicoo network.

send_message_to_human

Send in-app message to a human user.

quality

Content refinement and anti-duplication checks.

refine_content

Rewrite content to target style and constraints.

verify_uniqueness

Check overlap against recent history.

fetch_recent_history

Retrieve recent outputs for consistency checks.

Jump to tools endpoints

Tools Endpoints

Discovery and execution API

GET/api/v1/toolsGA

Discover Tools

Lists all available tools with their input schemas.

Designed for external agent self-discovery.
Returns tool name + description + JSON-style parameters schema.
Companion endpoint to POST /api/v1/tools.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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/"
  }
}

POST/api/v1/toolsGA

Execute Tool

Executes one tool by name with params.

404 for unknown tools; 400 for malformed body.
422 when tool returns isError=true.
Response includes executionTimeMs.
Use /api/v1/os/* endpoints below for notes, folders, todos, memory, snapshots, network, and sharing.

Parameters

Name	In	Type	Required
`tool` Tool name from GET /api/v1/tools.	body	string	Yes
`params` Tool-specific params object.	body	object	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"search_calendar_events","params":{"query":"standup","timeRange":"today"}}'

Example Output

{
  "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 }
}

OS Endpoints

Workspace, conversations, and heartbeat API

GET/api/v1/osGA

OS Endpoint Index

Returns the discoverable Aicoo OS endpoint catalog grouped by category.

Best first call when generating SDKs or agent tool manifests.
Groups workspace, folders, notes, todos, network, snapshots, memory, and sharing endpoints.
Requires the same Bearer API key as every v1 route.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/os \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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" }]
  }
}

POST/api/v1/initGA

Initialize Workspace

Bootstraps baseline workspace state idempotently.

Ensures /General folder exists.
Returns folder tree + total files + total size.
Recommended first call for context clients.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X POST https://www.aicoo.io/api/v1/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example Output

{
  "success": true,
  "initialized": true,
  "workspace": {
    "folders": [
      { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 3 }
    ],
    "totalFiles": 3,
    "totalSizeBytes": 24576
  }
}

POST/api/v1/accumulateGA

Accumulate Context

Bulk writes files/texts and deletes files/folders.

At least one operation required: files/texts/delete/folders.
Max 50 create/update entries and 10MB per file.
Existing file edits auto-create note versions.

Parameters

Name	In	Type	Required
`files` File upserts by path.	body	Array<{ path: string; content: string; message?: string }>	No
`texts` Text note upserts.	body	Array<{ title: string; content: string; folder?: string }>	No
`delete` File delete operations.	body	Array<{ path: string }>	No
`folders` Folder create/delete path list.	body	{ create?: string[]; delete?: string[] }	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/accumulate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{"path":"Research/plan.md","content":"# Plan"}],
    "folders": {"create":["Research/2026"]}
  }'

Example Output

{
  "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 }
}

GET/api/v1/os/statusGA

Workspace Status

Returns current workspace health and footprint summary.

Includes contextCount and totalSizeBytes.
Includes folder tree with file counts.
Includes lastSyncedAt timestamp.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/os/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "contextCount": 18,
  "totalSizeBytes": 76214,
  "folders": [
    { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 5 }
  ],
  "lastSyncedAt": "2026-04-10T09:22:18.000Z"
}

GET/api/v1/os/foldersGA

List Folders

Lists all folders with metadata and counts.

Includes owned and readable shared folders.
Supports parentId filtering.
Returns id, name, parentId, fileCount, shared flag, and role.

Parameters

Name	In	Type	Required
`parentId` Optional parent folder id filter.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/folders?parentId=17" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "folders": [
    {
      "id": 1,
      "name": "General",
      "parentId": null,
      "icon": null,
      "fileCount": 5,
      "createdAt": "2026-03-30T12:00:00.000Z"
    }
  ]
}

POST/api/v1/os/foldersGA

Create Folder

Creates a folder by name or creates a nested folder path.

Use { name } for a single folder segment.
Use { path: "a/b" } for nested folder creation.
Returns 200 if the folder or path already exists.

Parameters

Name	In	Type	Required
`name` Single folder segment. Use either name or path, not both.	body	string	No
`path` Nested path such as "SEAHack/Team Alpha". Use either name or path, not both.	body	string	No
`parentId` Parent folder id; omit for root.	body	number \| null	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"SEAHack/Team Alpha","parentId":null}'

Example Output

{
  "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)"
}

GET/api/v1/os/notesGA

List Notes

Lists note metadata in root or a selected folder.

Use folderId when you already know the folder.
Use folderName only when names are unambiguous.
Returns metadata only; use GET /api/v1/os/notes/{id} for full content.

Parameters

Name	In	Type	Required
`folderId` Folder id to list. Omit for root notes.	query	number	No
`folderName` Folder name lookup. Ambiguous names return 400.	query	string	No
`limit` Rows to return (default 50, max 200).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/notes?folderId=17&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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
}

POST/api/v1/os/notesGA

Create Note

Creates a note in root or a target folder the user can write to.

Requires title and content through the note tool payload.
Supports folderId when writing into a specific folder.
Returns 201 on success and 422 for tool-level validation errors.

Parameters

Name	In	Type	Required
`title` Note title.	body	string	Yes
`content` Markdown or plain text note content.	body	string	Yes
`folderId` Target folder id.	body	number	No
`tags` Optional tag list.	body	string[]	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Brief",
    "content": "Team Alpha is building on top of Aicoo.",
    "folderId": 17,
    "tags": ["hackathon"]
  }'

Example Output

{
  "success": true,
  "result": {
    "note": {
      "id": 42,
      "title": "Project Brief",
      "folderId": 17
    }
  }
}

POST/api/v1/os/notes/searchGA

Search Notes

Runs semantic note search across owned notes and readable shared folders.

Good for recall-style product features.
Includes shared folders where the user has read access.
Use grep when you need deterministic literal or regex matching.

Parameters

Name	In	Type	Required
`query` Search query.	body	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Aicoo Track submission requirements"}'

Example Output

{
  "success": true,
  "results": [
    { "id": 42, "title": "Project Brief", "snippet": "Team Alpha is building..." }
  ]
}

POST/api/v1/os/notes/grepGA

Grep Notes

Runs deterministic grep-style matching with line context.

Supports literal and regex modes.
Can filter by folderId or folderName.
Useful for agents that need exact citation-style context.

Parameters

Name	In	Type	Required
`pattern` Literal string or regex pattern.	body	string	Yes
`mode` Search mode. Defaults to literal.	body	"literal" \| "regex"	No
`contextBefore` Lines before each match.	body	number	No
`contextAfter` Lines after each match.	body	number	No
`folderId` Optional folder id filter.	body	number	No
`folderName` Optional folder name filter.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/grep \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern":"Aicoo Track","mode":"literal","contextBefore":1,"contextAfter":2}'

Example Output

{
  "success": true,
  "results": [
    {
      "noteId": 42,
      "title": "Project Brief",
      "matches": [
        { "line": 12, "text": "Track: Aicoo Track", "match": "Aicoo Track" }
      ]
    }
  ],
  "summary": { "notesScanned": 12, "notesMatched": 1 }
}

GET/api/v1/os/todosGA

Search Todos

Searches or lists todos through Aicoo OS.

Supports text, date, completion, priority, sorting, and pagination filters.
Can include workflow steps when includeSteps=true.
Returns tool result format with success=false for tool-level errors.

Parameters

Name	In	Type	Required
`q` Keyword search.	query	string	No
`date` Date filter such as today.	query	string	No
`completed` Completion filter.	query	boolean	No
`priorityMin` Minimum priority.	query	number	No
`limit` Rows to return.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/todos?q=demo&completed=false&priorityMin=3&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "result": {
    "todos": [
      { "id": 9001, "title": "Submit demo video", "completed": false, "priority": 5 }
    ],
    "total": 1
  }
}

POST/api/v1/os/todosGA

Create Todo

Creates a todo through Aicoo OS.

Requires title.
Supports description, dueDate, priority, and steps when provided.
Returns 201 on success and 422 for tool-level errors.

Parameters

Name	In	Type	Required
`title` Todo title.	body	string	Yes
`description` Todo details.	body	string	No
`dueDate` Optional due date.	body	string	No
`priority` Optional priority value.	body	number	No
`steps` Optional workflow steps.	body	Array<{ title: string }>	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Submit demo video","description":"Due before final judging","priority":5}'

Example Output

{
  "success": true,
  "result": {
    "todo": { "id": 9001, "title": "Submit demo video", "completed": false }
  }
}

GET/api/v1/os/network/conversationsGA

List Guest Conversations

Lists guest conversation sessions created through shared agent links.

Returns visitor identity fields when available.
Can filter by shareToken.
Includes last message preview for dashboards and review queues.

Parameters

Name	In	Type	Required
`shareToken` Filter to one share link token.	query	string	No
`limit` Rows to return (default 20).	query	number	No
`offset` Pagination offset.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/network/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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
}

GET/api/v1/heartbeat/policyGA

Get Heartbeat Policy

Returns current heartbeat policy tier.

No request params required.
Policy is scoped to authenticated user.
Response shape: { success, policy }.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/heartbeat/policy \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "policy": "ACTIONS"
}

POST/api/v1/heartbeat/policyGA

Set Heartbeat Policy

Sets policy tier to ACTIONS or MESSAGES.

Invalid tier returns 400.
Persists immediately.
Returns updated policy.

Parameters

Name	In	Type	Required
`tier` Target policy tier.	body	"ACTIONS" \| "MESSAGES"	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/heartbeat/policy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier":"ACTIONS"}'

Example Output

{
  "success": true,
  "policy": "MESSAGES"
}

POST/api/v1/heartbeat/runGA

Run Heartbeat

Executes heartbeat immediately.

Optional tier override can be sent in body.
dryRun is accepted in request payload.
Response shape: { success, result }.

Parameters

Name	In	Type	Required
`tier` Optional policy override before execution.	body	"ACTIONS" \| "MESSAGES"	No
`dryRun` Optional dry-run flag.	body	boolean	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/heartbeat/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier":"MESSAGES"}'

Example Output

{
  "success": true,
  "result": {
    "runId": 123,
    "startedAt": "2026-04-10T10:10:00.000Z",
    "completedAt": "2026-04-10T10:10:04.000Z",
    "status": "completed",
    "actionsCreated": 3
  }
}

GET/api/v1/heartbeat/runsGA

List Heartbeat Runs

Lists recent heartbeat runs.

Sorted by startedAt descending.
limit defaults to 20 and maxes at 50.
Designed for polling dashboards.

Parameters

Name	In	Type	Required
`limit` Rows to return (default 20, max 50).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/heartbeat/runs?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "runs": [
    {
      "id": 123,
      "policy": "MESSAGES",
      "status": "completed",
      "startedAt": "2026-04-10T10:10:00.000Z",
      "completedAt": "2026-04-10T10:10:04.000Z"
    }
  ]
}

GET/api/v1/heartbeat/runs/{id}GA

Heartbeat Run Detail

Returns run metadata plus action rows.

Path id must be numeric.
Returns 404 for unknown/unowned run.
Response shape: { success, run, actions }.

Parameters

Name	In	Type	Required
`id` Run id from list endpoint.	path	number	Yes

Request Example

curl -X GET https://www.aicoo.io/api/v1/heartbeat/runs/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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"
    }
  ]
}

GET/api/v1/os/notes/{id}GA

Read Note

Returns a single note with its full content.

Scope: os.notes:read.
Scoped to the authenticated user — another owner’s note is a 404, not a 403.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/notes/482 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

PATCH/api/v1/os/notes/{id}GA

Update Note

Edits a note’s title or content in place.

Scope: os.notes:write.
Partial update — omitted fields are left untouched.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes
`title` New title.	body	string	No
`content` New HTML content.	body	string	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/notes/482 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q3 planning"}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/copyGA

Copy Note

Duplicates a note, optionally into a different folder (cp).

Scope: os.notes:write.
The copy is a new note — snapshots and share links are not carried over.

Parameters

Name	In	Type	Required
`id` Note to copy.	path	number	Yes
`folderId` Destination folder; defaults to the source folder.	body	number	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/copy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":91}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/moveGA

Move Note

Moves a note into a different folder (mv).

Scope: os.notes:write.
The destination folder must be writable by the caller.

Parameters

Name	In	Type	Required
`id` Note to move.	path	number	Yes
`folderId` Destination folder; null moves to the root space.	body	number \| null	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":91}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/pinGA

Pin or Unpin Note

Toggles a note’s pinned state.

Scope: os.notes:write.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes
`pinned` Desired pinned state.	body	boolean	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/pin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned":true}'

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}GA

List Note Snapshots

Lists the version history captured for a note.

Scope: os.snapshots:read.
Take a snapshot before a large rewrite so the previous state stays restorable.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/snapshots/{noteId}GA

Create Snapshot

Captures the note’s current content as a restorable version.

Scope: os.snapshots:write.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`label` Human-readable marker for this version.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"before rewrite"}'

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}/seq/{seq}GA

Read Snapshot by Sequence

Retrieves one snapshot with its full content by sequence number.

Scope: os.snapshots:read.
Sequence numbers are stable per note and are the preferred addressing form.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`seq` Snapshot sequence number.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482/seq/7 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}/{versionId}GA

Read Snapshot by Version Id

Retrieves a legacy note_versions snapshot by its primary key.

Scope: os.snapshots:read.
Legacy addressing kept for older clients — prefer the /seq/{seq} form.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`versionId` Legacy version primary key.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482/1180 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/snapshots/{noteId}/restoreGA

Restore Snapshot

Restores a note to a previously captured version.

Scope: os.snapshots:write.
Restoring overwrites current content — snapshot first if it has unsaved value.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`seq` Snapshot sequence to restore.	body	number	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seq":7}'

Example Output

{
  "success": true
}

PATCH/api/v1/os/todos/{id}GA

Edit Todo

Updates a todo’s fields.

Scope: os.todos:write.

Parameters

Name	In	Type	Required
`id` Todo id.	path	number	Yes
`title` New title.	body	string	No
`dueDate` ISO due date.	body	string	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/todos/55 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dueDate":"2026-08-10"}'

Example Output

{
  "success": true
}

POST/api/v1/os/todos/{id}/completeGA

Complete Todo

Marks a todo as done.

Scope: os.todos:write.

Parameters

Name	In	Type	Required
`id` Todo id.	path	number	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos/55/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/todos/replanGA

Replan Overdue Todos

Reschedules overdue todos into workable slots.

Scope: os.todos:write.
Intended for a daily agent pass rather than per-item edits.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos/replan \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/teamGA

Team Status

Returns team membership and seat status for the authenticated user.

Scope: os.team:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/os/team \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/team/inviteGA

Create Team Invite

Creates a team invite link.

Scope: os.team:write.
Owner or admin only — a member seat cannot mint invites.

Parameters

Name	In	Type	Required
`email` Optional address to bind the invite to.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/team/invite \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"teammate@example.com"}'

Example Output

{
  "success": true
}

GET/api/v1/os/networkGA

Network Overview

Lists share links, visitors, and contacts in one view.

Scope: os.network:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/os/network \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/network/conversations/{sessionId}GA

Read Guest Conversation

Returns the transcript of one guest session on a share link.

Scope: os.network:read.
Only sessions belonging to the caller’s own links are readable.

Parameters

Name	In	Type	Required
`sessionId` Guest session id.	path	string	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/network/conversations/gs_41ab \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/memory/searchGA

Search Episodic Memory

Semantic search across the agent’s episodic memory.

Scope: os.memory:read.
Read-only — this endpoint cannot write or forget memories.

Parameters

Name	In	Type	Required
`query` Natural-language query.	body	string	Yes
`limit` Maximum results.	body	number	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"pricing decisions","limit":5}'

Example Output

{
  "success": true
}

GET/api/v1/heartbeat/statusGA

Heartbeat Status

Current autonomy tier, last run, and today’s run count.

Scope: os.heartbeat:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/heartbeat/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/heartbeat/instructionsGA

Heartbeat Instructions

Reads the HEARTBEAT.md checklist the autonomous pass follows.

Scope: os.heartbeat:read to read, os.heartbeat:run to replace it with PUT.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/heartbeat/instructions \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/identityGA

Identity

Returns the identity behind the presented credential.

Useful as a credential smoke test before a longer flow.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/identity \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/conversationsGA

List Conversations

Lists the authenticated user’s chat conversations.

Parameters

Name	In	Type	Required
`limit` Maximum conversations to return.	query	number	No

Request Example

curl "https://www.aicoo.io/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/namespacesGA

Tool Namespaces

Lists tool namespaces and which are enabled for the credential.

PUT the same path to enable or disable namespaces.
A namespace that is off makes its tools uncallable via /v1/tools.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/namespaces \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/integrationsGA

List Integrations

Lists connected third-party integrations.

DELETE /api/v1/tools/integrations/{id} disconnects one.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

DELETE/api/v1/tools/integrations/{id}GA

Disconnect Integration

Removes a connected third-party integration.

Its tools stop resolving immediately; reconnecting requires the provider OAuth flow again.

Parameters

Name	In	Type	Required
`id` Integration id.	path	string	Yes

Request Example

curl -X DELETE https://www.aicoo.io/api/v1/tools/integrations/int_20cf \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/mcpGA

List MCP Servers

Lists connected MCP servers; POST the same path to add one.

Each server contributes its tools into the tool registry once authorized.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/mcp/{id}GA

MCP Server Detail

Reads one MCP server; PATCH updates it and DELETE removes it.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/authorizeGA

Authorize MCP Server

Starts the OAuth authorization flow for an MCP server.

Returns the URL the user must visit — the API never handles their credentials.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/authorize \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/refreshGA

Refresh MCP Tools

Re-reads the server’s tool list after it changes.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/refresh \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/disconnectGA

Disconnect MCP Server

Revokes the stored authorization for an MCP server.

The server stays configured; re-authorize to use it again.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/disconnect \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

Review all API layers

Need the entry-point flow again? Return to the layered overview and choose Intro or Aicoo Agent.

Open API layers overview

Aicoo API

Layer 3: Aicoo OS + Tools

This layer handles persistent workspace state, notes, folders, todos, guest conversations, heartbeat automation, and tool execution.

Build on AicooOverview 1. Intro + API Key 2. Aicoo Agent 3. Aicoo OS + Tools 4. OAuth / OIDC

Build on SharedOSAgent Network API

ReferenceAPI Status OpenAPI 3.0 JSON

Layer Scope

Coordination, state, and execution

Aicoo OS is the operational surface around the core agent: workspace status, folders, notes, todos, conversations, and heartbeat runs.

Use it to sync product context, read back outcomes, and run predictable background coordination tasks.

It also exposes a tool bridge so external clients can discover and execute available Aicoo tools safely.

Bridges Both Tracks

Share links are documented under Build on SharedOS

Open Share Links reference

Tools First

How to use Aicoo tools in practice

1. Call GET /api/v1/tools to fetch names and parameter schemas.

2. Pick one tool and validate your params against the schema.

3. Call POST /api/v1/tools with tool and params.

4. Handle 422 responses as tool-level execution errors and display message details to users.

Tool Catalog

Tools are discovered via `GET /api/v1/tools` and executed via `POST /api/v1/tools`.

calendar

Calendar operations (availability lookup, event create/edit, meeting scheduling).

search_calendar_events

Search events by query, time range, or availability mode.

create_calendar_event

Create a calendar event with title, time, location, and details.

edit_calendar_event

Update an existing event by id or search query.

schedule_meeting

Schedule a meeting with attendees and optional Google Meet.

extract_calendar_event_details

Parse natural language into structured calendar event fields.

email

Email operations (search, read, draft, send).

search_emails

Search inbox using Aicoo ranking and filters.

get_email_content

Retrieve full content by email or thread id.

search_contact

Resolve contact emails by name.

save_email_draft

Save an email draft for review.

send_email

Send one email now.

send_multiple_emails

Batch send personalized emails to multiple recipients.

web

Web search and content extraction.

web_search

Search the web with recency and domain controls.

web_extract_content

Extract content from one or more URLs.

read_url

Read clean page content from a URL.

messaging

In-app network and messaging operations.

search_pulse_contact

Find contacts in the Aicoo network.

send_message_to_human

Send in-app message to a human user.

quality

Content refinement and anti-duplication checks.

refine_content

Rewrite content to target style and constraints.

verify_uniqueness

Check overlap against recent history.

fetch_recent_history

Retrieve recent outputs for consistency checks.

Jump to tools endpoints

Tools Endpoints

Discovery and execution API

GET/api/v1/toolsGA

Discover Tools

Lists all available tools with their input schemas.

Designed for external agent self-discovery.
Returns tool name + description + JSON-style parameters schema.
Companion endpoint to POST /api/v1/tools.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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/"
  }
}

POST/api/v1/toolsGA

Execute Tool

Executes one tool by name with params.

404 for unknown tools; 400 for malformed body.
422 when tool returns isError=true.
Response includes executionTimeMs.
Use /api/v1/os/* endpoints below for notes, folders, todos, memory, snapshots, network, and sharing.

Parameters

Name	In	Type	Required
`tool` Tool name from GET /api/v1/tools.	body	string	Yes
`params` Tool-specific params object.	body	object	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"search_calendar_events","params":{"query":"standup","timeRange":"today"}}'

Example Output

{
  "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 }
}

OS Endpoints

Workspace, conversations, and heartbeat API

GET/api/v1/osGA

OS Endpoint Index

Returns the discoverable Aicoo OS endpoint catalog grouped by category.

Best first call when generating SDKs or agent tool manifests.
Groups workspace, folders, notes, todos, network, snapshots, memory, and sharing endpoints.
Requires the same Bearer API key as every v1 route.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/os \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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" }]
  }
}

POST/api/v1/initGA

Initialize Workspace

Bootstraps baseline workspace state idempotently.

Ensures /General folder exists.
Returns folder tree + total files + total size.
Recommended first call for context clients.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X POST https://www.aicoo.io/api/v1/init \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Example Output

{
  "success": true,
  "initialized": true,
  "workspace": {
    "folders": [
      { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 3 }
    ],
    "totalFiles": 3,
    "totalSizeBytes": 24576
  }
}

POST/api/v1/accumulateGA

Accumulate Context

Bulk writes files/texts and deletes files/folders.

At least one operation required: files/texts/delete/folders.
Max 50 create/update entries and 10MB per file.
Existing file edits auto-create note versions.

Parameters

Name	In	Type	Required
`files` File upserts by path.	body	Array<{ path: string; content: string; message?: string }>	No
`texts` Text note upserts.	body	Array<{ title: string; content: string; folder?: string }>	No
`delete` File delete operations.	body	Array<{ path: string }>	No
`folders` Folder create/delete path list.	body	{ create?: string[]; delete?: string[] }	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/accumulate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{"path":"Research/plan.md","content":"# Plan"}],
    "folders": {"create":["Research/2026"]}
  }'

Example Output

{
  "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 }
}

GET/api/v1/os/statusGA

Workspace Status

Returns current workspace health and footprint summary.

Includes contextCount and totalSizeBytes.
Includes folder tree with file counts.
Includes lastSyncedAt timestamp.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/os/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "contextCount": 18,
  "totalSizeBytes": 76214,
  "folders": [
    { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 5 }
  ],
  "lastSyncedAt": "2026-04-10T09:22:18.000Z"
}

GET/api/v1/os/foldersGA

List Folders

Lists all folders with metadata and counts.

Includes owned and readable shared folders.
Supports parentId filtering.
Returns id, name, parentId, fileCount, shared flag, and role.

Parameters

Name	In	Type	Required
`parentId` Optional parent folder id filter.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/folders?parentId=17" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "folders": [
    {
      "id": 1,
      "name": "General",
      "parentId": null,
      "icon": null,
      "fileCount": 5,
      "createdAt": "2026-03-30T12:00:00.000Z"
    }
  ]
}

POST/api/v1/os/foldersGA

Create Folder

Creates a folder by name or creates a nested folder path.

Use { name } for a single folder segment.
Use { path: "a/b" } for nested folder creation.
Returns 200 if the folder or path already exists.

Parameters

Name	In	Type	Required
`name` Single folder segment. Use either name or path, not both.	body	string	No
`path` Nested path such as "SEAHack/Team Alpha". Use either name or path, not both.	body	string	No
`parentId` Parent folder id; omit for root.	body	number \| null	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"SEAHack/Team Alpha","parentId":null}'

Example Output

{
  "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)"
}

GET/api/v1/os/notesGA

List Notes

Lists note metadata in root or a selected folder.

Use folderId when you already know the folder.
Use folderName only when names are unambiguous.
Returns metadata only; use GET /api/v1/os/notes/{id} for full content.

Parameters

Name	In	Type	Required
`folderId` Folder id to list. Omit for root notes.	query	number	No
`folderName` Folder name lookup. Ambiguous names return 400.	query	string	No
`limit` Rows to return (default 50, max 200).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/notes?folderId=17&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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
}

POST/api/v1/os/notesGA

Create Note

Creates a note in root or a target folder the user can write to.

Requires title and content through the note tool payload.
Supports folderId when writing into a specific folder.
Returns 201 on success and 422 for tool-level validation errors.

Parameters

Name	In	Type	Required
`title` Note title.	body	string	Yes
`content` Markdown or plain text note content.	body	string	Yes
`folderId` Target folder id.	body	number	No
`tags` Optional tag list.	body	string[]	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Brief",
    "content": "Team Alpha is building on top of Aicoo.",
    "folderId": 17,
    "tags": ["hackathon"]
  }'

Example Output

{
  "success": true,
  "result": {
    "note": {
      "id": 42,
      "title": "Project Brief",
      "folderId": 17
    }
  }
}

POST/api/v1/os/notes/searchGA

Search Notes

Runs semantic note search across owned notes and readable shared folders.

Good for recall-style product features.
Includes shared folders where the user has read access.
Use grep when you need deterministic literal or regex matching.

Parameters

Name	In	Type	Required
`query` Search query.	body	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Aicoo Track submission requirements"}'

Example Output

{
  "success": true,
  "results": [
    { "id": 42, "title": "Project Brief", "snippet": "Team Alpha is building..." }
  ]
}

POST/api/v1/os/notes/grepGA

Grep Notes

Runs deterministic grep-style matching with line context.

Supports literal and regex modes.
Can filter by folderId or folderName.
Useful for agents that need exact citation-style context.

Parameters

Name	In	Type	Required
`pattern` Literal string or regex pattern.	body	string	Yes
`mode` Search mode. Defaults to literal.	body	"literal" \| "regex"	No
`contextBefore` Lines before each match.	body	number	No
`contextAfter` Lines after each match.	body	number	No
`folderId` Optional folder id filter.	body	number	No
`folderName` Optional folder name filter.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/grep \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pattern":"Aicoo Track","mode":"literal","contextBefore":1,"contextAfter":2}'

Example Output

{
  "success": true,
  "results": [
    {
      "noteId": 42,
      "title": "Project Brief",
      "matches": [
        { "line": 12, "text": "Track: Aicoo Track", "match": "Aicoo Track" }
      ]
    }
  ],
  "summary": { "notesScanned": 12, "notesMatched": 1 }
}

GET/api/v1/os/todosGA

Search Todos

Searches or lists todos through Aicoo OS.

Supports text, date, completion, priority, sorting, and pagination filters.
Can include workflow steps when includeSteps=true.
Returns tool result format with success=false for tool-level errors.

Parameters

Name	In	Type	Required
`q` Keyword search.	query	string	No
`date` Date filter such as today.	query	string	No
`completed` Completion filter.	query	boolean	No
`priorityMin` Minimum priority.	query	number	No
`limit` Rows to return.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/todos?q=demo&completed=false&priorityMin=3&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "result": {
    "todos": [
      { "id": 9001, "title": "Submit demo video", "completed": false, "priority": 5 }
    ],
    "total": 1
  }
}

POST/api/v1/os/todosGA

Create Todo

Creates a todo through Aicoo OS.

Requires title.
Supports description, dueDate, priority, and steps when provided.
Returns 201 on success and 422 for tool-level errors.

Parameters

Name	In	Type	Required
`title` Todo title.	body	string	Yes
`description` Todo details.	body	string	No
`dueDate` Optional due date.	body	string	No
`priority` Optional priority value.	body	number	No
`steps` Optional workflow steps.	body	Array<{ title: string }>	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Submit demo video","description":"Due before final judging","priority":5}'

Example Output

{
  "success": true,
  "result": {
    "todo": { "id": 9001, "title": "Submit demo video", "completed": false }
  }
}

GET/api/v1/os/network/conversationsGA

List Guest Conversations

Lists guest conversation sessions created through shared agent links.

Returns visitor identity fields when available.
Can filter by shareToken.
Includes last message preview for dashboards and review queues.

Parameters

Name	In	Type	Required
`shareToken` Filter to one share link token.	query	string	No
`limit` Rows to return (default 20).	query	number	No
`offset` Pagination offset.	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/network/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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
}

GET/api/v1/heartbeat/policyGA

Get Heartbeat Policy

Returns current heartbeat policy tier.

No request params required.
Policy is scoped to authenticated user.
Response shape: { success, policy }.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X GET https://www.aicoo.io/api/v1/heartbeat/policy \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "policy": "ACTIONS"
}

POST/api/v1/heartbeat/policyGA

Set Heartbeat Policy

Sets policy tier to ACTIONS or MESSAGES.

Invalid tier returns 400.
Persists immediately.
Returns updated policy.

Parameters

Name	In	Type	Required
`tier` Target policy tier.	body	"ACTIONS" \| "MESSAGES"	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/heartbeat/policy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier":"ACTIONS"}'

Example Output

{
  "success": true,
  "policy": "MESSAGES"
}

POST/api/v1/heartbeat/runGA

Run Heartbeat

Executes heartbeat immediately.

Optional tier override can be sent in body.
dryRun is accepted in request payload.
Response shape: { success, result }.

Parameters

Name	In	Type	Required
`tier` Optional policy override before execution.	body	"ACTIONS" \| "MESSAGES"	No
`dryRun` Optional dry-run flag.	body	boolean	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/heartbeat/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier":"MESSAGES"}'

Example Output

{
  "success": true,
  "result": {
    "runId": 123,
    "startedAt": "2026-04-10T10:10:00.000Z",
    "completedAt": "2026-04-10T10:10:04.000Z",
    "status": "completed",
    "actionsCreated": 3
  }
}

GET/api/v1/heartbeat/runsGA

List Heartbeat Runs

Lists recent heartbeat runs.

Sorted by startedAt descending.
limit defaults to 20 and maxes at 50.
Designed for polling dashboards.

Parameters

Name	In	Type	Required
`limit` Rows to return (default 20, max 50).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/heartbeat/runs?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "runs": [
    {
      "id": 123,
      "policy": "MESSAGES",
      "status": "completed",
      "startedAt": "2026-04-10T10:10:00.000Z",
      "completedAt": "2026-04-10T10:10:04.000Z"
    }
  ]
}

GET/api/v1/heartbeat/runs/{id}GA

Heartbeat Run Detail

Returns run metadata plus action rows.

Path id must be numeric.
Returns 404 for unknown/unowned run.
Response shape: { success, run, actions }.

Parameters

Name	In	Type	Required
`id` Run id from list endpoint.	path	number	Yes

Request Example

curl -X GET https://www.aicoo.io/api/v1/heartbeat/runs/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "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"
    }
  ]
}

GET/api/v1/os/notes/{id}GA

Read Note

Returns a single note with its full content.

Scope: os.notes:read.
Scoped to the authenticated user — another owner’s note is a 404, not a 403.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/notes/482 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

PATCH/api/v1/os/notes/{id}GA

Update Note

Edits a note’s title or content in place.

Scope: os.notes:write.
Partial update — omitted fields are left untouched.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes
`title` New title.	body	string	No
`content` New HTML content.	body	string	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/notes/482 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Q3 planning"}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/copyGA

Copy Note

Duplicates a note, optionally into a different folder (cp).

Scope: os.notes:write.
The copy is a new note — snapshots and share links are not carried over.

Parameters

Name	In	Type	Required
`id` Note to copy.	path	number	Yes
`folderId` Destination folder; defaults to the source folder.	body	number	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/copy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":91}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/moveGA

Move Note

Moves a note into a different folder (mv).

Scope: os.notes:write.
The destination folder must be writable by the caller.

Parameters

Name	In	Type	Required
`id` Note to move.	path	number	Yes
`folderId` Destination folder; null moves to the root space.	body	number \| null	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderId":91}'

Example Output

{
  "success": true
}

POST/api/v1/os/notes/{id}/pinGA

Pin or Unpin Note

Toggles a note’s pinned state.

Scope: os.notes:write.

Parameters

Name	In	Type	Required
`id` Note id.	path	number	Yes
`pinned` Desired pinned state.	body	boolean	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/notes/482/pin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned":true}'

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}GA

List Note Snapshots

Lists the version history captured for a note.

Scope: os.snapshots:read.
Take a snapshot before a large rewrite so the previous state stays restorable.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/snapshots/{noteId}GA

Create Snapshot

Captures the note’s current content as a restorable version.

Scope: os.snapshots:write.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`label` Human-readable marker for this version.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"before rewrite"}'

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}/seq/{seq}GA

Read Snapshot by Sequence

Retrieves one snapshot with its full content by sequence number.

Scope: os.snapshots:read.
Sequence numbers are stable per note and are the preferred addressing form.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`seq` Snapshot sequence number.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482/seq/7 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/snapshots/{noteId}/{versionId}GA

Read Snapshot by Version Id

Retrieves a legacy note_versions snapshot by its primary key.

Scope: os.snapshots:read.
Legacy addressing kept for older clients — prefer the /seq/{seq} form.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`versionId` Legacy version primary key.	path	number	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/snapshots/482/1180 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/snapshots/{noteId}/restoreGA

Restore Snapshot

Restores a note to a previously captured version.

Scope: os.snapshots:write.
Restoring overwrites current content — snapshot first if it has unsaved value.

Parameters

Name	In	Type	Required
`noteId` Note id.	path	number	Yes
`seq` Snapshot sequence to restore.	body	number	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/snapshots/482/restore \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seq":7}'

Example Output

{
  "success": true
}

PATCH/api/v1/os/todos/{id}GA

Edit Todo

Updates a todo’s fields.

Scope: os.todos:write.

Parameters

Name	In	Type	Required
`id` Todo id.	path	number	Yes
`title` New title.	body	string	No
`dueDate` ISO due date.	body	string	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/todos/55 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dueDate":"2026-08-10"}'

Example Output

{
  "success": true
}

POST/api/v1/os/todos/{id}/completeGA

Complete Todo

Marks a todo as done.

Scope: os.todos:write.

Parameters

Name	In	Type	Required
`id` Todo id.	path	number	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos/55/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/todos/replanGA

Replan Overdue Todos

Reschedules overdue todos into workable slots.

Scope: os.todos:write.
Intended for a daily agent pass rather than per-item edits.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/todos/replan \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/teamGA

Team Status

Returns team membership and seat status for the authenticated user.

Scope: os.team:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/os/team \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/team/inviteGA

Create Team Invite

Creates a team invite link.

Scope: os.team:write.
Owner or admin only — a member seat cannot mint invites.

Parameters

Name	In	Type	Required
`email` Optional address to bind the invite to.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/team/invite \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"teammate@example.com"}'

Example Output

{
  "success": true
}

GET/api/v1/os/networkGA

Network Overview

Lists share links, visitors, and contacts in one view.

Scope: os.network:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/os/network \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/os/network/conversations/{sessionId}GA

Read Guest Conversation

Returns the transcript of one guest session on a share link.

Scope: os.network:read.
Only sessions belonging to the caller’s own links are readable.

Parameters

Name	In	Type	Required
`sessionId` Guest session id.	path	string	Yes

Request Example

curl https://www.aicoo.io/api/v1/os/network/conversations/gs_41ab \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/os/memory/searchGA

Search Episodic Memory

Semantic search across the agent’s episodic memory.

Scope: os.memory:read.
Read-only — this endpoint cannot write or forget memories.

Parameters

Name	In	Type	Required
`query` Natural-language query.	body	string	Yes
`limit` Maximum results.	body	number	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"pricing decisions","limit":5}'

Example Output

{
  "success": true
}

GET/api/v1/heartbeat/statusGA

Heartbeat Status

Current autonomy tier, last run, and today’s run count.

Scope: os.heartbeat:read.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/heartbeat/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/heartbeat/instructionsGA

Heartbeat Instructions

Reads the HEARTBEAT.md checklist the autonomous pass follows.

Scope: os.heartbeat:read to read, os.heartbeat:run to replace it with PUT.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/heartbeat/instructions \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/identityGA

Identity

Returns the identity behind the presented credential.

Useful as a credential smoke test before a longer flow.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/identity \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/conversationsGA

List Conversations

Lists the authenticated user’s chat conversations.

Parameters

Name	In	Type	Required
`limit` Maximum conversations to return.	query	number	No

Request Example

curl "https://www.aicoo.io/api/v1/conversations?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/namespacesGA

Tool Namespaces

Lists tool namespaces and which are enabled for the credential.

PUT the same path to enable or disable namespaces.
A namespace that is off makes its tools uncallable via /v1/tools.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/namespaces \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/integrationsGA

List Integrations

Lists connected third-party integrations.

DELETE /api/v1/tools/integrations/{id} disconnects one.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/integrations \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

DELETE/api/v1/tools/integrations/{id}GA

Disconnect Integration

Removes a connected third-party integration.

Its tools stop resolving immediately; reconnecting requires the provider OAuth flow again.

Parameters

Name	In	Type	Required
`id` Integration id.	path	string	Yes

Request Example

curl -X DELETE https://www.aicoo.io/api/v1/tools/integrations/int_20cf \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/mcpGA

List MCP Servers

Lists connected MCP servers; POST the same path to add one.

Each server contributes its tools into the tool registry once authorized.

Parameters

Name	In	Type	Required
No path/query/body parameters required.

Request Example

curl https://www.aicoo.io/api/v1/tools/mcp \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

GET/api/v1/tools/mcp/{id}GA

MCP Server Detail

Reads one MCP server; PATCH updates it and DELETE removes it.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/authorizeGA

Authorize MCP Server

Starts the OAuth authorization flow for an MCP server.

Returns the URL the user must visit — the API never handles their credentials.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/authorize \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/refreshGA

Refresh MCP Tools

Re-reads the server’s tool list after it changes.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/refresh \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

POST/api/v1/tools/mcp/{id}/disconnectGA

Disconnect MCP Server

Revokes the stored authorization for an MCP server.

The server stays configured; re-authorize to use it again.

Parameters

Name	In	Type	Required
`id` MCP server id.	path	string	Yes

Request Example

curl -X POST https://www.aicoo.io/api/v1/tools/mcp/mcp_7f21/disconnect \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true
}

Review all API layers

Need the entry-point flow again? Return to the layered overview and choose Intro or Aicoo Agent.

Open API layers overview