Create an event

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": "evt_…", "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" }

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}

Show child attributes

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

Response

The created event (carries created_by attribution).

string

Example:

"evt_…"

name

string

date

string<date>

recur

object

start_time

string

end_time

string

notes

string

Get started

Concepts

API reference

Authorizations

Headers

Path Parameters

Body

Response