Aicoo
    LoginContact salesTry Aicoo
    Try Aicoo

    Aicoo API

    Layer 3: Aicoo OS + Tools

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

    OS Surface

    50 Endpoints

    Use this layer when your product needs Aicoo memory, permissioned sharing, or tool-driven automation.

    Manage API keysOpenAPI 3.0 specification (JSON)Extended API catalog (JSON)llms.txt for agentsBack to docs hub
    Build on AicooOverview1. Intro + API Key2. Aicoo Agent3. Aicoo OS + Tools4. OAuth / OIDC
    Build on SharedOSAgent Network API
    ReferenceAPI StatusOpenAPI 3.0 JSON

    On This Page

    Overview

    What this layer isHow tools workTools catalog

    Tools Endpoints

    Tools API surfaceDiscover ToolsExecute Tool

    OS Endpoints

    Workspace/heartbeatOS Endpoint IndexInitialize WorkspaceAccumulate ContextWorkspace StatusList FoldersCreate FolderList NotesCreate NoteSearch NotesGrep NotesSearch TodosCreate TodoList Guest ConversationsGet Heartbeat PolicySet Heartbeat PolicyRun HeartbeatList Heartbeat RunsHeartbeat Run DetailRead NoteUpdate NoteCopy NoteMove NotePin or Unpin NoteList Note SnapshotsCreate SnapshotRead Snapshot by SequenceRead Snapshot by Version IdRestore SnapshotEdit TodoComplete TodoReplan Overdue TodosTeam StatusCreate Team InviteNetwork OverviewRead Guest ConversationSearch Episodic MemoryHeartbeat StatusHeartbeat InstructionsIdentityList ConversationsTool NamespacesList IntegrationsDisconnect IntegrationList MCP ServersMCP Server DetailAuthorize MCP ServerRefresh MCP ToolsDisconnect MCP Server

    Layer Scope

    Coordination, state, and execution

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

    Use it to sync product context, read back outcomes, and run predictable background coordination tasks.

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

    Bridges Both Tracks

    Share links are documented under Build on SharedOS

    The /v1/os/share endpoints are part of the workspace surface, but they double as the handshake entry point for network connections (/v1/network/connect), so their reference now lives in the SharedOS track.

    Open Share Links reference

    Tools First

    How to use Aicoo tools in practice

    1. Call GET /api/v1/tools to fetch names and parameter schemas.

    2. Pick one tool and validate your params against the schema.

    3. Call POST /api/v1/tools with tool and params.

    4. Handle 422 responses as tool-level execution errors and display message details to users.

    Tool Catalog

    Tools are discovered via `GET /api/v1/tools` and executed via `POST /api/v1/tools`.

    calendar

    Calendar operations (availability lookup, event create/edit, meeting scheduling).

    search_calendar_events

    Search events by query, time range, or availability mode.

    create_calendar_event

    Create a calendar event with title, time, location, and details.

    edit_calendar_event

    Update an existing event by id or search query.

    schedule_meeting

    Schedule a meeting with attendees and optional Google Meet.

    extract_calendar_event_details

    Parse natural language into structured calendar event fields.

    email

    Email operations (search, read, draft, send).

    search_emails

    Search inbox using Aicoo ranking and filters.

    get_email_content

    Retrieve full content by email or thread id.

    search_contact

    Resolve contact emails by name.

    save_email_draft

    Save an email draft for review.

    send_email

    Send one email now.

    send_multiple_emails

    Batch send personalized emails to multiple recipients.

    web

    Web search and content extraction.

    web_search

    Search the web with recency and domain controls.

    web_extract_content

    Extract content from one or more URLs.

    read_url

    Read clean page content from a URL.

    messaging

    In-app network and messaging operations.

    search_pulse_contact

    Find contacts in the Aicoo network.

    send_message_to_human

    Send in-app message to a human user.

    quality

    Content refinement and anti-duplication checks.

    refine_content

    Rewrite content to target style and constraints.

    verify_uniqueness

    Check overlap against recent history.

    fetch_recent_history

    Retrieve recent outputs for consistency checks.

    Jump to tools endpoints

    Tools Endpoints

    Discovery and execution API

    GET/api/v1/toolsGA

    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

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X GET https://www.yourcoo.ai/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/toolsGA

    Execute Tool

    Executes one tool by name with params.

    • 404 for unknown tools; 400 for malformed body.
    • 422 when tool returns isError=true.
    • Response includes executionTimeMs.
    • Use /api/v1/os/* endpoints below for notes, folders, todos, memory, snapshots, network, and sharing.

    Parameters

    NameInTypeRequired
    tool

    Tool name from GET /api/v1/tools.

    bodystringYes
    params

    Tool-specific params object.

    bodyobjectNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/tools \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"tool":"search_calendar_events","params":{"query":"standup","timeRange":"today"}}'

    Example Output

    {
      "success": true,
      "tool": "search_calendar_events",
      "result": {
        "success": true,
        "events": [],
        "totalFound": 0,
        "timeRange": {
          "timeMin": "2026-04-16T00:00:00.000Z",
          "timeMax": "2026-04-17T00:00:00.000Z"
        }
      },
      "metadata": { "executionTimeMs": 83 }
    }

    OS Endpoints

    Workspace, conversations, and heartbeat API

    GET/api/v1/osGA

    OS Endpoint Index

    Returns the discoverable Aicoo OS endpoint catalog grouped by category.

    • Best first call when generating SDKs or agent tool manifests.
    • Groups workspace, folders, notes, todos, network, snapshots, memory, and sharing endpoints.
    • Requires the same Bearer API key as every v1 route.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X GET https://www.yourcoo.ai/api/v1/os \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "description": "Aicoo OS - RESTful access to notes, folders, todos, memory, snapshots, network, and sharing.",
      "totalEndpoints": 29,
      "byCategory": {
        "workspace": [{ "method": "GET", "path": "/api/v1/os/status" }],
        "folders": [{ "method": "GET", "path": "/api/v1/os/folders" }],
        "notes": [{ "method": "GET", "path": "/api/v1/os/notes" }],
        "sharing": [{ "method": "POST", "path": "/api/v1/os/share" }]
      }
    }
    POST/api/v1/initGA

    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

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X POST https://www.yourcoo.ai/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/accumulateGA

    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

    NameInTypeRequired
    files

    File upserts by path.

    bodyArray<{ path: string; content: string; message?: string }>No
    texts

    Text note upserts.

    bodyArray<{ title: string; content: string; folder?: string }>No
    delete

    File delete operations.

    bodyArray<{ path: string }>No
    folders

    Folder create/delete path list.

    body{ create?: string[]; delete?: string[] }No

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/accumulate \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "files": [{"path":"Research/plan.md","content":"# Plan"}],
        "folders": {"create":["Research/2026"]}
      }'

    Example Output

    {
      "success": true,
      "created": 1,
      "updated": 2,
      "deleted": 0,
      "skipped": 1,
      "errors": [],
      "versions": [
        { "file": "Research/plan.md", "from": "v1", "to": "v2", "message": "Updated assumptions" }
      ],
      "foldersCreated": ["Research/2026"],
      "workspace": { "totalFiles": 18, "totalSizeBytes": 76214 }
    }
    GET/api/v1/os/statusGA

    Workspace Status

    Returns current workspace health and footprint summary.

    • Includes contextCount and totalSizeBytes.
    • Includes folder tree with file counts.
    • Includes lastSyncedAt timestamp.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X GET https://www.yourcoo.ai/api/v1/os/status \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "contextCount": 18,
      "totalSizeBytes": 76214,
      "folders": [
        { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 5 }
      ],
      "lastSyncedAt": "2026-04-10T09:22:18.000Z"
    }
    GET/api/v1/os/foldersGA

    List Folders

    Lists all folders with metadata and counts.

    • Includes owned and readable shared folders.
    • Supports parentId filtering.
    • Returns id, name, parentId, fileCount, shared flag, and role.

    Parameters

    NameInTypeRequired
    parentId

    Optional parent folder id filter.

    querynumberNo

    Request Example

    curl -X GET "https://www.yourcoo.ai/api/v1/os/folders?parentId=17" \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "folders": [
        {
          "id": 1,
          "name": "General",
          "parentId": null,
          "icon": null,
          "fileCount": 5,
          "createdAt": "2026-03-30T12:00:00.000Z"
        }
      ]
    }
    POST/api/v1/os/foldersGA

    Create Folder

    Creates a folder by name or creates a nested folder path.

    • Use { name } for a single folder segment.
    • Use { path: "a/b" } for nested folder creation.
    • Returns 200 if the folder or path already exists.

    Parameters

    NameInTypeRequired
    name

    Single folder segment. Use either name or path, not both.

    bodystringNo
    path

    Nested path such as "SEAHack/Team Alpha". Use either name or path, not both.

    bodystringNo
    parentId

    Parent folder id; omit for root.

    bodynumber | nullNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/folders \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"path":"SEAHack/Team Alpha","parentId":null}'

    Example Output

    {
      "success": true,
      "mode": "path",
      "path": "SEAHack/Team Alpha",
      "folder": { "id": 17, "name": "Team Alpha", "parentId": 16 },
      "createdSegments": ["SEAHack", "Team Alpha"],
      "message": "Created 2 folder(s)"
    }
    GET/api/v1/os/notesGA

    List Notes

    Lists note metadata in root or a selected folder.

    • Use folderId when you already know the folder.
    • Use folderName only when names are unambiguous.
    • Returns metadata only; use GET /api/v1/os/notes/{id} for full content.

    Parameters

    NameInTypeRequired
    folderId

    Folder id to list. Omit for root notes.

    querynumberNo
    folderName

    Folder name lookup. Ambiguous names return 400.

    querystringNo
    limit

    Rows to return (default 50, max 200).

    querynumberNo

    Request Example

    curl -X GET "https://www.yourcoo.ai/api/v1/os/notes?folderId=17&limit=50" \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "folder": { "id": 17, "name": "Team Alpha" },
      "notes": [
        {
          "id": 42,
          "title": "Project Brief",
          "wordCount": 386,
          "pinned": true,
          "tags": ["hackathon"],
          "createdAt": "2026-04-10T08:22:00.000Z",
          "updatedAt": "2026-04-10T09:22:00.000Z"
        }
      ],
      "totalNotes": 1,
      "limited": false
    }
    POST/api/v1/os/notesGA

    Create Note

    Creates a note in root or a target folder the user can write to.

    • Requires title and content through the note tool payload.
    • Supports folderId when writing into a specific folder.
    • Returns 201 on success and 422 for tool-level validation errors.

    Parameters

    NameInTypeRequired
    title

    Note title.

    bodystringYes
    content

    Markdown or plain text note content.

    bodystringYes
    folderId

    Target folder id.

    bodynumberNo
    tags

    Optional tag list.

    bodystring[]No

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Project Brief",
        "content": "Team Alpha is building on top of Aicoo.",
        "folderId": 17,
        "tags": ["hackathon"]
      }'

    Example Output

    {
      "success": true,
      "result": {
        "note": {
          "id": 42,
          "title": "Project Brief",
          "folderId": 17
        }
      }
    }
    POST/api/v1/os/notes/searchGA

    Search Notes

    Runs semantic note search across owned notes and readable shared folders.

    • Good for recall-style product features.
    • Includes shared folders where the user has read access.
    • Use grep when you need deterministic literal or regex matching.

    Parameters

    NameInTypeRequired
    query

    Search query.

    bodystringYes

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes/search \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query":"Aicoo Track submission requirements"}'

    Example Output

    {
      "success": true,
      "results": [
        { "id": 42, "title": "Project Brief", "snippet": "Team Alpha is building..." }
      ]
    }
    POST/api/v1/os/notes/grepGA

    Grep Notes

    Runs deterministic grep-style matching with line context.

    • Supports literal and regex modes.
    • Can filter by folderId or folderName.
    • Useful for agents that need exact citation-style context.

    Parameters

    NameInTypeRequired
    pattern

    Literal string or regex pattern.

    bodystringYes
    mode

    Search mode. Defaults to literal.

    body"literal" | "regex"No
    contextBefore

    Lines before each match.

    bodynumberNo
    contextAfter

    Lines after each match.

    bodynumberNo
    folderId

    Optional folder id filter.

    bodynumberNo
    folderName

    Optional folder name filter.

    bodystringNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes/grep \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"pattern":"Aicoo Track","mode":"literal","contextBefore":1,"contextAfter":2}'

    Example Output

    {
      "success": true,
      "results": [
        {
          "noteId": 42,
          "title": "Project Brief",
          "matches": [
            { "line": 12, "text": "Track: Aicoo Track", "match": "Aicoo Track" }
          ]
        }
      ],
      "summary": { "notesScanned": 12, "notesMatched": 1 }
    }
    GET/api/v1/os/todosGA

    Search Todos

    Searches or lists todos through Aicoo OS.

    • Supports text, date, completion, priority, sorting, and pagination filters.
    • Can include workflow steps when includeSteps=true.
    • Returns tool result format with success=false for tool-level errors.

    Parameters

    NameInTypeRequired
    q

    Keyword search.

    querystringNo
    date

    Date filter such as today.

    querystringNo
    completed

    Completion filter.

    querybooleanNo
    priorityMin

    Minimum priority.

    querynumberNo
    limit

    Rows to return.

    querynumberNo

    Request Example

    curl -X GET "https://www.yourcoo.ai/api/v1/os/todos?q=demo&completed=false&priorityMin=3&limit=20" \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "result": {
        "todos": [
          { "id": 9001, "title": "Submit demo video", "completed": false, "priority": 5 }
        ],
        "total": 1
      }
    }
    POST/api/v1/os/todosGA

    Create Todo

    Creates a todo through Aicoo OS.

    • Requires title.
    • Supports description, dueDate, priority, and steps when provided.
    • Returns 201 on success and 422 for tool-level errors.

    Parameters

    NameInTypeRequired
    title

    Todo title.

    bodystringYes
    description

    Todo details.

    bodystringNo
    dueDate

    Optional due date.

    bodystringNo
    priority

    Optional priority value.

    bodynumberNo
    steps

    Optional workflow steps.

    bodyArray<{ title: string }>No

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/todos \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"title":"Submit demo video","description":"Due before final judging","priority":5}'

    Example Output

    {
      "success": true,
      "result": {
        "todo": { "id": 9001, "title": "Submit demo video", "completed": false }
      }
    }
    GET/api/v1/os/network/conversationsGA

    List Guest Conversations

    Lists guest conversation sessions created through shared agent links.

    • Returns visitor identity fields when available.
    • Can filter by shareToken.
    • Includes last message preview for dashboards and review queues.

    Parameters

    NameInTypeRequired
    shareToken

    Filter to one share link token.

    querystringNo
    limit

    Rows to return (default 20).

    querynumberNo
    offset

    Pagination offset.

    querynumberNo

    Request Example

    curl -X GET "https://www.yourcoo.ai/api/v1/os/network/conversations?limit=20" \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "conversations": [
        {
          "sessionId": "sess_123",
          "shareToken": "f4c8...ab91",
          "linkLabel": "SEAHack Team Alpha",
          "guestName": "Mentor",
          "lastRole": "assistant",
          "lastContent": "The team still needs to finalize the demo script.",
          "lastCreatedAt": "2026-04-10T10:12:00.000Z"
        }
      ],
      "limit": 20,
      "offset": 0
    }
    GET/api/v1/heartbeat/policyGA

    Get Heartbeat Policy

    Returns current heartbeat policy tier.

    • No request params required.
    • Policy is scoped to authenticated user.
    • Response shape: { success, policy }.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X GET https://www.yourcoo.ai/api/v1/heartbeat/policy \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true,
      "policy": "ACTIONS"
    }
    POST/api/v1/heartbeat/policyGA

    Set Heartbeat Policy

    Sets policy tier to ACTIONS or MESSAGES.

    • Invalid tier returns 400.
    • Persists immediately.
    • Returns updated policy.

    Parameters

    NameInTypeRequired
    tier

    Target policy tier.

    body"ACTIONS" | "MESSAGES"Yes

    Request Example

    curl -X POST https://www.yourcoo.ai/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/runGA

    Run Heartbeat

    Executes heartbeat immediately.

    • Optional tier override can be sent in body.
    • dryRun is accepted in request payload.
    • Response shape: { success, result }.

    Parameters

    NameInTypeRequired
    tier

    Optional policy override before execution.

    body"ACTIONS" | "MESSAGES"No
    dryRun

    Optional dry-run flag.

    bodybooleanNo

    Request Example

    curl -X POST https://www.yourcoo.ai/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/runsGA

    List Heartbeat Runs

    Lists recent heartbeat runs.

    • Sorted by startedAt descending.
    • limit defaults to 20 and maxes at 50.
    • Designed for polling dashboards.

    Parameters

    NameInTypeRequired
    limit

    Rows to return (default 20, max 50).

    querynumberNo

    Request Example

    curl -X GET "https://www.yourcoo.ai/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}GA

    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

    NameInTypeRequired
    id

    Run id from list endpoint.

    pathnumberYes

    Request Example

    curl -X GET https://www.yourcoo.ai/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"
        }
      ]
    }
    GET/api/v1/os/notes/{id}GA

    Read Note

    Returns a single note with its full content.

    • Scope: os.notes:read.
    • Scoped to the authenticated user — another owner’s note is a 404, not a 403.

    Parameters

    NameInTypeRequired
    id

    Note id.

    pathnumberYes

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/notes/482 \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    PATCH/api/v1/os/notes/{id}GA

    Update Note

    Edits a note’s title or content in place.

    • Scope: os.notes:write.
    • Partial update — omitted fields are left untouched.

    Parameters

    NameInTypeRequired
    id

    Note id.

    pathnumberYes
    title

    New title.

    bodystringNo
    content

    New HTML content.

    bodystringNo

    Request Example

    curl -X PATCH https://www.yourcoo.ai/api/v1/os/notes/482 \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"title":"Q3 planning"}'

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/notes/{id}/copyGA

    Copy Note

    Duplicates a note, optionally into a different folder (cp).

    • Scope: os.notes:write.
    • The copy is a new note — snapshots and share links are not carried over.

    Parameters

    NameInTypeRequired
    id

    Note to copy.

    pathnumberYes
    folderId

    Destination folder; defaults to the source folder.

    bodynumberNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes/482/copy \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"folderId":91}'

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/notes/{id}/moveGA

    Move Note

    Moves a note into a different folder (mv).

    • Scope: os.notes:write.
    • The destination folder must be writable by the caller.

    Parameters

    NameInTypeRequired
    id

    Note to move.

    pathnumberYes
    folderId

    Destination folder; null moves to the root space.

    bodynumber | nullYes

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes/482/move \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"folderId":91}'

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/notes/{id}/pinGA

    Pin or Unpin Note

    Toggles a note’s pinned state.

    • Scope: os.notes:write.

    Parameters

    NameInTypeRequired
    id

    Note id.

    pathnumberYes
    pinned

    Desired pinned state.

    bodybooleanYes

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/notes/482/pin \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"pinned":true}'

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/snapshots/{noteId}GA

    List Note Snapshots

    Lists the version history captured for a note.

    • Scope: os.snapshots:read.
    • Take a snapshot before a large rewrite so the previous state stays restorable.

    Parameters

    NameInTypeRequired
    noteId

    Note id.

    pathnumberYes

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/snapshots/482 \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/snapshots/{noteId}GA

    Create Snapshot

    Captures the note’s current content as a restorable version.

    • Scope: os.snapshots:write.

    Parameters

    NameInTypeRequired
    noteId

    Note id.

    pathnumberYes
    label

    Human-readable marker for this version.

    bodystringNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/snapshots/482 \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"label":"before rewrite"}'

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/snapshots/{noteId}/seq/{seq}GA

    Read Snapshot by Sequence

    Retrieves one snapshot with its full content by sequence number.

    • Scope: os.snapshots:read.
    • Sequence numbers are stable per note and are the preferred addressing form.

    Parameters

    NameInTypeRequired
    noteId

    Note id.

    pathnumberYes
    seq

    Snapshot sequence number.

    pathnumberYes

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/snapshots/482/seq/7 \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/snapshots/{noteId}/{versionId}GA

    Read Snapshot by Version Id

    Retrieves a legacy note_versions snapshot by its primary key.

    • Scope: os.snapshots:read.
    • Legacy addressing kept for older clients — prefer the /seq/{seq} form.

    Parameters

    NameInTypeRequired
    noteId

    Note id.

    pathnumberYes
    versionId

    Legacy version primary key.

    pathnumberYes

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/snapshots/482/1180 \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/snapshots/{noteId}/restoreGA

    Restore Snapshot

    Restores a note to a previously captured version.

    • Scope: os.snapshots:write.
    • Restoring overwrites current content — snapshot first if it has unsaved value.

    Parameters

    NameInTypeRequired
    noteId

    Note id.

    pathnumberYes
    seq

    Snapshot sequence to restore.

    bodynumberYes

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/snapshots/482/restore \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"seq":7}'

    Example Output

    {
      "success": true
    }
    PATCH/api/v1/os/todos/{id}GA

    Edit Todo

    Updates a todo’s fields.

    • Scope: os.todos:write.

    Parameters

    NameInTypeRequired
    id

    Todo id.

    pathnumberYes
    title

    New title.

    bodystringNo
    dueDate

    ISO due date.

    bodystringNo

    Request Example

    curl -X PATCH https://www.yourcoo.ai/api/v1/os/todos/55 \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"dueDate":"2026-08-10"}'

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/todos/{id}/completeGA

    Complete Todo

    Marks a todo as done.

    • Scope: os.todos:write.

    Parameters

    NameInTypeRequired
    id

    Todo id.

    pathnumberYes

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/todos/55/complete \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/todos/replanGA

    Replan Overdue Todos

    Reschedules overdue todos into workable slots.

    • Scope: os.todos:write.
    • Intended for a daily agent pass rather than per-item edits.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/todos/replan \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/teamGA

    Team Status

    Returns team membership and seat status for the authenticated user.

    • Scope: os.team:read.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/team \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/team/inviteGA

    Create Team Invite

    Creates a team invite link.

    • Scope: os.team:write.
    • Owner or admin only — a member seat cannot mint invites.

    Parameters

    NameInTypeRequired
    email

    Optional address to bind the invite to.

    bodystringNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/team/invite \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"email":"teammate@example.com"}'

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/networkGA

    Network Overview

    Lists share links, visitors, and contacts in one view.

    • Scope: os.network:read.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/network \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/os/network/conversations/{sessionId}GA

    Read Guest Conversation

    Returns the transcript of one guest session on a share link.

    • Scope: os.network:read.
    • Only sessions belonging to the caller’s own links are readable.

    Parameters

    NameInTypeRequired
    sessionId

    Guest session id.

    pathstringYes

    Request Example

    curl https://www.yourcoo.ai/api/v1/os/network/conversations/gs_41ab \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    POST/api/v1/os/memory/searchGA

    Search Episodic Memory

    Semantic search across the agent’s episodic memory.

    • Scope: os.memory:read.
    • Read-only — this endpoint cannot write or forget memories.

    Parameters

    NameInTypeRequired
    query

    Natural-language query.

    bodystringYes
    limit

    Maximum results.

    bodynumberNo

    Request Example

    curl -X POST https://www.yourcoo.ai/api/v1/os/memory/search \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query":"pricing decisions","limit":5}'

    Example Output

    {
      "success": true
    }
    GET/api/v1/heartbeat/statusGA

    Heartbeat Status

    Current autonomy tier, last run, and today’s run count.

    • Scope: os.heartbeat:read.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl https://www.yourcoo.ai/api/v1/heartbeat/status \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/heartbeat/instructionsGA

    Heartbeat Instructions

    Reads the HEARTBEAT.md checklist the autonomous pass follows.

    • Scope: os.heartbeat:read to read, os.heartbeat:run to replace it with PUT.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl https://www.yourcoo.ai/api/v1/heartbeat/instructions \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/identityGA

    Identity

    Returns the identity behind the presented credential.

    • Useful as a credential smoke test before a longer flow.

    Parameters

    NameInTypeRequired
    No path/query/body parameters required.

    Request Example

    curl https://www.yourcoo.ai/api/v1/identity \
      -H "Authorization: Bearer YOUR_API_KEY"

    Example Output

    {
      "success": true
    }
    GET/api/v1/conversationsGA

    List Conversations

    Lists the authenticated user’s chat conversations.

      Parameters

      NameInTypeRequired
      limit

      Maximum conversations to return.

      querynumberNo

      Request Example

      curl "https://www.yourcoo.ai/api/v1/conversations?limit=20" \
        -H "Authorization: Bearer YOUR_API_KEY"

      Example Output

      {
        "success": true
      }
      GET/api/v1/tools/namespacesGA

      Tool Namespaces

      Lists tool namespaces and which are enabled for the credential.

      • PUT the same path to enable or disable namespaces.
      • A namespace that is off makes its tools uncallable via /v1/tools.

      Parameters

      NameInTypeRequired
      No path/query/body parameters required.

      Request Example

      curl https://www.yourcoo.ai/api/v1/tools/namespaces \
        -H "Authorization: Bearer YOUR_API_KEY"

      Example Output

      {
        "success": true
      }
      GET/api/v1/tools/integrationsGA

      List Integrations

      Lists connected third-party integrations.

      • DELETE /api/v1/tools/integrations/{id} disconnects one.

      Parameters

      NameInTypeRequired
      No path/query/body parameters required.

      Request Example

      curl https://www.yourcoo.ai/api/v1/tools/integrations \
        -H "Authorization: Bearer YOUR_API_KEY"

      Example Output

      {
        "success": true
      }
      DELETE/api/v1/tools/integrations/{id}GA

      Disconnect Integration

      Removes a connected third-party integration.

      • Its tools stop resolving immediately; reconnecting requires the provider OAuth flow again.

      Parameters

      NameInTypeRequired
      id

      Integration id.

      pathstringYes

      Request Example

      curl -X DELETE https://www.yourcoo.ai/api/v1/tools/integrations/int_20cf \
        -H "Authorization: Bearer YOUR_API_KEY"

      Example Output

      {
        "success": true
      }
      GET/api/v1/tools/mcpGA

      List MCP Servers

      Lists connected MCP servers; POST the same path to add one.

      • Each server contributes its tools into the tool registry once authorized.

      Parameters

      NameInTypeRequired
      No path/query/body parameters required.

      Request Example

      curl https://www.yourcoo.ai/api/v1/tools/mcp \
        -H "Authorization: Bearer YOUR_API_KEY"

      Example Output

      {
        "success": true
      }
      GET/api/v1/tools/mcp/{id}GA

      MCP Server Detail

      Reads one MCP server; PATCH updates it and DELETE removes it.

        Parameters

        NameInTypeRequired
        id

        MCP server id.

        pathstringYes

        Request Example

        curl https://www.yourcoo.ai/api/v1/tools/mcp/mcp_7f21 \
          -H "Authorization: Bearer YOUR_API_KEY"

        Example Output

        {
          "success": true
        }
        POST/api/v1/tools/mcp/{id}/authorizeGA

        Authorize MCP Server

        Starts the OAuth authorization flow for an MCP server.

        • Returns the URL the user must visit — the API never handles their credentials.

        Parameters

        NameInTypeRequired
        id

        MCP server id.

        pathstringYes

        Request Example

        curl -X POST https://www.yourcoo.ai/api/v1/tools/mcp/mcp_7f21/authorize \
          -H "Authorization: Bearer YOUR_API_KEY"

        Example Output

        {
          "success": true
        }
        POST/api/v1/tools/mcp/{id}/refreshGA

        Refresh MCP Tools

        Re-reads the server’s tool list after it changes.

          Parameters

          NameInTypeRequired
          id

          MCP server id.

          pathstringYes

          Request Example

          curl -X POST https://www.yourcoo.ai/api/v1/tools/mcp/mcp_7f21/refresh \
            -H "Authorization: Bearer YOUR_API_KEY"

          Example Output

          {
            "success": true
          }
          POST/api/v1/tools/mcp/{id}/disconnectGA

          Disconnect MCP Server

          Revokes the stored authorization for an MCP server.

          • The server stays configured; re-authorize to use it again.

          Parameters

          NameInTypeRequired
          id

          MCP server id.

          pathstringYes

          Request Example

          curl -X POST https://www.yourcoo.ai/api/v1/tools/mcp/mcp_7f21/disconnect \
            -H "Authorization: Bearer YOUR_API_KEY"

          Example Output

          {
            "success": true
          }

          Back to Top

          Review all API layers

          Need the entry-point flow again? Return to the layered overview and choose Intro or Aicoo Agent.

          Open API layers overview
          © 2026 Aicoo/SysteMind, Inc. (USA)
          SecurityDocsBlogTermsPrivacyDelete account