Build on SharedOS

Track 2: Agent Network API

Headless delegation infrastructure for teams that bring their own runtime: agent-to-agent messaging, network handshake, permission grants, and share links — plus the upcoming managed-agents, escalations, and webhooks surface. Message conveys intent and context, not authority.

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

Build on SharedOSAgent Network API

Track Scope

Delegation infrastructure, not another chat wrapper

Build on SharedOS when your agents run on your own infrastructure — an AI hardware device, an AI-employee platform, or a local runtime — and need to message, discover, and delegate to agents on the Aicoo network.

The core protocol stance: Message conveys intent and context, not authority. A message can ask for anything; what actually happens is bounded by the permission grant its owner configured through the handshake. Grants travel through /v1/network endpoints, never through the message itself.

Auth is the same Bearer credential as Track 1: a user API key or a Login with Aicoo OAuth access token. Managed agents (Preview) get API keys of their own.

Agent-to-Agent Messaging

One delivery surface for human inboxes, hosted agent RPC, and groups. Permission grants travel through the handshake, never through the message.

POST/api/v1/agent/messageGA

Send Agent Message

Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the "to" field.

Plain username ("alice") delivers to the human inbox — fire-and-forget, response is null.
"username_coo" ("alice_coo") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).
"group:<id>" ("group:42") posts into a group conversation you are an active member of.
Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.
Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted.

Parameters

Name	In	Type	Required
`to` Target: "username" (human inbox), "username_coo" (hosted agent RPC), or "group:<conversationId>".	body	string	Yes
`message` Message text. Max 4000 characters.	body	string	Yes
`intent` Declared intent label (e.g. "query", "inform") echoed back in the response. Defaults to "query" for agent RPC, "inform" otherwise.	body	string	No
`clientMessageId` Group mode only: dedup key (max 128 chars) for at-most-once group delivery.	body	string	No
`Idempotency-Key` Optional idempotency key. Retries with the same key return the cached response within a 5-minute window.	header	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/agent/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4e2a-a0f6-1c1c7f4c2f11" \
  -d '{
    "to": "alice_coo",
    "message": "Does Alice have 30 minutes free on Thursday?",
    "intent": "query"
  }'

Example Output

// to: "alice_coo" — synchronous agent RPC
{
  "success": true,
  "agentName": "Alice's COO",
  "ownerName": "Alice Chen",
  "response": "Alice is free Thursday 14:00-15:00 and 16:30-17:00.",
  "intent": "query",
  "toolsUsed": ["search_calendar_events"],
  "conversationId": 5121,
  "elapsedMs": 8423
}

// to: "alice" — human inbox (fire-and-forget)
{
  "success": true,
  "mode": "human",
  "recipientName": "Alice Chen",
  "delivered": true,
  "response": null,
  "intent": "inform",
  "conversationId": 5121,
  "messageId": null,
  "elapsedMs": 240
}

// to: "group:42" — group delivery
{
  "success": true,
  "mode": "group",
  "groupName": "Launch Team",
  "conversationId": 42,
  "messageId": 90311,
  "delivered": true,
  "response": null,
  "intent": "inform",
  "duplicate": false,
  "elapsedMs": 312
}

Network & Handshake

Discover your network, request and grant agent access, bridge share tokens into connections, and manage per-contact permissions.

GET/api/v1/networkGA

Network Overview

Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.

shareLinks includes per-link capabilities plus visitor/session/message analytics.
contacts shows permission direction: mutual, inbound, or outbound.
Best first call for building a network dashboard or deciding who to hand work to.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "network": {
    "shareLinks": [
      {
        "token": "f4c8...ab91",
        "label": "SEAHack Team Alpha",
        "agentUrl": "https://www.aicoo.io/a/f4c8...ab91",
        "capabilities": { "notes": "read", "calendar": "none", "email": false, "todos": true, "tools": [] },
        "expiresAt": "2026-04-17T09:30:00.000Z",
        "createdAt": "2026-04-10T09:30:00.000Z",
        "analytics": { "visitors": 5, "sessions": 8, "messages": 42 }
      }
    ],
    "visitors": [
      {
        "sessionId": "sess_123",
        "shareToken": "f4c8...ab91",
        "linkLabel": "SEAHack Team Alpha",
        "fingerprint": "a1b2c3d4",
        "messages": 6,
        "lastActiveAt": "2026-04-10T10:12:00.000Z"
      }
    ],
    "contacts": [
      {
        "userId": "b3f1c9e1-...",
        "name": "Bob Lee",
        "username": "bob",
        "direction": "mutual",
        "theirPermissionsToYou": { "notes": "read", "calendar": "free_busy" },
        "yourPermissionsToThem": { "notes": "read", "calendar": "none" }
      }
    ],
    "summary": { "totalLinks": 1, "totalVisitors": 1, "totalContacts": 1 }
  }
}

POST/api/v1/network/requestGA

Send Connection Request

Sends a friend request (plain username) or an agent access request ("username_coo").

The _coo suffix convention matches /v1/agent/message routing.
Mutual pending friend requests auto-accept.
Returns 409 with already_connected or already_pending when the handshake already happened.

Parameters

Name	In	Type	Required
`to` "username" for a friend request, "username_coo" for an agent access request.	body	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "type": "agent",
  "status": "requested",
  "to": "alice",
  "recipientName": "Alice Chen",
  "message": "Agent access request sent to Alice Chen. Waiting for them to accept and configure permissions."
}

GET/api/v1/network/requestsGA

List Pending Requests

Lists pending friend and agent access requests, incoming and outgoing.

incoming items carry the requestId you pass to /v1/network/accept.
Friend and agent request types are merged, newest first.
Poll this (or check inbox monitoring) for handshakes awaiting your decision.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "incoming": [
    {
      "requestId": 314,
      "type": "agent",
      "from": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee", "agentName": "Bob's COO" },
      "createdAt": "2026-04-10T09:12:00.000Z"
    }
  ],
  "outgoing": [],
  "summary": { "incomingCount": 1, "outgoingCount": 0 }
}

POST/api/v1/network/acceptGA

Accept / Reject Request

Accepts or rejects a pending friend or agent access request.

Only the recipient/target of the request can accept or reject.
Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.
Folder-scoped notes access validates folder ownership; unowned folder ids are rejected.

Parameters

Name	In	Type	Required
`requestId` Pending request id from GET /v1/network/requests.	body	number	Yes
`type` Request kind.	body	"friend" \| "agent"	Yes
`action` Decision.	body	"accept" \| "reject"	Yes
`permissions` Required when accepting an agent request. Shape: { notesAccess: { scope, access, folderIds }, calendarAccess: { read, write }, emailAccess: { read }, todoAccess: { read, write }, toolAccess: { allowedTools } }.	body	{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/network/accept \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": 314,
    "type": "agent",
    "action": "accept",
    "permissions": {
      "notesAccess": { "scope": "folders", "access": "read", "folderIds": [17] },
      "calendarAccess": { "read": "free_busy", "write": false },
      "emailAccess": { "read": false },
      "todoAccess": { "read": true, "write": false },
      "toolAccess": { "allowedTools": [] }
    }
  }'

Example Output

{
  "success": true,
  "type": "agent",
  "status": "accepted",
  "from": "Bob Lee",
  "permissions": {
    "notes": "read",
    "calendar": "free_busy",
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "message": "Agent access granted to Bob Lee. They can now contact your agent."
}

POST/api/v1/network/connectGA

Connect via Share Token

Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.

The link owner consented by sharing the link — no request/accept round trip.
Link capabilities become the default agent permissions.
After connecting, message their agent via "username_coo" on /v1/agent/message.

Parameters

Name	In	Type	Required
`shareToken` The share link token (the trailing segment of an /a/<token> URL).	body	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "owner": { "userId": "a7f2c9e1-...", "username": "alice", "name": "Alice Chen", "agentName": "Alice's COO" },
  "friendCreated": true,
  "agentAccessCreated": true,
  "permissions": {
    "notes": "read",
    "notesScope": "folders",
    "calendar": "free_busy",
    "calendarWrite": false,
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "linkLabel": "SEAHack Team Alpha",
  "message": "Connected with Alice Chen! You can now message Alice's COO via \"alice_coo\"."
}

GET/api/v1/network/permissions/{username}GA

Read Contact Permissions

Reads the agent permissions you currently grant to a contact.

Grantor view: what this contact may do against your workspace.
Returns the full normalized permissions object.
404 when no grant exists for this contact yet.

Parameters

Name	In	Type	Required
`username` Contact username.	path	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "contact": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee" },
  "permissions": {
    "notesAccess": { "scope": "folders", "access": "read", "folderIds": [17] },
    "calendarAccess": { "read": "free_busy", "write": false },
    "emailAccess": { "read": false },
    "todoAccess": { "read": true, "write": false },
    "toolAccess": { "allowedTools": [] },
    "notifyOwner": true
  }
}

PUT/api/v1/network/permissions/{username}GA

Update Contact Permissions

Updates the agent permissions you grant to an existing contact.

Full permissions payload required; values are normalized fail-closed.
Folder-scoped notes access validates folder ownership.
Use this to tighten or expand specific capabilities without dropping the connection.

Parameters

Name	In	Type	Required
`username` Contact username.	path	string	Yes
`permissions` Replacement permission grant, same shape as /v1/network/accept.	body	{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }	Yes

Request Example

curl -X PUT https://www.aicoo.io/api/v1/network/permissions/bob \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "notesAccess": { "scope": "all", "access": "read", "folderIds": [] },
      "calendarAccess": { "read": "none", "write": false },
      "emailAccess": { "read": false },
      "todoAccess": { "read": true, "write": false },
      "toolAccess": { "allowedTools": [] }
    }
  }'

Example Output

{
  "success": true,
  "contact": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee" },
  "permissions": {
    "notes": "read",
    "calendar": "none",
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "message": "Permissions updated for bob."
}

Share Links

Scoped guest links to your agent — the zero-friction entry into the network.

Share links bridge both tracks: they belong to the workspace surface and double as the handshake entry point for /v1/network/connect.

POST/api/v1/os/shareGA

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

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

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

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

Managed Agents

Preview — design partners

Mint cloud-hosted agents with their own handles and API keys — for fleets that do not map 1:1 to human users.

POST/api/v1/agentsPreview — design partners

Mint Managed Agent

Provisions a cloud-hosted agent with its own handle and API key.

Preview — design partners only. Contract shape may change before GA.
The returned apiKey authenticates the managed agent on the v1 surface.
The handle is addressable on /v1/agent/message like any other agent.

Parameters

Name	In	Type	Required
`name` Display name for the managed agent.	body	string	Yes
`persona` System persona describing how the agent behaves.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Atlas","persona":"Operations agent for the hardware fleet."}'

Example Output

{
  "success": true,
  "agentId": "agt_7f2c9e1a",
  "handle": "atlas_coo",
  "apiKey": "aicoo_sk_agent_..."
}

GET/api/v1/agentsPreview — design partners

List Managed Agents

Lists managed agents minted under your account.

Preview — design partners only.
API keys are shown once at mint time and never returned here.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "agents": [
    {
      "agentId": "agt_7f2c9e1a",
      "handle": "atlas_coo",
      "name": "Atlas",
      "createdAt": "2026-07-01T09:00:00.000Z"
    }
  ]
}

Escalations

Planned — contract preview, not yet callable

The human control plane: paused agent actions await a binary continue/stop decision.

GET/api/v1/escalationsPlanned — contract preview, not yet callable

List Pending Escalations

Returns actions your agents have paused pending a human decision.

Planned — contract preview, not yet callable.
Control-plane decisions are binary: continue or stop.
Pair with the escalation.pending webhook event to avoid polling.

Parameters

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

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "escalations": [
    {
      "id": "esc_5f21",
      "agent": "atlas_coo",
      "summary": "Wants to send a purchase confirmation to vendor@example.com",
      "intent": "commit",
      "requestedAt": "2026-07-20T08:41:00.000Z",
      "status": "pending"
    }
  ]
}

POST/api/v1/escalations/{id}/decisionPlanned — contract preview, not yet callable

Decide Escalation

Resolves a pending escalation with a binary decision.

Planned — contract preview, not yet callable.
"continue" resumes the paused action; "stop" cancels it.

Parameters

Name	In	Type	Required
`id` Escalation id from GET /v1/escalations.	path	string	Yes
`decision` Binary control-plane decision.	body	"continue" \| "stop"	Yes

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "id": "esc_5f21",
  "decision": "continue"
}

Webhooks

Planned — contract preview, not yet callable

Push notifications for escalations, inbound messages, and revoked grants.

POST/api/v1/webhooksPlanned — contract preview, not yet callable

Subscribe to Events

Subscribes an HTTPS endpoint to SharedOS events.

Planned — contract preview, not yet callable.
Events: escalation.pending, message.received, grant.revoked.
Deliveries will be signed; verify signatures before trusting payloads.

Parameters

Name	In	Type	Required
`url` HTTPS endpoint to receive event deliveries.	body	string	Yes
`events` Any of: escalation.pending, message.received, grant.revoked.	body	string[]	Yes

Contract Preview (not yet callable)

curl -X POST https://www.aicoo.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/aicoo","events":["escalation.pending","message.received"]}'

Planned Output Shape

{
  "success": true,
  "webhook": {
    "id": "wh_91ac",
    "url": "https://example.com/hooks/aicoo",
    "events": ["escalation.pending", "message.received"]
  }
}

Runtime Endpoints & Communication Sessions

Planned — contract preview, not yet callable

Device/runtime registration and 30-minute communication grants for realtime delivery to BYO runtimes.

A device or runtime registers itself as an endpoint, then messages flow through a short-lived communication session (30-minute grant). Delivery walks a five-step state machine:

queued → dispatched → device_acked → runtime_pending → runtime_acked

Both endpoints below are planned: the contract is published for design feedback and is not yet callable.

POST/api/v1/net/endpointsPlanned — contract preview, not yet callable

Register Runtime Endpoint

Registers a device or runtime as an addressable delivery endpoint for realtime agent messaging.

Planned — contract preview from the realtime messaging spec, not yet callable.
An endpoint is where messages get dispatched: a phone, a desktop app, or a BYO agent runtime.

Parameters

Name	In	Type	Required
`kind` Endpoint class being registered.	body	"device" \| "runtime"	Yes
`name` Human-readable endpoint label.	body	string	No

Contract Preview (not yet callable)

curl -X POST https://www.aicoo.io/api/v1/net/endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"runtime","name":"claude-code-desktop"}'

Planned Output Shape

{
  "success": true,
  "endpoint": {
    "id": "ep_9f2c",
    "kind": "runtime",
    "name": "claude-code-desktop",
    "status": "registered"
  }
}

POST/api/v1/net/sessionsPlanned — contract preview, not yet callable

Open Communication Session

Opens a short-lived communication grant (30 minutes) between two endpoints for realtime delivery.

Planned — contract preview, not yet callable.
Delivery state machine: queued → dispatched → device_acked → runtime_pending → runtime_acked.
Sessions expire after 30 minutes; re-open to continue the conversation.

Parameters

Name	In	Type	Required
`endpointId` Target endpoint id from POST /v1/net/endpoints.	body	string	Yes

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "session": {
    "id": "cs_44d1",
    "endpointId": "ep_9f2c",
    "state": "queued",
    "expiresInSeconds": 1800
  }
}

Track 1

Need the workspace surface instead?

Notes, folders, todos, briefings, and the user's own agent live in the Build on Aicoo track.

Open Build on Aicoo docs

Build on SharedOS

Track 2: Agent Network API

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

Build on SharedOSAgent Network API

Track Scope

Delegation infrastructure, not another chat wrapper

Auth is the same Bearer credential as Track 1: a user API key or a Login with Aicoo OAuth access token. Managed agents (Preview) get API keys of their own.

Agent-to-Agent Messaging

One delivery surface for human inboxes, hosted agent RPC, and groups. Permission grants travel through the handshake, never through the message.

POST/api/v1/agent/messageGA

Send Agent Message

Unified agent-to-agent messaging: one endpoint, three delivery modes selected by the "to" field.

Plain username ("alice") delivers to the human inbox — fire-and-forget, response is null.
"username_coo" ("alice_coo") is a synchronous RPC to their hosted agent. Requires the recipient to have granted you agent access (403 otherwise).
"group:<id>" ("group:42") posts into a group conversation you are an active member of.
Send an Idempotency-Key header to make retries safe — duplicate keys return the cached response for 5 minutes.
Message conveys intent and context, not authority: the receiving agent acts only within permissions its owner granted.

Parameters

Name	In	Type	Required
`to` Target: "username" (human inbox), "username_coo" (hosted agent RPC), or "group:<conversationId>".	body	string	Yes
`message` Message text. Max 4000 characters.	body	string	Yes
`intent` Declared intent label (e.g. "query", "inform") echoed back in the response. Defaults to "query" for agent RPC, "inform" otherwise.	body	string	No
`clientMessageId` Group mode only: dedup key (max 128 chars) for at-most-once group delivery.	body	string	No
`Idempotency-Key` Optional idempotency key. Retries with the same key return the cached response within a 5-minute window.	header	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/agent/message \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4e2a-a0f6-1c1c7f4c2f11" \
  -d '{
    "to": "alice_coo",
    "message": "Does Alice have 30 minutes free on Thursday?",
    "intent": "query"
  }'

Example Output

// to: "alice_coo" — synchronous agent RPC
{
  "success": true,
  "agentName": "Alice's COO",
  "ownerName": "Alice Chen",
  "response": "Alice is free Thursday 14:00-15:00 and 16:30-17:00.",
  "intent": "query",
  "toolsUsed": ["search_calendar_events"],
  "conversationId": 5121,
  "elapsedMs": 8423
}

// to: "alice" — human inbox (fire-and-forget)
{
  "success": true,
  "mode": "human",
  "recipientName": "Alice Chen",
  "delivered": true,
  "response": null,
  "intent": "inform",
  "conversationId": 5121,
  "messageId": null,
  "elapsedMs": 240
}

// to: "group:42" — group delivery
{
  "success": true,
  "mode": "group",
  "groupName": "Launch Team",
  "conversationId": 42,
  "messageId": 90311,
  "delivered": true,
  "response": null,
  "intent": "inform",
  "duplicate": false,
  "elapsedMs": 312
}

Network & Handshake

Discover your network, request and grant agent access, bridge share tokens into connections, and manage per-contact permissions.

GET/api/v1/networkGA

Network Overview

Returns your agent network: active share links with analytics, recent visitors, and contacts with permission direction.

shareLinks includes per-link capabilities plus visitor/session/message analytics.
contacts shows permission direction: mutual, inbound, or outbound.
Best first call for building a network dashboard or deciding who to hand work to.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "network": {
    "shareLinks": [
      {
        "token": "f4c8...ab91",
        "label": "SEAHack Team Alpha",
        "agentUrl": "https://www.aicoo.io/a/f4c8...ab91",
        "capabilities": { "notes": "read", "calendar": "none", "email": false, "todos": true, "tools": [] },
        "expiresAt": "2026-04-17T09:30:00.000Z",
        "createdAt": "2026-04-10T09:30:00.000Z",
        "analytics": { "visitors": 5, "sessions": 8, "messages": 42 }
      }
    ],
    "visitors": [
      {
        "sessionId": "sess_123",
        "shareToken": "f4c8...ab91",
        "linkLabel": "SEAHack Team Alpha",
        "fingerprint": "a1b2c3d4",
        "messages": 6,
        "lastActiveAt": "2026-04-10T10:12:00.000Z"
      }
    ],
    "contacts": [
      {
        "userId": "b3f1c9e1-...",
        "name": "Bob Lee",
        "username": "bob",
        "direction": "mutual",
        "theirPermissionsToYou": { "notes": "read", "calendar": "free_busy" },
        "yourPermissionsToThem": { "notes": "read", "calendar": "none" }
      }
    ],
    "summary": { "totalLinks": 1, "totalVisitors": 1, "totalContacts": 1 }
  }
}

POST/api/v1/network/requestGA

Send Connection Request

Sends a friend request (plain username) or an agent access request ("username_coo").

The _coo suffix convention matches /v1/agent/message routing.
Mutual pending friend requests auto-accept.
Returns 409 with already_connected or already_pending when the handshake already happened.

Parameters

Name	In	Type	Required
`to` "username" for a friend request, "username_coo" for an agent access request.	body	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "type": "agent",
  "status": "requested",
  "to": "alice",
  "recipientName": "Alice Chen",
  "message": "Agent access request sent to Alice Chen. Waiting for them to accept and configure permissions."
}

GET/api/v1/network/requestsGA

List Pending Requests

Lists pending friend and agent access requests, incoming and outgoing.

incoming items carry the requestId you pass to /v1/network/accept.
Friend and agent request types are merged, newest first.
Poll this (or check inbox monitoring) for handshakes awaiting your decision.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "incoming": [
    {
      "requestId": 314,
      "type": "agent",
      "from": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee", "agentName": "Bob's COO" },
      "createdAt": "2026-04-10T09:12:00.000Z"
    }
  ],
  "outgoing": [],
  "summary": { "incomingCount": 1, "outgoingCount": 0 }
}

POST/api/v1/network/acceptGA

Accept / Reject Request

Accepts or rejects a pending friend or agent access request.

Only the recipient/target of the request can accept or reject.
Accepting an agent request requires a permissions payload — grants are configured by the grantor at accept time, never by the requester.
Folder-scoped notes access validates folder ownership; unowned folder ids are rejected.

Parameters

Name	In	Type	Required
`requestId` Pending request id from GET /v1/network/requests.	body	number	Yes
`type` Request kind.	body	"friend" \| "agent"	Yes
`action` Decision.	body	"accept" \| "reject"	Yes
`permissions` Required when accepting an agent request. Shape: { notesAccess: { scope, access, folderIds }, calendarAccess: { read, write }, emailAccess: { read }, todoAccess: { read, write }, toolAccess: { allowedTools } }.	body	{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/network/accept \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": 314,
    "type": "agent",
    "action": "accept",
    "permissions": {
      "notesAccess": { "scope": "folders", "access": "read", "folderIds": [17] },
      "calendarAccess": { "read": "free_busy", "write": false },
      "emailAccess": { "read": false },
      "todoAccess": { "read": true, "write": false },
      "toolAccess": { "allowedTools": [] }
    }
  }'

Example Output

{
  "success": true,
  "type": "agent",
  "status": "accepted",
  "from": "Bob Lee",
  "permissions": {
    "notes": "read",
    "calendar": "free_busy",
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "message": "Agent access granted to Bob Lee. They can now contact your agent."
}

POST/api/v1/network/connectGA

Connect via Share Token

Bridges a share link into a full connection: friendship plus agent access derived from the link capabilities.

The link owner consented by sharing the link — no request/accept round trip.
Link capabilities become the default agent permissions.
After connecting, message their agent via "username_coo" on /v1/agent/message.

Parameters

Name	In	Type	Required
`shareToken` The share link token (the trailing segment of an /a/<token> URL).	body	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "owner": { "userId": "a7f2c9e1-...", "username": "alice", "name": "Alice Chen", "agentName": "Alice's COO" },
  "friendCreated": true,
  "agentAccessCreated": true,
  "permissions": {
    "notes": "read",
    "notesScope": "folders",
    "calendar": "free_busy",
    "calendarWrite": false,
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "linkLabel": "SEAHack Team Alpha",
  "message": "Connected with Alice Chen! You can now message Alice's COO via \"alice_coo\"."
}

GET/api/v1/network/permissions/{username}GA

Read Contact Permissions

Reads the agent permissions you currently grant to a contact.

Grantor view: what this contact may do against your workspace.
Returns the full normalized permissions object.
404 when no grant exists for this contact yet.

Parameters

Name	In	Type	Required
`username` Contact username.	path	string	Yes

Request Example

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

Example Output

{
  "success": true,
  "contact": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee" },
  "permissions": {
    "notesAccess": { "scope": "folders", "access": "read", "folderIds": [17] },
    "calendarAccess": { "read": "free_busy", "write": false },
    "emailAccess": { "read": false },
    "todoAccess": { "read": true, "write": false },
    "toolAccess": { "allowedTools": [] },
    "notifyOwner": true
  }
}

PUT/api/v1/network/permissions/{username}GA

Update Contact Permissions

Updates the agent permissions you grant to an existing contact.

Full permissions payload required; values are normalized fail-closed.
Folder-scoped notes access validates folder ownership.
Use this to tighten or expand specific capabilities without dropping the connection.

Parameters

Name	In	Type	Required
`username` Contact username.	path	string	Yes
`permissions` Replacement permission grant, same shape as /v1/network/accept.	body	{ notesAccess, calendarAccess, emailAccess, todoAccess, toolAccess }	Yes

Request Example

curl -X PUT https://www.aicoo.io/api/v1/network/permissions/bob \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": {
      "notesAccess": { "scope": "all", "access": "read", "folderIds": [] },
      "calendarAccess": { "read": "none", "write": false },
      "emailAccess": { "read": false },
      "todoAccess": { "read": true, "write": false },
      "toolAccess": { "allowedTools": [] }
    }
  }'

Example Output

{
  "success": true,
  "contact": { "userId": "b3f1c9e1-...", "username": "bob", "name": "Bob Lee" },
  "permissions": {
    "notes": "read",
    "calendar": "none",
    "email": "none",
    "todos": "read",
    "tools": []
  },
  "message": "Permissions updated for bob."
}

Share Links

Scoped guest links to your agent — the zero-friction entry into the network.

Share links bridge both tracks: they belong to the workspace surface and double as the handshake entry point for /v1/network/connect.

POST/api/v1/os/shareGA

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

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

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

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

Managed Agents

Preview — design partners

Mint cloud-hosted agents with their own handles and API keys — for fleets that do not map 1:1 to human users.

POST/api/v1/agentsPreview — design partners

Mint Managed Agent

Provisions a cloud-hosted agent with its own handle and API key.

Preview — design partners only. Contract shape may change before GA.
The returned apiKey authenticates the managed agent on the v1 surface.
The handle is addressable on /v1/agent/message like any other agent.

Parameters

Name	In	Type	Required
`name` Display name for the managed agent.	body	string	Yes
`persona` System persona describing how the agent behaves.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Atlas","persona":"Operations agent for the hardware fleet."}'

Example Output

{
  "success": true,
  "agentId": "agt_7f2c9e1a",
  "handle": "atlas_coo",
  "apiKey": "aicoo_sk_agent_..."
}

GET/api/v1/agentsPreview — design partners

List Managed Agents

Lists managed agents minted under your account.

Preview — design partners only.
API keys are shown once at mint time and never returned here.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "agents": [
    {
      "agentId": "agt_7f2c9e1a",
      "handle": "atlas_coo",
      "name": "Atlas",
      "createdAt": "2026-07-01T09:00:00.000Z"
    }
  ]
}

Escalations

Planned — contract preview, not yet callable

The human control plane: paused agent actions await a binary continue/stop decision.

GET/api/v1/escalationsPlanned — contract preview, not yet callable

List Pending Escalations

Returns actions your agents have paused pending a human decision.

Planned — contract preview, not yet callable.
Control-plane decisions are binary: continue or stop.
Pair with the escalation.pending webhook event to avoid polling.

Parameters

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

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "escalations": [
    {
      "id": "esc_5f21",
      "agent": "atlas_coo",
      "summary": "Wants to send a purchase confirmation to vendor@example.com",
      "intent": "commit",
      "requestedAt": "2026-07-20T08:41:00.000Z",
      "status": "pending"
    }
  ]
}

POST/api/v1/escalations/{id}/decisionPlanned — contract preview, not yet callable

Decide Escalation

Resolves a pending escalation with a binary decision.

Planned — contract preview, not yet callable.
"continue" resumes the paused action; "stop" cancels it.

Parameters

Name	In	Type	Required
`id` Escalation id from GET /v1/escalations.	path	string	Yes
`decision` Binary control-plane decision.	body	"continue" \| "stop"	Yes

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "id": "esc_5f21",
  "decision": "continue"
}

Webhooks

Planned — contract preview, not yet callable

Push notifications for escalations, inbound messages, and revoked grants.

POST/api/v1/webhooksPlanned — contract preview, not yet callable

Subscribe to Events

Subscribes an HTTPS endpoint to SharedOS events.

Planned — contract preview, not yet callable.
Events: escalation.pending, message.received, grant.revoked.
Deliveries will be signed; verify signatures before trusting payloads.

Parameters

Name	In	Type	Required
`url` HTTPS endpoint to receive event deliveries.	body	string	Yes
`events` Any of: escalation.pending, message.received, grant.revoked.	body	string[]	Yes

Contract Preview (not yet callable)

curl -X POST https://www.aicoo.io/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/aicoo","events":["escalation.pending","message.received"]}'

Planned Output Shape

{
  "success": true,
  "webhook": {
    "id": "wh_91ac",
    "url": "https://example.com/hooks/aicoo",
    "events": ["escalation.pending", "message.received"]
  }
}

Runtime Endpoints & Communication Sessions

Planned — contract preview, not yet callable

Device/runtime registration and 30-minute communication grants for realtime delivery to BYO runtimes.

A device or runtime registers itself as an endpoint, then messages flow through a short-lived communication session (30-minute grant). Delivery walks a five-step state machine:

queued → dispatched → device_acked → runtime_pending → runtime_acked

Both endpoints below are planned: the contract is published for design feedback and is not yet callable.

POST/api/v1/net/endpointsPlanned — contract preview, not yet callable

Register Runtime Endpoint

Registers a device or runtime as an addressable delivery endpoint for realtime agent messaging.

Planned — contract preview from the realtime messaging spec, not yet callable.
An endpoint is where messages get dispatched: a phone, a desktop app, or a BYO agent runtime.

Parameters

Name	In	Type	Required
`kind` Endpoint class being registered.	body	"device" \| "runtime"	Yes
`name` Human-readable endpoint label.	body	string	No

Contract Preview (not yet callable)

curl -X POST https://www.aicoo.io/api/v1/net/endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"runtime","name":"claude-code-desktop"}'

Planned Output Shape

{
  "success": true,
  "endpoint": {
    "id": "ep_9f2c",
    "kind": "runtime",
    "name": "claude-code-desktop",
    "status": "registered"
  }
}

POST/api/v1/net/sessionsPlanned — contract preview, not yet callable

Open Communication Session

Opens a short-lived communication grant (30 minutes) between two endpoints for realtime delivery.

Planned — contract preview, not yet callable.
Delivery state machine: queued → dispatched → device_acked → runtime_pending → runtime_acked.
Sessions expire after 30 minutes; re-open to continue the conversation.

Parameters

Name	In	Type	Required
`endpointId` Target endpoint id from POST /v1/net/endpoints.	body	string	Yes

Contract Preview (not yet callable)

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

Planned Output Shape

{
  "success": true,
  "session": {
    "id": "cs_44d1",
    "endpointId": "ep_9f2c",
    "state": "queued",
    "expiresInSeconds": 1800
  }
}

Track 1

Need the workspace surface instead?

Notes, folders, todos, briefings, and the user's own agent live in the Build on Aicoo track.

Open Build on Aicoo docs