Aicoo API

Layer 3: Aicoo OS + Tools

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

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

Layer Scope

Coordination, state, and execution

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

Use it to sync product context, create scoped guest access, 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.

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/tools

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/tools

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, sharing, conversations, and heartbeat API

GET/api/v1/os

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 workspace data: 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/init

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/accumulate

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/status

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/folders

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/folders

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/notes

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/notes

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/search

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/grep

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/todos

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/todos

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

POST/api/v1/os/share

Create Share Link

Creates a guest share link for your agent.

Creates a scoped Aicoo agent or note link.
scope=folders requires folderIds.
Returns link token, URL, capabilities, and expiry metadata.

Parameters

Name	In	Type	Required
`scope` Context exposure scope.	body	"all" \| "folders"	Yes
`access` Guest permission mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	Yes
`label` Optional label for managing links.	body	string	No
`expiresIn` Optional expiry duration.	body	"1h" \| "24h" \| "7d" \| "30d"	No
`folderIds` Required when scope=folders.	body	number[]	No
`notesAccess` Guest notes permission. Default read.	body	"read" \| "write" \| "edit"	No
`identity` Control which identity files the agent loads. All default to true.	body	{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }	No
`todos` Optional todo capabilities exposed to the link.	body	object	No
`requireSignIn` Whether guests must sign in. Defaults to true.	body	boolean	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "folders",
    "access": "read",
    "folderIds": [17],
    "label": "SEAHack Team Alpha",
    "expiresIn": "7d",
    "requireSignIn": true
  }'

Example Output

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

GET/api/v1/os/share/list

List Share Links

Lists links with activity analytics.

status filter: active | revoked | all.
limit max 50.
Per-link analytics: visitors, conversations, messages.

Parameters

Name	In	Type	Required
`status` Link status filter. Default active.	query	"active" \| "revoked" \| "all"	No
`limit` Rows to return (default 20, max 50).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/share/list?status=all&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

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

PATCH/api/v1/os/share/{linkId}

Update Share Link

Partially updates link configuration fields.

Update scope/access/label/folderIds/expiresIn/notesAccess/identity.
Returns 404 for unknown or unowned link ID.
Scope and access values are fail-closed validated.

Parameters

Name	In	Type	Required
`linkId` Share link id from create/list response.	path	string	Yes
`scope` Updated scope.	body	"all" \| "folders"	No
`access` Updated access mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	No
`label` Updated label.	body	string \| null	No
`folderIds` Updated folder list when using folder scope.	body	number[]	No
`expiresIn` New expiry offset from now.	body	"1h" \| "24h" \| "7d" \| "30d"	No
`notesAccess` Updated notes permission.	body	"read" \| "write" \| "edit"	No
`identity` Update which identity files the agent loads.	body	{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/share/LINK_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Updated label","identity":{"loadCoo":false}}'

Example Output

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

DELETE/api/v1/os/share/{linkId}

Revoke Share Link

Revokes a link by setting isActive=false.

Guest access is immediately disabled.
Returns 404 for unknown/unowned ids.
Revoked links still listable via status filter.

Parameters

Name	In	Type	Required
`linkId` Share link id from create/list response.	path	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "message": "Share link revoked"
}

GET/api/v1/os/network/conversations

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/policy

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/policy

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/run

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/runs

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}

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

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, share links, guest conversations, heartbeat automation, and tool execution.

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

Layer Scope

Coordination, state, and execution

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

Use it to sync product context, create scoped guest access, 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.

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/tools

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/tools

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, sharing, conversations, and heartbeat API

GET/api/v1/os

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 workspace data: 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/init

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/accumulate

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/status

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/folders

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/folders

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/notes

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/notes

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/search

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/grep

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/todos

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/todos

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

POST/api/v1/os/share

Create Share Link

Creates a guest share link for your agent.

Creates a scoped Aicoo agent or note link.
scope=folders requires folderIds.
Returns link token, URL, capabilities, and expiry metadata.

Parameters

Name	In	Type	Required
`scope` Context exposure scope.	body	"all" \| "folders"	Yes
`access` Guest permission mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	Yes
`label` Optional label for managing links.	body	string	No
`expiresIn` Optional expiry duration.	body	"1h" \| "24h" \| "7d" \| "30d"	No
`folderIds` Required when scope=folders.	body	number[]	No
`notesAccess` Guest notes permission. Default read.	body	"read" \| "write" \| "edit"	No
`identity` Control which identity files the agent loads. All default to true.	body	{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }	No
`todos` Optional todo capabilities exposed to the link.	body	object	No
`requireSignIn` Whether guests must sign in. Defaults to true.	body	boolean	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/os/share \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "folders",
    "access": "read",
    "folderIds": [17],
    "label": "SEAHack Team Alpha",
    "expiresIn": "7d",
    "requireSignIn": true
  }'

Example Output

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

GET/api/v1/os/share/list

List Share Links

Lists links with activity analytics.

status filter: active | revoked | all.
limit max 50.
Per-link analytics: visitors, conversations, messages.

Parameters

Name	In	Type	Required
`status` Link status filter. Default active.	query	"active" \| "revoked" \| "all"	No
`limit` Rows to return (default 20, max 50).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/os/share/list?status=all&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

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

PATCH/api/v1/os/share/{linkId}

Update Share Link

Partially updates link configuration fields.

Update scope/access/label/folderIds/expiresIn/notesAccess/identity.
Returns 404 for unknown or unowned link ID.
Scope and access values are fail-closed validated.

Parameters

Name	In	Type	Required
`linkId` Share link id from create/list response.	path	string	Yes
`scope` Updated scope.	body	"all" \| "folders"	No
`access` Updated access mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	No
`label` Updated label.	body	string \| null	No
`folderIds` Updated folder list when using folder scope.	body	number[]	No
`expiresIn` New expiry offset from now.	body	"1h" \| "24h" \| "7d" \| "30d"	No
`notesAccess` Updated notes permission.	body	"read" \| "write" \| "edit"	No
`identity` Update which identity files the agent loads.	body	{ loadCoo?: boolean, loadUser?: boolean, loadPolicy?: boolean }	No

Request Example

curl -X PATCH https://www.aicoo.io/api/v1/os/share/LINK_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Updated label","identity":{"loadCoo":false}}'

Example Output

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

DELETE/api/v1/os/share/{linkId}

Revoke Share Link

Revokes a link by setting isActive=false.

Guest access is immediately disabled.
Returns 404 for unknown/unowned ids.
Revoked links still listable via status filter.

Parameters

Name	In	Type	Required
`linkId` Share link id from create/list response.	path	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "message": "Share link revoked"
}

GET/api/v1/os/network/conversations

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/policy

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/policy

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/run

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/runs

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}

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

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