Skip to content
calternal docs

List standalone Calendar items

GET
/api/v1/calendar/items
curl --request GET \
  --url 'https://example.com/api/v1/calendar/items?from=example&to=example&tz=example' \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User. It returns a time-ordered page of standalone Files, Photos, Notes and bookmarks for a date range. The range can be up to 42 days. It accepts a page size and cursor. It returns 400 for invalid dates, time zones, limits or cursors. Route: /api/v1/calendar/items. Inputs: from, to, tz, cursor, limit. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
from
required
string

First local date, inclusive.

to
required
string

Last local date, inclusive. At most 42 days after from.

tz
required
string

IANA time-zone name for the local days and times.

cursor
string

Opaque cursor from the previous page’s next_cursor.

limit
integer format: int32

Page size, 1 to 1000. Default 500.

Responses

Section titled “Responses”

200

Section titled “200”

Standalone files, photos, Notes and bookmarks in time order

Media typeapplication/json
object
from
required
string
items
required
Array<object>

One standalone item on the grid.

object
at
required

RFC 3339 time in the requested zone.

string
date
required

Local day in the requested zone.

string
item_id

Files item ID (/f/<id>, /p/<id>). Missing until Files adopts the file.

string | null
kind
required

photo, file, note or bookmark.

string
media_type
required
string
name
required

File name, or the Note or bookmark title.

string
note_id

The Note’s calternal-id (/n/<id>) for Notes and bookmarks.

string | null
owner_id
required
string
path
required

Home-relative path in the owner’s Home.

string
thumbnail_url

Files thumb route for supported media and documents. Document routes carry the renderer family from the Index, per #510/#547 and DESIGN §39. It can answer 404 until the thumbnail Job has run; clients keep the glyph then.

string | null
time
required

Local HH:MM in the requested zone.

string
time_source
required

taken when a photo sits at its capture time, else added.

string
Allowed values: taken added
url

Page address for a bookmark.

string | null
next_cursor

Pass as cursor to read the next page. None on the last page.

string | null
to
required
string
tz
required
string
Example
{
  "items": [
    {
      "time_source": "taken"
    }
  ]
}

400

Section titled “400”
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"
  }
}

403

Section titled “403”
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"
  }
}