Share Agent

Share Agent

Create and manage secure, shareable links to a user's agent.

Prerequisites

• AICOO_API_KEY must be set; legacy PULSE_API_KEY is also accepted
• Base URL: https://www.aicoo.io/api/v1
• User should sync context first
• Command examples use ${AICOO_API_KEY:-$PULSE_API_KEY} for backward compatibility

Core Workflow

1) Check context exists

curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  "https://www.aicoo.io/api/v1/os/status" | jq .

If contextCount is 0, run context-sync first.

2) Create a share link (OS endpoint)

curl -s -X POST "https://www.aicoo.io/api/v1/os/share" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "scope":"all",
    "access":"read",
    "notesAccess":"read",
    "label":"For investors",
    "expiresIn":"7d",
    "requireSignIn":true
  }' | jq .

3) Confirm to user

Always report:

1. URL to share
2. Scope and notes/calendar permissions
3. Expiration
4. Sign-in requirement
5. Access is sandboxed

Default behavior: new links require sign-in (requireSignIn:true). Only set requireSignIn:false when the user explicitly asks for an anonymous public link.

Parameters

Notes Access Matrix

Manage Existing Links

List links + visitors + contacts

curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  "https://www.aicoo.io/api/v1/os/network" | jq .

Update/revoke link (canonical OS endpoints)

# update
curl -s -X PATCH "https://www.aicoo.io/api/v1/os/share/{linkId}" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"notesAccess":"write","expiresIn":"30d","requireSignIn":true}' | jq .

# revoke
curl -s -X DELETE "https://www.aicoo.io/api/v1/os/share/{linkId}" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" | jq .

List links with analytics

curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  "https://www.aicoo.io/api/v1/os/share/list?status=active&limit=20" | jq .

Folder-Scoped Share Example

# inspect folders first
curl -s -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  "https://www.aicoo.io/api/v1/os/folders" | jq .

# create folder-scoped link
curl -s -X POST "https://www.aicoo.io/api/v1/os/share" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"scope":"folders","folderIds":[5,12],"access":"read","notesAccess":"write","label":"Team collaborator","requireSignIn":true}' | jq .

Per-Link Policy Editing

Link notes are stored in links/ folder. Edit policy by searching notes then patching note content:

# find link policy note
curl -s -X POST "https://www.aicoo.io/api/v1/os/notes/search" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query":"For-Investors"}' | jq .

# edit policy note content
curl -s -X PATCH "https://www.aicoo.io/api/v1/os/notes/123" \
  -H "Authorization: Bearer ${AICOO_API_KEY:-$PULSE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content":"...\n\n## Policy\n\nBe professional, concise, and do not disclose confidential numbers."}' | jq .

Security Notes

• Every link runs inside isolated scope
• New links require sign-in by default unless requireSignIn:false is explicitly set
• Signed-in visitors can appear in analytics with name, username, email, and user id; anonymous links only have guest-session/fingerprint metadata
• Revoked/expired links lose access immediately
• Default expiration is 30 days unless overridden
• Use notesAccess: "edit" carefully