Pulse API

Layer 3: Pulse Layer

This layer handles persistent context, share-link controls, heartbeat automation, and tool execution.

Overview 1. Intro + API Key 2. Pulse Agent 3. Pulse Layer

Layer Scope

Coordination, state, and execution

The Pulse Layer is the operational surface around the core agent: context sync, share links, and heartbeat runs.

Use it to accumulate workspace state, control guest access, and run predictable background coordination tasks.

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

Tools First

How to use Pulse 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`.

Notes Tools

Search, read, create, edit, and pin note content.

search_notes

AI-powered multi-query semantic search across notes.

get_note_content

Retrieve full content for a note by ID.

create_note

Create a new note with markdown/plain/HTML content.

edit_note

Update existing note content/title/folder with backup behavior.

pin_note

Pin or unpin a note.

Memory Tools

Retrieve historical episodic context.

memory_search

Search episodic memories and stored context.

Workspace Primitives

Inspect folders and note listings like filesystem commands.

list_folders

List folders with metadata and file counts.

list_notes

List notes in a folder with summary metadata.

Sharing Primitive

Create share links from tool-call workflows.

share_agent

Create guest share links with scope/access/identity settings. Control COO.md, USER.md, POLICY.md loading per link.

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_notes",
      "description": "Search through notes using AI-powered multi-query semantic search.",
      "category": "notes",
      "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] }
    }
  ],
  "usage": {
    "endpoint": "POST /api/v1/tools",
    "body": "{ \"tool\": \"<tool_name>\", \"params\": { ... } }"
  }
}

POST/api/v1/tools

Execute Tool

Executes one tool by name with params.

400 for unknown tools or malformed body.
422 when tool returns isError=true.
Response includes executionTimeMs.

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":"list_notes","params":{"folderId":5,"limit":20}}'

Example Output

{
  "success": true,
  "tool": "list_notes",
  "result": {
    "success": true,
    "folder": { "id": 5, "name": "Research" },
    "notes": [{ "id": 81, "title": "Launch Notes", "wordCount": 421 }],
    "totalNotes": 1,
    "limited": false
  },
  "metadata": { "executionTimeMs": 83 }
}

Coordination Endpoints

Context, sharing, and heartbeat API

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

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

List Folders

Lists all folders with metadata and counts.

Includes id, name, parentId, fileCount, createdAt.
Sorted by folder name.
Read operation with low token usage tracking.

Parameters

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

Request Example

curl -X GET https://www.aicoo.io/api/v1/context/folders \
  -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/context/folders

Create Folder

Creates a folder under root or specified parent folder.

Returns 201 on create.
Returns 200 if folder already exists on same level.
Validates parent ownership.

Parameters

Name	In	Type	Required
`name` Folder name (required, non-empty).	body	string	Yes
`parentId` Parent folder id; omit for root.	body	number \| null	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/context/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Client Notes","parentId":null}'

Example Output

{
  "success": true,
  "folder": { "id": 17, "name": "Client Notes", "parentId": null, "fileCount": 0 }
}

POST/api/v1/share/create

Create Share Link

Creates a guest share link for your agent.

Default scope=all, access=read, identity=all loaded.
scope=folders requires folderIds.
Returns link token and full URL.

Parameters

Name	In	Type	Required
`scope` Context exposure scope.	body	"all" \| "folders"	No
`access` Guest permission mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	No
`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

Request Example

curl -X POST https://www.aicoo.io/api/v1/share/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"all","access":"read_calendar","expiresIn":"7d","identity":{"loadCoo":true,"loadUser":true,"loadPolicy":true}}'

Example Output

{
  "success": true,
  "shareLink": {
    "id": "f7d6d8cc-7305-4385-a5c7-df7c30a4d377",
    "token": "f4c8...ab91",
    "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",
    "anonymous": true,
    "expiresAt": "2026-04-17T09:30:00.000Z",
    "createdAt": "2026-04-10T09:30:00.000Z"
  }
}

GET/api/v1/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/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/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/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/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/share/LINK_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

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

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 Pulse Agent.

Open API layers overview

Pulse API

Layer 3: Pulse Layer

This layer handles persistent context, share-link controls, heartbeat automation, and tool execution.

Overview 1. Intro + API Key 2. Pulse Agent 3. Pulse Layer

Layer Scope

Coordination, state, and execution

The Pulse Layer is the operational surface around the core agent: context sync, share links, and heartbeat runs.

Use it to accumulate workspace state, control guest access, and run predictable background coordination tasks.

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

Tools First

How to use Pulse 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`.

Notes Tools

Search, read, create, edit, and pin note content.

search_notes

AI-powered multi-query semantic search across notes.

get_note_content

Retrieve full content for a note by ID.

create_note

Create a new note with markdown/plain/HTML content.

edit_note

Update existing note content/title/folder with backup behavior.

pin_note

Pin or unpin a note.

Memory Tools

Retrieve historical episodic context.

memory_search

Search episodic memories and stored context.

Workspace Primitives

Inspect folders and note listings like filesystem commands.

list_folders

List folders with metadata and file counts.

list_notes

List notes in a folder with summary metadata.

Sharing Primitive

Create share links from tool-call workflows.

share_agent

Create guest share links with scope/access/identity settings. Control COO.md, USER.md, POLICY.md loading per link.

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_notes",
      "description": "Search through notes using AI-powered multi-query semantic search.",
      "category": "notes",
      "parameters": { "type": "object", "properties": { "query": { "type": "string" } }, "required": ["query"] }
    }
  ],
  "usage": {
    "endpoint": "POST /api/v1/tools",
    "body": "{ \"tool\": \"<tool_name>\", \"params\": { ... } }"
  }
}

POST/api/v1/tools

Execute Tool

Executes one tool by name with params.

400 for unknown tools or malformed body.
422 when tool returns isError=true.
Response includes executionTimeMs.

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":"list_notes","params":{"folderId":5,"limit":20}}'

Example Output

{
  "success": true,
  "tool": "list_notes",
  "result": {
    "success": true,
    "folder": { "id": 5, "name": "Research" },
    "notes": [{ "id": 81, "title": "Launch Notes", "wordCount": 421 }],
    "totalNotes": 1,
    "limited": false
  },
  "metadata": { "executionTimeMs": 83 }
}

Coordination Endpoints

Context, sharing, and heartbeat API

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

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

List Folders

Lists all folders with metadata and counts.

Includes id, name, parentId, fileCount, createdAt.
Sorted by folder name.
Read operation with low token usage tracking.

Parameters

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

Request Example

curl -X GET https://www.aicoo.io/api/v1/context/folders \
  -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/context/folders

Create Folder

Creates a folder under root or specified parent folder.

Returns 201 on create.
Returns 200 if folder already exists on same level.
Validates parent ownership.

Parameters

Name	In	Type	Required
`name` Folder name (required, non-empty).	body	string	Yes
`parentId` Parent folder id; omit for root.	body	number \| null	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/context/folders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Client Notes","parentId":null}'

Example Output

{
  "success": true,
  "folder": { "id": 17, "name": "Client Notes", "parentId": null, "fileCount": 0 }
}

POST/api/v1/share/create

Create Share Link

Creates a guest share link for your agent.

Default scope=all, access=read, identity=all loaded.
scope=folders requires folderIds.
Returns link token and full URL.

Parameters

Name	In	Type	Required
`scope` Context exposure scope.	body	"all" \| "folders"	No
`access` Guest permission mode.	body	"read" \| "read_calendar" \| "read_calendar_write"	No
`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

Request Example

curl -X POST https://www.aicoo.io/api/v1/share/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"all","access":"read_calendar","expiresIn":"7d","identity":{"loadCoo":true,"loadUser":true,"loadPolicy":true}}'

Example Output

{
  "success": true,
  "shareLink": {
    "id": "f7d6d8cc-7305-4385-a5c7-df7c30a4d377",
    "token": "f4c8...ab91",
    "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",
    "anonymous": true,
    "expiresAt": "2026-04-17T09:30:00.000Z",
    "createdAt": "2026-04-10T09:30:00.000Z"
  }
}

GET/api/v1/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/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/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/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/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/share/LINK_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

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

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 Pulse Agent.

Open API layers overview