API reference

Findings

Research findings the app has detected, such as gaps: read, resolve or dismiss.

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

get/workspaces/{workspace_id}/findings

List findings

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.
status	query	no	Filter by status (lowercase letters and underscores).
type	query	no	Filter by finding type.

Responses

200 A page of findings. (FindingList)
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, status or type. (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"
          },
          "status": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "person_ids": {
            "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)$"
            }
          },
          "record_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "dismissed": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "type",
          "status",
          "severity",
          "title",
          "description",
          "person_ids",
          "record_id",
          "dismissed",
          "created_at",
          "resolved_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}/findings/{finding_id}

Get a finding

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

Responses

200 The finding. (Finding)
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. Also: The finding does not exist or is not visible. (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": {
    "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"
    },
    "status": {
      "type": "string"
    },
    "severity": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "person_ids": {
      "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)$"
      }
    },
    "record_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "dismissed": {
      "type": "boolean"
    },
    "created_at": {
      "type": "string"
    },
    "resolved_at": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "type",
    "status",
    "severity",
    "title",
    "description",
    "person_ids",
    "record_id",
    "dismissed",
    "created_at",
    "resolved_at"
  ]
}

post/workspaces/{workspace_id}/findings/{finding_id}/resolve

Resolve a finding

The optional note is stored but not returned in v1. 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.
finding_id	path	yes	The finding 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)

{
  "type": "object",
  "properties": {
    "note": {
      "description": "Optional resolution note (max 2000 characters, newlines allowed). Stored with the finding; not returned by the API in v1.",
      "type": "string",
      "maxLength": 2000
    }
  },
  "additionalProperties": false
}

Responses

200 Resolved. (Ok)
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: The finding does not exist or is not visible. (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. Also: The finding is not active. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (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
    }
  },
  "required": [
    "ok"
  ]
}

post/workspaces/{workspace_id}/findings/{finding_id}/dismiss

Dismiss a finding

A dismissed finding is not created again. 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.
finding_id	path	yes	The finding 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)

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Responses

200 Dismissed. (Ok)
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: The finding does not exist or is not visible. (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. Also: The finding is not active. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (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
    }
  },
  "required": [
    "ok"
  ]
}