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"
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}Create an event
Three schedule kinds: one-off (date), recurring (recur), or someday (neither; a milestone without a date yet). Requires scope calendar:write and a writer/owner grant.
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"
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "<string>",
"details": {}
}
}Authorizations
Agent token from POST /v1/mint (format ac_agent_…). Scopes: agent:read, calendar:read, calendar:write, grants:manage.
Headers
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.
200Path Parameters
cal_… public id.
Body
YYYY-MM-DD for a one-off. Mutually exclusive with recur; omit both for a someday milestone.
{"type":"daily"} | {"type":"weekly","day":0-6 (0=Sunday)} | {"type":"monthly","date":1-31}
Show child attributes
Show child attributes
HH:MM 24h; absent = all-day.
^\d{2}:\d{2}$^\d{2}:\d{2}$4000One short lowercase word, e.g. release, deadline.
Plain text or sanitized HTML shown on the event page.
8000Response
The created event (carries created_by attribution).