Skip to content
Kindgi

List compliance-evidence records

View as Markdown
GET
/v1/compliance/evidence
curl --request GET \
  --url 'https://example.com/v1/compliance/evidence?limit=25&kind=access-event' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Filters: ?runId= / ?agentId= / ?flowId= / ?kind= / ?from= / ?to= (all AND-composed). Fixed sort: timestamp asc, id asc — deterministic even when two records share a timestamp. Only mounted when CreateAppInput.auditEvents + CreateAppInput.complianceClassifier are both wired.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

runId
string

Filter to evidence records tied to this run id (exact match on provenanceRef.runId).

agentId
string

Filter to evidence records whose payload references this agent id.

flowId
string

Filter to evidence records whose payload references this flow id.

kind

Compliance-relevant event class. Open set: evidence is a classifier lens over the audit stream, and a deployment can mark any audit-event kind exportable. examples lists the built-in kinds; clients must tolerate kinds they do not know.

string
>= 1 characters

Filter by evidence kind: a built-in EvidenceKind, or a kind the classifier names. Any other kind is a 400. A kind the classifier does not mark exportable yields an empty page.

from
string format: date-time

ISO 8601 lower bound (inclusive) on timestamp.

to
string format: date-time

ISO 8601 upper bound (inclusive) on timestamp.

Responses

Section titled “Responses”

200

Section titled “200”

Page of compliance-evidence records.

Media typeapplication/json
object
data
required
Array<object>

One evidence record — matches @kindgi/specs/compliance-evidence.schema.json (payload is a versioned document opaque to the wire schema).

object
id
required
string
tenantId
required
string format: uuid
projectId

The project the underlying audit event belongs to. Absent for workspace-level events (e.g. authz decisions).

string format: uuid
kind
required

Compliance-relevant event class. Open set: evidence is a classifier lens over the audit stream, and a deployment can mark any audit-event kind exportable. examples lists the built-in kinds; clients must tolerate kinds they do not know.

string
>= 1 characters
timestamp
required
string format: date-time
actor
object
kind
string
Allowed values: user agent system admin external
id
string
ipAddress
string
userAgent
string
subject
object
kind
string
id
string
outcome
string
Allowed values: allowed denied succeeded failed escalated
payload
required

Kind-specific payload document. Always carries version for on-read migration; other fields vary by kind.

object
key
additional properties
any
provenanceRef
object
runId
string
nodeId
string
recordId
string
signature
object
algorithm
required
string
Allowed value: ed25519
keyId
required
string
value
required

Base64-encoded signature bytes.

string
signedAt
required
string format: date-time
hasMore
required
boolean
nextCursor
string
Example
{
  "data": [
    {
      "kind": "access-event",
      "actor": {
        "kind": "user"
      },
      "outcome": "allowed",
      "signature": {
        "algorithm": "ed25519"
      }
    }
  ]
}

400

Section titled “400”

Malformed cursor, from or to, or a kind that is no evidence kind.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

Not a tenant admin (permission-denied). Without an authorization store, a tenant admin is the deployment’s API token, an admin key, or a console signed in with either.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also