API reference

Notifications

The notifications the app shows in a workspace: list them, count the unread ones, and mark them read.

Paths are relative to https://kleiobase.com/api/v1.

get/workspaces/{workspace_id}/notifications

List notifications

Newest first: this workspace's notifications plus account-wide ones (for example about credits), which appear in every workspace. At most 50 per page, whatever limit asks for. Keep following next_cursor.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
limit	query	no	Page size. Default 25, max 100.
cursor	query	no	The next_cursor of the previous page. Opaque.
unread	query	no	true for unread only.

Responses

200 A page of notifications. (NotificationList)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
422 Invalid limit, cursor or unread. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "type": {
            "type": "string",
            "description": "For example record_processed, match_found, research_finding, system. The set is open."
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "link_path": {
            "description": "The app page the notification points to, as a path (for example /knowledge-base/people/...). Null when there is none.",
            "type": [
              "string",
              "null"
            ]
          },
          "read_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "title",
          "body",
          "link_path",
          "read_at",
          "created_at"
        ]
      }
    },
    "next_cursor": {
      "description": "Pass as ?cursor to get the next page. Null on the last page.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "next_cursor"
  ]
}

get/workspaces/{workspace_id}/notifications/unread-count

Count unread notifications

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.

Responses

200 The count. (UnreadCount)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "count"
  ]
}

post/workspaces/{workspace_id}/notifications/read

Mark notifications read

Send { ids } (1 to 100) or { all: true }. With ids, all or nothing: every id must be a notification of this workspace (or account-wide); one already read is fine. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
Idempotency-Key	header	no	Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Request body (application/json, required)

{
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "ids": {
          "minItems": 1,
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          }
        }
      },
      "required": [
        "ids"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "all": {
          "type": "boolean",
          "const": true
        }
      },
      "required": [
        "all"
      ],
      "additionalProperties": false
    }
  ]
}

Responses

200 Marked. (NotificationsMarked)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. Also: One of the ids is not a notification visible in this workspace. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body. (ErrorResponse)
429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)

200 response schema

{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "marked": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many notifications changed from unread to read."
    }
  },
  "required": [
    "ok",
    "marked"
  ]
}