Skip to content
calternal docs

List Events

GET
/api/v1/calendar/events
curl --request GET \
  --url https://example.com/api/v1/calendar/events \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User. It returns cached Events, with repeated Events expanded for the requested date range. It accepts from and to together and an optional time zone. Set fresh to request a refresh. It returns 400 for invalid dates or time zones, or 429 when refresh capacity is full. Route: /api/v1/calendar/events. Inputs: fresh, from, to, tz. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
fresh
boolean
from
string

First local date to include. Must be supplied with to.

to
string

Last local date to include. Must be supplied with from.

tz
string

IANA time-zone name used to select Event instances. When omitted: the X-Calternal-Timezone header, else the user’s timezone setting, else UTC.

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
as_of
string | null
items
required
Array<object>
object
all_day
required
boolean
calendar_id
required
string
end
string | null
etag
required
string
id
required
string
location
string | null
start
string | null
summary
required
string
tags
required
Array<string>
timezone
string | null
uid
string | null
updated_at
required
string
stale
required
boolean
truncated
required
boolean
Examplegenerated
{
  "as_of": "example",
  "items": [
    {
      "all_day": true,
      "calendar_id": "example",
      "end": "example",
      "etag": "example",
      "id": "example",
      "location": "example",
      "start": "example",
      "summary": "example",
      "tags": [
        "example"
      ],
      "timezone": "example",
      "uid": "example",
      "updated_at": "example"
    }
  ],
  "stale": true,
  "truncated": true
}

429

Section titled “429”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}