Create an organization tag
Creates a mutable classification definition in the calling organization. Labels are trimmed and case-insensitively unique among live tags; deleting a tag releases its label. The 201 response includes the created tag and its Location. An optional Idempotency-Key makes an ambiguous retry replay that original response. The tag, request fingerprint, and response commit atomically. The key is scoped to the verified tenant, principal, and matched operation and path; its fingerprint uses the method, canonical path, normalized query, and decoded effective body; reusing it for a different request returns 409 idempotency_conflict. An active matching request returns 409 idempotency_in_progress. Completed receipts last approximately 24 hours. Without a key, list tags before retrying after an ambiguous failure; labels are mutable and are not a replay identity.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
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.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization 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.
1Body
Request body for creating one organization-scoped tag definition. The organization always comes from the authenticated principal.
Display color in #RRGGBB form.
7^#[0-9A-Fa-f]{6}$"#14b8a6"
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.
1 - 32Optional operator-facing explanation of this classification, up to 280 characters.
280Response
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.
Display color in #RRGGBB form.
7^#[0-9A-Fa-f]{6}$"#14b8a6"
Server-assigned RFC 3339 timestamp of when the tag was created.
Display label, trimmed by the service. Unique case-insensitively among live tags in this organization.
1 - 32Organization that owns the tag. Server-assigned from the authenticated principal and never accepted as authority from the request body.
Server-assigned tag id (UUID).
Server-assigned RFC 3339 timestamp of the most recent definition update.
Optional operator-facing explanation of the classification, up to 280 characters.
280