Skip to main content
POST
Create an organization tag

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string

Optional replay-protection key scoped to the verified tenant, principal, and managedAgentsCreateTag operation and path. Send one header value of 1 to 256 visible ASCII characters. The request fingerprint uses the method, canonical path, normalized query, and decoded effective body; equivalent JSON formatting and field order produce the same fingerprint. The same create replays the original successful response; a different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts last approximately 24 hours; pending claims may be reclaimed after approximately 1 hour. No deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Body

application/json

Request body for creating one organization-scoped tag definition. The organization always comes from the authenticated principal.

color
string
required

Display color in #RRGGBB form.

Required string length: 7
Pattern: ^#[0-9A-Fa-f]{6}$
Example:

"#14b8a6"

label
string
required

Display label. Leading and trailing whitespace is removed; the result must contain 1-32 characters and be unique case-insensitively among live tags in the organization.

Required string length: 1 - 32
description
string
default:""

Optional operator-facing explanation of this classification, up to 280 characters.

Maximum string length: 280

Response

An organization-scoped classification definition. Applying or removing it changes only catalog membership: it does not update the agent, mint an AgentVersion, or affect running sessions.

An organization-scoped classification definition. Applying or removing it changes only catalog membership: it does not update the agent, mint an AgentVersion, or affect running sessions.

color
string
required

Display color in #RRGGBB form.

Required string length: 7
Pattern: ^#[0-9A-Fa-f]{6}$
Example:

"#14b8a6"

created_at
string<date-time>
required
read-only

Server-assigned RFC 3339 timestamp of when the tag was created.

label
string
required

Display label, trimmed by the service. Unique case-insensitively among live tags in this organization.

Required string length: 1 - 32
organization_id
string
required
read-only

Organization that owns the tag. Server-assigned from the authenticated principal and never accepted as authority from the request body.

tag_id
string<uuid>
required
read-only

Server-assigned tag id (UUID).

updated_at
string<date-time>
required
read-only

Server-assigned RFC 3339 timestamp of the most recent definition update.

description
string

Optional operator-facing explanation of the classification, up to 280 characters.

Maximum string length: 280