Files

Michilis 41f6ae916f first commit

Made-with: Cursor

2026-02-28 02:17:55 +00:00

11 KiB

Raw Blame History

Calendar & Contacts API

details.md

This document defines exact endpoint contracts: request/response schemas, field constraints, pagination formats, examples, and implementation notes so a developer can build the API and a frontend without guessing.

All timestamps are RFC3339 strings. All stored times are UTC.

1. Conventions

1.1 Base URL

Local: http://localhost:8080
Production: https://api.example.com

All endpoints are under the root path.

1.2 Authentication Headers

JWT:

Authorization: Bearer <access_token>

API key:

X-API-Key: <api_key_token>

If both are present, JWT takes precedence.

1.3 Standard Response Envelope

This API returns plain JSON objects. For list endpoints, a consistent list envelope is required.

List response envelope: { "items": [ ... ], "page": { "limit": 50, "next_cursor": "opaque-or-null" } }

1.4 Cursor Pagination

Query params:

limit (optional, default 50, max 200)
cursor (optional)

Cursor meaning:

Opaque base64url string encoding the tuple:
- last_sort_time (RFC3339)
- last_id (uuid)

Sorting rule for paginated lists:

Primary: start_time asc (or created_at for contacts)
Secondary: id asc

If cursor is provided:

Return records strictly greater than the tuple.

1.5 Error Format

All error responses: { "error": "Human readable message", "code": "MACHINE_READABLE_CODE", "details": "Optional string or object" }

HTTP mapping:

400 VALIDATION_ERROR
401 AUTH_REQUIRED / AUTH_INVALID
403 FORBIDDEN
404 NOT_FOUND
409 CONFLICT
429 RATE_LIMITED
500 INTERNAL

2. Data Schemas

2.1 User

{ "id": "uuid", "email": "string", "timezone": "string", "created_at": "RFC3339", "updated_at": "RFC3339" }

Constraints:

email lowercase
timezone must be IANA timezone name, default "UTC"

2.2 Calendar

{ "id": "uuid", "name": "string", "color": "string", "is_public": true, "role": "owner|editor|viewer", "created_at": "RFC3339", "updated_at": "RFC3339" }

Constraints:

name 1..80
color is hex like "#RRGGBB" (optional)

2.3 Event

{ "id": "uuid", "calendar_id": "uuid", "title": "string", "description": "string|null", "location": "string|null", "start_time": "RFC3339-UTC", "end_time": "RFC3339-UTC", "timezone": "string", "all_day": false, "recurrence_rule": "string|null", "created_by": "uuid", "updated_by": "uuid", "created_at": "RFC3339", "updated_at": "RFC3339", "reminders": [ {"id": "uuid", "minutes_before": 10} ], "attendees": [ {"id": "uuid", "user_id": "uuid|null", "email": "string|null", "status": "pending|accepted|declined|tentative"} ], "tags": ["string"], "attachments": [ {"id": "uuid", "file_url": "string"} ] }

Constraints:

title 1..140
timezone IANA name
recurrence_rule must be valid RFC5545 RRULE when present

2.4 Contact

{ "id": "uuid", "first_name": "string|null", "last_name": "string|null", "email": "string|null", "phone": "string|null", "company": "string|null", "notes": "string|null", "created_at": "RFC3339", "updated_at": "RFC3339" }

Constraints:

At least one of: first_name, last_name, email, phone must be present

3. Endpoint Contracts

3.1 Auth

POST /auth/register

Request: { "email": "user@example.com", "password": "string", "timezone": "America/Asuncion" }

Rules:

timezone optional
server creates default calendar

Response 200: { "user": { ...User }, "access_token": "string", "refresh_token": "string" }

Errors:

400 VALIDATION_ERROR
409 CONFLICT (email already exists)

POST /auth/login

Request: { "email": "user@example.com", "password": "string" }

Response 200: { "user": { ...User }, "access_token": "string", "refresh_token": "string" }

Errors:

401 AUTH_INVALID

POST /auth/refresh

Request: { "refresh_token": "string" }

Response 200: { "access_token": "string", "refresh_token": "string" }

Errors:

401 AUTH_INVALID

POST /auth/logout

Request: { "refresh_token": "string" }

Response 200: { "ok": true }

GET /auth/me

Response 200: { "user": { ...User } }

3.2 API Keys

POST /api-keys

Request: { "name": "My agent key", "scopes": { "calendars": ["read", "write"], "events": ["read", "write"], "contacts": ["read", "write"], "availability": ["read"], "booking": ["write"] } }

Response 200: { "id": "uuid", "name": "My agent key", "created_at": "RFC3339", "token": "RAW_TOKEN_RETURNED_ONCE" }

GET /api-keys

Response 200: { "items": [ {"id": "uuid", "name": "string", "created_at": "RFC3339", "revoked_at": "RFC3339|null"} ], "page": {"limit": 50, "next_cursor": null} }

DELETE /api-keys/{id}

Response 200: { "ok": true }

3.3 Users

GET /users/me

Response 200: { "user": { ...User } }

PUT /users/me

Request: { "timezone": "America/Asuncion" }

Response 200: { "user": { ...User } }

DELETE /users/me

Response 200: { "ok": true }

3.4 Calendars

GET /calendars

Response 200: { "items": [ ...Calendar ], "page": {"limit": 50, "next_cursor": null} }

POST /calendars

Request: { "name": "Work", "color": "#22C55E" }

Response 200: { "calendar": { ...Calendar } }

GET /calendars/{id}

Response 200: { "calendar": { ...Calendar } }

PUT /calendars/{id}

Request: { "name": "Work Calendar", "color": "#22C55E", "is_public": false }

Rules:

is_public only owner

Response 200: { "calendar": { ...Calendar } }

DELETE /calendars/{id}

Response 200: { "ok": true }

POST /calendars/{id}/share

Request: { "target": {"email": "other@example.com"}, "role": "editor" }

Response 200: { "ok": true }

GET /calendars/{id}/members

Response 200: { "items": [ {"user_id": "uuid", "email": "string", "role": "owner|editor|viewer"} ], "page": {"limit": 50, "next_cursor": null} }

DELETE /calendars/{id}/members/{user_id}

Response 200: { "ok": true }

3.6 Events

GET /events

Query:

start (required) RFC3339
end (required) RFC3339
calendar_id (optional)
search (optional)
tag (optional)
limit, cursor

Response 200: { "items": [ ...Event ], "page": {"limit": 50, "next_cursor": "string|null"} }

Notes:

Must include expanded recurrence occurrences inside requested range.
For recurrence expansion, include occurrences as separate items with:
- id = master event id
- occurrence_start_time, occurrence_end_time (recommended fields)

Recommended recurrence occurrence representation: { "id": "uuid-master", "is_occurrence": true, "occurrence_start_time": "RFC3339", "occurrence_end_time": "RFC3339", ...base event fields... }

POST /events

Request: { "calendar_id": "uuid", "title": "Meeting", "description": "Project sync", "location": "Zoom", "start_time": "2026-03-01T14:00:00-03:00", "end_time": "2026-03-01T15:00:00-03:00", "timezone": "America/Asuncion", "all_day": false, "recurrence_rule": null, "reminders": [10, 60], "tags": ["work", "sync"] }