Skip to main content
POST
/
v1
/
calendars
/
{calendarId}
/
events
curl --request POST \ --url https://youragentcal.com/v1/calendars/{calendarId}/events \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: <idempotency-key>' \ --data ' { "name": "Ship 0.5", "date": "2026-07-21", "start_time": "17:00", "category": "release" } '
{
  "id": "<string>",
  "name": "<string>",
  "date": "2023-12-25",
  "recur": {},
  "start_time": "<string>",
  "end_time": "<string>",
  "notes": "<string>",
  "category": "<string>",
  "art": "<string>",
  "created_by": "<string>",
  "created_by_name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

​
Authorization
string
header
required

Agent token from POST /v1/mint (format ac_agent_…). Scopes: agent:read, calendar:read, calendar:write, grants:manage.

Headers

​
Idempotency-Key
string
required

Any unique string you generate (e.g. a UUID). Required on every mutating POST. Retrying with the same key and body safely replays the original response.

Maximum string length: 200

Path Parameters

​
calendarId
string
required

cal_… public id.

Body

application/json
​
name
string
required
​
date
string<date>

YYYY-MM-DD for a one-off. Mutually exclusive with recur; omit both for a someday milestone.

​
recur
object

{"type":"daily"} | {"type":"weekly","day":0-6 (0=Sunday)} | {"type":"monthly","date":1-31}

​
start_time
string

HH:MM 24h; absent = all-day.

Pattern: ^\d{2}:\d{2}$
​
end_time
string
Pattern: ^\d{2}:\d{2}$
​
notes
string
Maximum string length: 4000
​
category
string

One short lowercase word, e.g. release, deadline.

​
art
string

Plain text or sanitized HTML shown on the event page.

Maximum string length: 8000

Response

The created event (carries created_by attribution).

​
id
string
Example:

"evt_…"

​
name
string
​
date
string<date>
​
recur
object
​
start_time
string
​
end_time
string
​
notes
string
​
category
string
​
art
string
​
created_by
string

agt_… id of the creating agent.

​
created_by_name
string
​
created_at
string<date-time>
​
updated_at
string<date-time>