Calendar & Scheduling
The Calendar API provides full control over events, legal deadlines (Fristen), meeting scheduling, and external calendar synchronization. It is the central hub for time management in Optimaite Law.
Base URL
https://api.optimaite.eu/api/v1/calendar
Authentication
All calendar endpoints require a valid API key with the calendar:read scope. Write operations require calendar:write.
Calendar Events
List Events
GET /api/v1/calendar/events?from=2026-01-01&to=2026-12-31&limit=50
Returns a paginated list of calendar events.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
from | ISO date | Start of date range (inclusive) |
to | ISO date | End of date range (inclusive) |
type | string | Filter: event, deadline, meeting |
case_id | UUID | Filter events for a specific case |
limit | integer | Max results per page (default 50) |
cursor | string | Pagination cursor |
Response:
{
"data": [
{
"id": "evt_550e8400",
"title": "Court Hearing -- Smith v. Jones",
"type": "event",
"start": "2026-03-15T10:00:00+01:00",
"end": "2026-03-15T12:00:00+01:00",
"all_day": false,
"case_id": "550e8400-e29b-41d4-a716-446655440000",
"location": "Landgericht Berlin",
"attendees": ["usr_abc123", "usr_def456"]
}
],
"pagination": { "has_more": false }
}
Create Event
POST /api/v1/calendar/events
Request Body:
{
"title": "Client Meeting",
"start": "2026-04-01T14:00:00+02:00",
"end": "2026-04-01T15:00:00+02:00",
"case_id": "550e8400-e29b-41d4-a716-446655440000",
"location": "Office Room 3",
"description": "Discuss settlement offer",
"attendees": ["usr_abc123"]
}
Update Event
PATCH /api/v1/calendar/events/{event_id}
Accepts partial updates. Only included fields are modified.
Delete Event
DELETE /api/v1/calendar/events/{event_id}
Legal Deadlines (Fristen)
List Fristen
GET /api/v1/calendar/fristen?status=open&case_id=550e8400
Returns legal deadlines with verification and delegation status.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
status | string | open, verified, expired, all |
case_id | UUID | Filter by case |
assigned_to | UUID | Filter by assignee |
Response:
{
"data": [
{
"id": "frist_001",
"title": "Statement of Defense",
"deadline": "2026-04-15T23:59:00+02:00",
"case_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "open",
"verified": false,
"chain_id": "chain_abc",
"assigned_to": "usr_abc123"
}
]
}
Verify Deadline
POST /api/v1/calendar/fristen/{id}/verify
Marks a deadline as dual-control verified (Vier-Augen-Prinzip).
Get Deadline Chain
GET /api/v1/calendar/fristen/{id}/chain
Returns all related deadlines in the chain (e.g., response deadline, counter-claim deadline).
Free/Busy & Scheduling
Free/Busy Query
POST /api/v1/calendar/availability/freebusy
Request Body:
{
"user_ids": ["usr_abc123", "usr_def456"],
"from": "2026-04-01T08:00:00+02:00",
"to": "2026-04-01T18:00:00+02:00"
}
Response:
{
"busy": [
{
"user_id": "usr_abc123",
"start": "2026-04-01T10:00:00+02:00",
"end": "2026-04-01T11:30:00+02:00"
}
]
}
Find Open Slots
POST /api/v1/calendar/availability/open-slots
Finds available time slots for a group of users within a date range.
iCal Feed
Create iCal Token
POST /api/v1/calendar/ical-tokens
Generates a secret token for subscribing to an iCal feed.
Response:
{
"id": "ical_tok_001",
"url": "https://api.optimaite.eu/api/v1/calendar/ical/feed?token=abc123...",
"created_at": "2026-05-27T10:00:00Z"
}
Revoke iCal Token
POST /api/v1/calendar/ical-tokens/{id}/revoke
External Calendar Sync
Sync Status
GET /api/v1/calendar/sync/status
Returns synchronization status for connected Google Calendar or Outlook accounts.
Push Event to External Calendar
POST /api/v1/calendar/sync/events/{id}/push
Pushes a specific event to the user's connected external calendar.
Error Codes
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_DATE_RANGE | from must be before to |
| 403 | AUTH_INSUFFICIENT_SCOPE | Missing calendar:read or calendar:write scope |
| 404 | EVENT_NOT_FOUND | Event does not exist |
| 409 | SLOT_CONFLICT | Event conflicts with an existing event |