AI Workforce OneHQDocs

Variables

Plain configuration values, organization-wide and per AI team.

List an AI team's variables

GET/v1/teams/{team_id}/variables
Permission variables.team:read
Path parameters
team_idstringrequired

An AI team id.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a list of Variable objects.

Responses
200

A page of variables.

Other

An RFC 9457 problem.

Create an AI team's variable

POST/v1/teams/{team_id}/variables
Permission variables.team:write
Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Body parameters
namestringrequired
valuestringrequired

Returns a Variable object.

Responses
201

The variable.

Other

An RFC 9457 problem.

Get an AI team's variable

GET/v1/teams/{team_id}/variables/{variable_id}
Permission variables.team:read
Path parameters
team_idstringrequired

An AI team id.

variable_idstringrequired

A variable id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a Variable object.

Responses
200

The variable.

Other

An RFC 9457 problem.

Change an AI team's variable

PATCH/v1/teams/{team_id}/variables/{variable_id}
Permission variables.team:write
Path parameters
team_idstringrequired

An AI team id.

variable_idstringrequired

A variable id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Body parameters
valuestringrequired

Returns a Variable object.

Responses
200

The variable.

Other

An RFC 9457 problem.

Delete an AI team's variable

DELETE/v1/teams/{team_id}/variables/{variable_id}
Permission variables.team:write
Path parameters
team_idstringrequired

An AI team id.

variable_idstringrequired

A variable id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Responses
204

Done.

Other

An RFC 9457 problem.

List organization variables

GET/v1/variables
Permission variables.org:read
Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a list of Variable objects.

Responses
200

A page of variables.

Other

An RFC 9457 problem.

Create an org variable

POST/v1/variables
Permission variables.org:write

A key restricted to some AI teams creates only selected variables, for teams inside its restriction (an org-wide one is 403 team_restricted, another team 404).

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Body parameters
namestringrequired
valuestringrequired
scopestring

One of org, selected.

teamsarray of string

With scope: selected only.

Returns a Variable object.

Responses
201

The variable.

Other

An RFC 9457 problem.

Get an organization variable

GET/v1/variables/{variable_id}
Permission variables.org:read
Path parameters
variable_idstringrequired

A variable id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a Variable object.

Responses
200

The variable.

Other

An RFC 9457 problem.

Change an org variable's value

PATCH/v1/variables/{variable_id}
Permission variables.org:write
Path parameters
variable_idstringrequired

A variable id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Body parameters
valuestringrequired

Returns a Variable object.

Responses
200

The variable.

Other

An RFC 9457 problem.

Delete an org variable

DELETE/v1/variables/{variable_id}
Permission variables.org:write
Path parameters
variable_idstringrequired

A variable id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Responses
204

Done.

Other

An RFC 9457 problem.

Objects

Variable

Attributes
objectstring
idstring
namestring
valuestring
scopestring

One of org, team.

teamsarray of string
created_atstring (date-time)
updated_atstring or null