Aicoo API

Layer 1: Intro + API Key

Everything needed to authenticate and make your first successful API request.

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

Get API Key

Create a key from settings

2. Create a new key and copy the secret immediately.

3. Store it in your environment as `AICOO_API_KEY` (legacy `PULSE_API_KEY` also works).

export AICOO_API_KEY="aicoo_sk_live_..."

Authentication

Use Bearer auth on every request

All v1 routes are API-key protected. Include this header in each request.

Authorization: Bearer YOUR_API_KEY

Base URL

Path prefix for all endpoints

https://www.aicoo.io/api/v1

First Calls

Starter endpoints

Recommended first sequence: initialize workspace, then send first agent message.

POST/api/v1/init

Initialize Workspace

Idempotently initializes workspace state and returns folder/file totals.

Safe to call on every client bootstrap.
Ensures default /General folder exists.
Returns complete folder tree and total storage footprint.

Parameters

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

Request Example

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

Example Output

{
  "success": true,
  "initialized": true,
  "workspace": {
    "folders": [
      { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 3 }
    ],
    "totalFiles": 3,
    "totalSizeBytes": 24576
  }
}

POST/api/v1/chat

Send First Agent Message

Sends a message through the Aicoo Agent runtime.

Uses the same agent-v04 execution path as first-party product chat.
Streaming is enabled by default.
Supports conversation continuation via conversationId.

Parameters

Name	In	Type	Required
`message` Prompt text for the agent.	body	string	Yes
`userTimezone` IANA timezone. Defaults to UTC.	body	string	No
`stream` Set false to disable streaming response events.	body	boolean	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": "Give me a concise plan for today",
    "userTimezone": "America/New_York",
    "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}}

Rate Limits

Tier	Requests/min	Tokens/week
Free	10	1,200,000
Pro	60	6,000,000
Business	300	25,000,000

Common Errors

unauthorizedHTTP 401

Missing or invalid API key.

invalid_requestHTTP 400

Malformed JSON or input validation failed.

not_foundHTTP 404

Resource not found for authenticated user.

parse_errorHTTP 500

AI output could not be parsed into expected JSON shape.

server_errorHTTP 500

Unhandled server-side failure.

Next Layer

Move to Aicoo Agent docs

Continue with the dedicated Agent layer for chat and briefing endpoints.

Open Aicoo Agent layer

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

Name

Type

Required

No path/query/body parameters required.

{ "success": true, "initialized": true, "workspace": { "folders": [ { "id": 1, "name": "General", "parentId": null, "icon": null, "fileCount": 3 } ], "totalFiles": 3, "totalSizeBytes": 24576 } }

Name

Type

Required

message

Prompt text for the agent.

body

string

Yes

userTimezone

IANA timezone. Defaults to UTC.

body

string

stream

Set false to disable streaming response events.

body

boolean

curl -X POST https://www.aicoo.io/api/v1/chat \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Give me a concise plan for today", "userTimezone": "America/New_York", "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}}

Tier

Requests/min

Tokens/week

Free

1,200,000

Pro

6,000,000

Business

300

25,000,000