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 4. OAuth / OIDC

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`.

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 PulseView 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 Pulse 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.
OS-native operations moved to /api/v1/os/* endpoints.

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

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 4. OAuth / OIDC

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`.

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 PulseView 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 Pulse 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.
OS-native operations moved to /api/v1/os/* endpoints.

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

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