Aicoo API

Layer 2: Aicoo Agent

All endpoints in this layer are about AI reasoning workflows: chat, briefing synthesis, and strategy planning.

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

Layer Scope

Reasoning and planning endpoints

The Aicoo Agent layer is where natural-language requests become structured reasoning output.

Use it for chat, executive briefings, strategic priorities, and matrix-based task classification.

If you need context sync, sharing controls, notes, todos, conversations, or tools execution, move to the Aicoo OS + Tools page.

Endpoints

Aicoo Agent API surface

POST/api/v1/chat

Agent Chat

Primary conversational endpoint for the Aicoo Agent.

Accepts API key auth and reuses the same core routing as product chat.
Supports conversation continuity and tool-assisted responses.
Allows model and temperature overrides in payload.

Parameters

Name	In	Type	Required
`message` User message text.	body	string	Yes
`conversationId` Continue an existing conversation.	body	number \| string	No
`userTimezone` IANA timezone, defaults to UTC.	body	string	No
`model` Optional model alias selection.	body	string	No
`stream` Defaults to true for streaming events.	body	boolean	No
`temperature` Sampling control override.	body	number	No
`attachmentIds` Attachment IDs to include in context.	body	number[]	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize open priorities from my context",
    "stream": true
  }'

Example Output

{"type":"text-delta","textDelta":"Here is your plan for today..."}
{"type":"tool-call-start","toolName":"search_calendar_events","toolCallId":"call_123"}
{"type":"completion","metadata":{"promptTokens":812,"completionTokens":191,"totalTokens":1003}}

POST/api/v1/briefing

Daily Briefing

Generates a full executive briefing from todos, notes, and optional external inputs.

Returns statusQuoSummary plus sub-summaries and suggestions.
Persists briefing history for future retrieval.
Tracks token usage under the calling API key.

Parameters

Name	In	Type	Required
`timeDuration` Time window label. Default is "last 24 hours".	body	string	No
`emails` Optional normalized email input set.	body	Array<{ id?, summary?, priority?, category?, needsReply?, date?, sender?, snippet? }>	No
`calendarEvents` Optional calendar event list.	body	Array<{ summary?, start, end, location?, description? }>	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/briefing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeDuration": "last 24 hours",
    "emails": [{"summary": "Need response", "priority": 5, "needsReply": true}]
  }'

Example Output

{
  "success": true,
  "briefingId": 128,
  "statusQuoSummary": "<h3>Today's Focus</h3><ul><li>Finalize partner brief</li></ul>",
  "todoSummary": "<ul><li>Finish Q3 review</li></ul>",
  "calendarSummary": "<ul><li>Client sync at 2:00 PM</li></ul>",
  "notesSummary": "<ul><li>Roadmap draft updated</li></ul>",
  "emailAttentionSummary": "<ul><li>P5 - Investor follow-up required</li></ul>",
  "suggestions": [
    {
      "title": "Reply to investor thread",
      "description": "Close open financing question before EOD",
      "action": "Send concise status update",
      "suggestionId": "a8f5f167-f44f-4f6f-b4af-555aa5c2e4c2"
    }
  ],
  "tokenUsage": { "total": 1422 }
}

POST/api/v1/briefing/strategies

COO Strategies

Derives top 3 strategic priorities from summary inputs.

Returns empty list if all summary fields are missing.
Normalizes urgency and category values.
Includes generatedAt timestamp.

Parameters

Name	In	Type	Required
`statusQuoSummary` Main summary.	body	string	No
`todoSummary` Todo summary.	body	string	No
`calendarSummary` Calendar summary.	body	string	No
`notesSummary` Notes summary.	body	string	No
`emailAttentionSummary` Email summary.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/briefing/strategies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statusQuoSummary": "Main blockers are...",
    "todoSummary": "Top tasks..."
  }'

Example Output

{
  "success": true,
  "strategies": [
    {
      "priority": 1,
      "title": "Confirm launch dependencies",
      "description": "Resolve blockers from engineering and design",
      "urgencyLevel": "critical",
      "category": "action"
    }
  ],
  "generatedAt": "2026-04-10T09:30:00.000Z"
}

POST/api/v1/briefing/matrix

Eisenhower Matrix

Classifies work into Q1-Q4 urgency/importance buckets.

Returns all four quadrants in one payload.
Each quadrant item source is normalized.
Returns empty matrix if no summaries provided.

Parameters

Name	In	Type	Required
`statusQuoSummary` Main summary.	body	string	No
`todoSummary` Todo summary.	body	string	No
`calendarSummary` Calendar summary.	body	string	No
`notesSummary` Notes summary.	body	string	No
`emailAttentionSummary` Email summary.	body	string	No

Request Example

curl -X POST https://www.aicoo.io/api/v1/briefing/matrix \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"statusQuoSummary": "Deadlines this week..."}'

Example Output

{
  "success": true,
  "matrix": {
    "q1_urgent_important": [{ "title": "Client deadline today", "source": "email" }],
    "q2_not_urgent_important": [{ "title": "Q2 hiring plan", "source": "note" }],
    "q3_urgent_not_important": [{ "title": "Reschedule vendor demo", "source": "calendar" }],
    "q4_not_urgent_not_important": []
  },
  "generatedAt": "2026-04-10T09:30:00.000Z"
}

GET/api/v1/briefings

Briefing History

Returns stored briefing history rows for the authenticated user.

Ordered by generatedAt descending.
limit is capped at 50.
Returns id + summary + generated timestamp.

Parameters

Name	In	Type	Required
`limit` Rows to return (default 10, max 50).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/briefings?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "briefings": [
    {
      "id": 128,
      "statusQuoSummary": "<h3>Today's Focus</h3><ul><li>...</li></ul>",
      "timeDuration": "last 24 hours",
      "generatedAt": "2026-04-10T09:12:00.000Z"
    }
  ]
}

GET/api/v1/notes/summary

Notes Summary

Returns recent notes plus a compact HTML summary block.

Includes relativeTime and pinned flags.
Sorted by most recently updated notes.
limit is capped at 20.

Parameters

Name	In	Type	Required
`limit` Rows to return (default 5, max 20).	query	number	No

Request Example

curl -X GET "https://www.aicoo.io/api/v1/notes/summary?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Output

{
  "success": true,
  "notes": [
    {
      "id": 42,
      "title": "Roadmap Decisions",
      "summary": "Decided to ship onboarding improvements first...",
      "updatedAt": "2026-04-10T08:22:00.000Z",
      "relativeTime": "2 hours ago",
      "pinned": true
    }
  ],
  "notesSummary": "<ul><li><strong>Roadmap Decisions</strong> [pinned] <span>(2 hours ago)</span></li></ul>"
}

Next Layer

Continue to Aicoo OS + Tools

For notes, folders, todos, share links, conversations, tools, and heartbeat workflows, use the OS + Tools page.

Open Aicoo OS + Tools docs

Reasoning and planning endpoints

The Aicoo Agent layer is where natural-language requests become structured reasoning output.

Use it for chat, executive briefings, strategic priorities, and matrix-based task classification.

If you need context sync, sharing controls, notes, todos, conversations, or tools execution, move to the Aicoo OS + Tools page.

Name

Type

Required

message

User message text.

body

string

Yes

conversationId

Continue an existing conversation.

body

number | string

userTimezone

IANA timezone, defaults to UTC.

body

string

model

Optional model alias selection.

body

string

stream

Defaults to true for streaming events.

body

boolean

temperature

Sampling control override.

body

number

attachmentIds

Attachment IDs to include in context.

body

number[]

curl -X POST https://www.aicoo.io/api/v1/chat \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Summarize open priorities from my context", "stream": true }'

{"type":"text-delta","textDelta":"Here is your plan for today..."} {"type":"tool-call-start","toolName":"search_calendar_events","toolCallId":"call_123"} {"type":"completion","metadata":{"promptTokens":812,"completionTokens":191,"totalTokens":1003}}

Name

Type

Required

timeDuration

Time window label. Default is "last 24 hours".

body

string

emails

Optional normalized email input set.

body

Array<{ id?, summary?, priority?, category?, needsReply?, date?, sender?, snippet? }>

calendarEvents

Optional calendar event list.

body

Array<{ summary?, start, end, location?, description? }>

curl -X POST https://www.aicoo.io/api/v1/briefing \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "timeDuration": "last 24 hours", "emails": [{"summary": "Need response", "priority": 5, "needsReply": true}] }'

{ "success": true, "briefingId": 128, "statusQuoSummary": "<h3>Today's Focus</h3><ul><li>Finalize partner brief</li></ul>", "todoSummary": "<ul><li>Finish Q3 review</li></ul>", "calendarSummary": "<ul><li>Client sync at 2:00 PM</li></ul>", "notesSummary": "<ul><li>Roadmap draft updated</li></ul>", "emailAttentionSummary": "<ul><li>P5 - Investor follow-up required</li></ul>", "suggestions": [ { "title": "Reply to investor thread", "description": "Close open financing question before EOD", "action": "Send concise status update", "suggestionId": "a8f5f167-f44f-4f6f-b4af-555aa5c2e4c2" } ], "tokenUsage": { "total": 1422 } }

Name

Type

Required

statusQuoSummary

Main summary.

body

string

todoSummary

Todo summary.

body

string

calendarSummary

Calendar summary.

body

string

notesSummary

Notes summary.

body

string

emailAttentionSummary

Email summary.

body

string

curl -X POST https://www.aicoo.io/api/v1/briefing/strategies \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "statusQuoSummary": "Main blockers are...", "todoSummary": "Top tasks..." }'

{ "success": true, "strategies": [ { "priority": 1, "title": "Confirm launch dependencies", "description": "Resolve blockers from engineering and design", "urgencyLevel": "critical", "category": "action" } ], "generatedAt": "2026-04-10T09:30:00.000Z" }

Name

Type

Required

statusQuoSummary

Main summary.

body

string

todoSummary

Todo summary.

body

string

calendarSummary

Calendar summary.

body

string

notesSummary

Notes summary.

body

string

emailAttentionSummary

Email summary.

body

string

{ "success": true, "matrix": { "q1_urgent_important": [{ "title": "Client deadline today", "source": "email" }], "q2_not_urgent_important": [{ "title": "Q2 hiring plan", "source": "note" }], "q3_urgent_not_important": [{ "title": "Reschedule vendor demo", "source": "calendar" }], "q4_not_urgent_not_important": [] }, "generatedAt": "2026-04-10T09:30:00.000Z" }

Name

Type

Required

limit

Rows to return (default 10, max 50).

query

number

{ "success": true, "briefings": [ { "id": 128, "statusQuoSummary": "<h3>Today's Focus</h3><ul><li>...</li></ul>", "timeDuration": "last 24 hours", "generatedAt": "2026-04-10T09:12:00.000Z" } ] }

Name

Type

Required

limit

Rows to return (default 5, max 20).

query

number

{ "success": true, "notes": [ { "id": 42, "title": "Roadmap Decisions", "summary": "Decided to ship onboarding improvements first...", "updatedAt": "2026-04-10T08:22:00.000Z", "relativeTime": "2 hours ago", "pinned": true } ], "notesSummary": "<ul><li><strong>Roadmap Decisions</strong> [pinned] <span>(2 hours ago)</span></li></ul>" }