Skip to main content
POST
Create a group

Authorizations

Authorization
string
header
required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Headers

Idempotency-Key
string

Returns the original response verbatim while the node still caches it. Correctness never depends on it.

Minimum string length: 1

Path Parameters

ns
string
required

A namespace name, or a template prefix ending in /* (§7.7), with any / sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.

A namespace name, or a template prefix: a namespace path ending in /*, such as acme/prod/*, which every namespace under acme/prod/ inherits judgments from (§7.7). Up to 256 bytes.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+(/\*)?$

Body

application/json

Relations (§6.5.3). A group definition.

name
string
required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
key
string
required

The attribute whose values the group is kept per, such as attributes.plan. A document with no value there belongs to no key value.

Pattern: ^attributes\.[A-Za-z0-9_-]+$
aggregate
object
required

Relations (§6.5.3). What the group keeps per key value, over the documents matching match, exact as of the last merge. At most 8 paths in total. quantiles keeps a mergeable sketch per path, which position reads and GET reports as p50, p90 and p99. count_where counts documents by plain judgments' answers, with the roll-up rules; sum and avg over answers are invalid_request.

match
object

Which documents count. All documents when absent.

keep_keys
string

A key value whose newest matching document was created longer ago than this is not live, and leaves the rows and the 1,000 cap. Defaults to 90d.

Pattern: ^[1-9][0-9]*[smhd]$

Response

The group, building, with its group_build job in job_id.

Relations (§6.5.3). A group, its status and, on get in a namespace, its rows.

name
string
required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
key
string
required
Pattern: ^attributes\.[A-Za-z0-9_-]+$
aggregate
object
required

Relations (§6.5.3). What the group keeps per key value, over the documents matching match, exact as of the last merge. At most 8 paths in total. quantiles keeps a mergeable sketch per path, which position reads and GET reports as p50, p90 and p99. count_where counts documents by plain judgments' answers, with the roll-up rules; sum and avg over answers are invalid_request.

keep_keys
string
required

A whole number and a unit (s, m, h or d), such as 7d or 1h.

Pattern: ^[1-9][0-9]*[smhd]$
status
enum<string>
required

building until its group_build job has computed the aggregates, then ready. Judgments that read it wait for it.

Available options:
building,
ready
created_at
string<date-time>
required

RFC 3339, UTC.

match
object

Entities, E1 (§6.5). Which documents something applies to, by their attributes. Each key is an attribute path; a value is equality, and a list of values is In, as in query filters. Keys combine with And.

template
string

Present when the group is inherited, the template prefix it comes from.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9._:/-]+(/\*)?$
job_id
string | null

The group_build job, while it runs.

readers
string[]

The judgments that read the group. Deleting it is conflict while there are any.

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
live_keys
integer | null

Live key values now; null on a template's prefix path.

Required range: x >= 0
warnings
enum<string>[]

group_over_cap: more than 1,000 live key values, so its readers read stale (group_over_cap) until key values age out past keep_keys.

Available options:
group_over_cap
as_of
integer<int64> | null

The seq of the merge the rows are exact at. Absent from lists and on a template's prefix path.

Required range: x >= 0
rows
object[] | null

On get in a namespace, one row per live key value, the largest count first. Null on a template's prefix path, absent from lists.

Maximum array length: 1000