query_records

POST/entities/{entity_id}/records/query

Authorization

AuthorizationBearer <token>

A service principal's credential, or a person's access token, AgentFlow's own or an installed app's. A service principal's effective permissions are its role permissions intersected with the credential's scopes.

In: header

Path Parameters

entity_id*string

Entity id

Formatuuid

Request Body

application/json

The filters, sort, cursors and page size

TypeScript Definitions

Use the request body type in TypeScript.

The typed JSON body for POST /entities/{entityId}/records/query — the rich operator surface (multi-value / range / relative-date filters) beside the query-string GET. Absent filter fields default (an empty browse).

before?string|null

cursor?string|null

dir?null|

filter?

Record-browser filter set. Always scoped by org_id + entity_id first (those are path/route inputs, not part of the fingerprint). q is a text-contains search; field_filters are the picked field predicates; ref_filters are single-hop join predicates.

skip_serializing_if on every field keeps an absent filter hashing identically to a never-added one (cursor stability) — join predicates change result-set membership, so they must be part of the fingerprint.

include_actions?boolean

Resolve each row's visible actions (of any scope) into visible_action_ids. Off by default so nobody pays for the per-row predicate evaluation unless a view actually renders row actions. Not a filter, so it does not touch the cursor fingerprint — a page is the same page either way.

limit?|

Formatint32

Range0 <= value

scope?null|

sort?|

Field key, ref.field, or a system token (updated_at / created_at).

view_id?|

Project each row's body + label sidecars down to what this view can render, and cap file-id arrays at RECORD_LIST_FILE_CAP (the total rides in file_counts). Absent ⇒ the full redacted body, byte-identical to before the field existed. A transfer optimization, not a filter: it changes no row membership and rides OUTSIDE the cursor fingerprint, exactly like include_actions — cursors are interchangeable across projected and unprojected requests. Must name a non-detail view of THIS entity; anything else is a 422 rather than a silent full page, because the caller asked for a smaller wire shape and would otherwise never learn its binding is stale.

Formatuuid

Response Body

`application/json`

`application/problem+json`

curl -X POST "https://example.com/entities/497f6eca-6276-4993-bfeb-53cbbbba6f08/records/query" \  -H "Content-Type: application/json" \  -d '{}'

{  "items": [    {      "body": {},      "created_at": "2019-08-24T14:15:22Z",      "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",      "entity_id": "8161163a-f227-466f-bc01-090a01e80165",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",      "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",      "unit_id": "5becc822-b69e-4e66-a762-ad8e868dcab6",      "updated_at": "2019-08-24T14:15:22Z",      "version": 0,      "file_counts": {        "property1": 0,        "property2": 0      },      "file_labels": {        "property1": {          "property1": "string",          "property2": "string"        },        "property2": {          "property1": "string",          "property2": "string"        }      },      "mentions": {        "property1": {          "href": "string",          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "kind": "user",          "label": "string",          "state": "ok"        },        "property2": {          "href": "string",          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "kind": "user",          "label": "string",          "state": "ok"        }      },      "ref_labels": {        "property1": {          "property1": "string",          "property2": "string"        },        "property2": {          "property1": "string",          "property2": "string"        }      },      "unit": null,      "visible_action_ids": [        "f379d2c9-fe6d-4ba6-bf32-0c26891f05a3"      ]    }  ],  "next_cursor": "string",  "prev_cursor": "string"}

query_records

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

409application/problem+json

413application/problem+json

415application/problem+json

422application/problem+json

429application/problem+json

500application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`