Skip to main content
POST
TypeScript SDK

Authorizations

x-api-key
string
header
required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

Body

application/json

POST /v1/groups — register a new group.

The prompt is the instruction the ingest classifier reads on every ingest to decide whether an extracted memory belongs in this group. Write it as a description of what belongs, not a chat instruction — e.g. "Facts about the Tokyo trip: dates, flights, hotels, dietary preferences for Tokyo", not "tag this if you think it should be tagged".

Omit prompt (or send null) to create a catch-all group: every extracted memory the classifier judges shareable (not personal) is tagged with it — no per-group matching. Sending an empty string is still a 422; only omission/null means catch-all, so a blank field from a buggy client can't silently create one.

name
string
required

Human-readable label, shown in UI. Not used by the classifier.

Required string length: 1 - 120
Example:

"Tokyo trip 2026"

prompt
string | null

Free-text criterion the ingest classifier reads to decide whether an extracted memory belongs in this group. Describe what belongs, not how the classifier should behave. Omit (or send null) to make the group a catch-all: every extracted memory judged shareable (not personal) is tagged with it, with no per-group matching.

Required string length: 1 - 2000
Example:

"Facts about the Tokyo trip in May 2026: dates, flights, hotels, restaurants, dietary preferences for this trip."

Response

Successful Response

Wire shape of a group. id is the opaque handle that goes into IngestRequest.group_ids and into search filters.

id
string
required

Stable group id of the form grp_<32-hex-chars>.

Example:

"grp_a1b2c3d4e5f6071829304a5b6c7d8e9f"

name
string
required

Human-readable label.

status
enum<string>
required

active groups are tagged on new ingests. archived groups still surface on search (rows tagged with the id stay reachable) but the ingest classifier rejects them.

Available options:
active,
archived
created_at
string<date-time>
required

ISO-8601 timestamp the group was registered.

object
string
default:group

Constant discriminator for the resource type.

Allowed value: "group"
prompt
string | null

Classifier criterion. Read by the ingest pipeline on every request that includes this group's id in group_ids. null marks a catch-all group: every extracted memory judged shareable (not personal) is tagged with it.

updated_at
string<date-time>

ISO-8601 timestamp of the most recent edit.