Skip to content
calternal docs

Get Calendar activity for a year

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

Requires a signed-in User. It returns daily activity counts for the requested year and time zone. It returns 400 when the year or time zone is invalid. Route: /api/v1/calendar/year. Inputs: year, tz. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
year
required
integer format: int32
tz
string

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

Responses

Section titled “Responses”

200

Section titled “200”

Daily activity counts for a heat map

Media typeapplication/json
object
days
required
Array<object>
object
activity_count
required
integer format: int64
bookmark_count
required
integer format: int64
cover_photo
One of:
object
item_id
string | null
media_type
required
string
modified_at
required
string
name
required
string
owner_id
required
string
path
required
string
thumbnail_hash

Source BLAKE3 hash. The Files thumb route uses it to find the derived image.

string | null
date
required
string
event_color

First URL subscription’s chosen colour for its compact Event marker.

string | null
event_count
required
integer format: int64
event_tag

First Event’s first category, for the compact Year and mini-month dot.

string | null
file_count
required
integer format: int64
log_count
required
integer format: int64
note_count
required
integer format: int64
photo_count
required
integer format: int64
photo_day
required
boolean
tz
required
string
year
required
integer format: int32
Examplegenerated
{
  "days": [
    {
      "activity_count": 1,
      "bookmark_count": 1,
      "cover_photo": {
        "item_id": "example",
        "media_type": "example",
        "modified_at": "example",
        "name": "example",
        "owner_id": "example",
        "path": "example",
        "thumbnail_hash": "example"
      },
      "date": "example",
      "event_color": "example",
      "event_count": 1,
      "event_tag": "example",
      "file_count": 1,
      "log_count": 1,
      "note_count": 1,
      "photo_count": 1,
      "photo_day": true
    }
  ],
  "tz": "example",
  "year": 1
}

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"
  }
}