API reference

Notifications

3 endpoints

The in-app bell for the seats on the account, not a delivery channel of its own. Every list and every mark-read answers with the live unread_count alongside, so a client never has to count for itself.

Trip reminder scheduling is a different thing and lives at GET /api/v1/trips/{trip_id}/notifications.

List bell notifications

GET/api/v1/notifications

Needs a key with the full scope.

Newest first, scoped to the company the key's principal is reading.

Parameters

Query

limitintegerdefault 25
Rows per page.
cursorstring
Opaque; take it from the previous response's page.next_cursor.

Response · 200

dataobject[]required
Show fieldsHide fields
- iduuid
- categorystring
- titlestring
- bodystringnullable
- action_urlstringnullable
  Where the bell row points, relative to the app host.
- read_atdate-timenullable
- created_atdate-time
pageobjectrequired
The cursor for the list beside it. Re-send the same request with ?cursor=<next_cursor> while has_more is true. next_cursor is null on the last page.
Show fieldsHide fields
- next_cursorstringrequirednullable
- has_morebooleanrequired
- limitintegerrequired
unread_countintegerrequired

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
429Rate limit exceeded

curl -X GET 'https://YOUR-CELL.lydira.com/api/v1/notifications' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/notifications",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.get(
    "https://YOUR-CELL.lydira.com/api/v1/notifications",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/notifications")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/notifications");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": [
    {
      "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "category": "booking",
      "title": "Cappadocia, 4 nights",
      "body": "Guest asked for a late checkout.",
      "action_url": "/trips/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
      "read_at": "2026-03-14T09:30:00Z",
      "created_at": "2026-03-14T09:30:00Z"
    }
  ],
  "page": {
    "next_cursor": "MjAyNi0wMy0xNFQwOTozMDowMC4wMDAwMDBafDk0MQ",
    "has_more": true,
    "limit": 25
  },
  "unread_count": 3
}

Mark one read

POST/api/v1/notifications/{id}/mark_read

Needs a key with the full scope.

Parameters

Path

iduuidrequired

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Response · 200

dataobjectrequired
Show fieldsHide fields
- iduuid
- categorystring
- titlestring
- bodystringnullable
- action_urlstringnullable
  Where the bell row points, relative to the app host.
- read_atdate-timenullable
- created_atdate-time
- company_iduuidnullable
- metadataobjectnullable
unread_countintegerrequired

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
404Resource not found
429Rate limit exceeded

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/notifications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/notifications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/notifications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/notifications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/notifications/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18/mark_read");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "data": {
    "id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "category": "booking",
    "title": "Cappadocia, 4 nights",
    "body": "Guest asked for a late checkout.",
    "action_url": "/trips/9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "read_at": "2026-03-14T09:30:00Z",
    "created_at": "2026-03-14T09:30:00Z",
    "company_id": "9d2f7c3a-1b4e-4a7d-8e51-2c0f6b9a4d18",
    "metadata": {}
  },
  "unread_count": 3
}

Mark everything read

POST/api/v1/notifications/mark_all_read

Needs a key with the full scope.

Answers with the new count, which is always 0.

Parameters

Headers

Idempotency-Keystring
Your own unique string for this write (a UUID is the obvious choice), max 255 characters. Optional: omit it and nothing changes. Send it and a repeat of the same request returns this call's response verbatim, with Idempotent-Replay: true, instead of writing again.

Response · 200

unread_countintegerrequired

Responses

401Missing or invalid Bearer token
403Policy denied or account has no owner
429Rate limit exceeded

curl -X POST 'https://YOUR-CELL.lydira.com/api/v1/notifications/mark_all_read' \
  -H 'Authorization: Bearer sek_YOUR_API_KEY' \
  -H 'Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90'

const response = await fetch(
  "https://YOUR-CELL.lydira.com/api/v1/notifications/mark_all_read",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sek_YOUR_API_KEY",
      "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
  },
);

if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const data = await response.json();

import requests

response = requests.post(
    "https://YOUR-CELL.lydira.com/api/v1/notifications/mark_all_read",
    headers={
        "Authorization": "Bearer sek_YOUR_API_KEY",
        "Idempotency-Key": "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    },
)
response.raise_for_status()
data = response.json()

require "net/http"
require "json"

uri = URI("https://YOUR-CELL.lydira.com/api/v1/notifications/mark_all_read")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer sek_YOUR_API_KEY"
request["Idempotency-Key"] = "8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { it.request(request) }
raise response.body unless response.is_a?(Net::HTTPSuccess)
data = JSON.parse(response.body)

<?php
$ch = curl_init("https://YOUR-CELL.lydira.com/api/v1/notifications/mark_all_read");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer sek_YOUR_API_KEY",
        "Idempotency-Key: 8f14e45f-ea2c-4f33-9a3b-6d0c1b7e5a90",
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response

200

{
  "unread_count": 0
}