Developers / API / Essentials Health, the contract itself, and the calling credential.
Check the API is up No credential needed. version is the deployed build.
Returns a Health object.
Responses
OtherAn RFC 9457 problem.
cURL JavaScript Python
curl https://api-hq.aiworkforceone.com/v1/health const res = await fetch ( 'https://api-hq.aiworkforceone.com/v1/health' );
console .log ( await res .json ()); import requests
res = requests . get ( "https://api-hq.aiworkforceone.com/v1/health" )
print (res. json ()) Response 200
{
"ok" : true ,
"version" : "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90"
}
Get this contract The OpenAPI 3.1 document this server implements, as JSON. No credential needed.
Responses
OtherAn RFC 9457 problem.
cURL JavaScript Python
curl https://api-hq.aiworkforceone.com/v1/openapi.json const res = await fetch ( 'https://api-hq.aiworkforceone.com/v1/openapi.json' );
console .log ( await res .json ()); import requests
res = requests . get ( "https://api-hq.aiworkforceone.com/v1/openapi.json" )
print (res. json ()) Response 200
{
"openapi" : "3.1.0" ,
"info" : {
"title" : "AI Workforce One HQ API" ,
"version" : "2026-11-01"
} ,
"servers" : [
{
"url" : "https://api-hq.aiworkforceone.com/v1"
}
] ,
"paths" : {
"/health" : {}
}
}
Describe the calling key The key making this request, its organization, scopes, version and expiry.
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 Credential object.
Responses
200The calling credential.
OtherAn RFC 9457 problem.
cURL JavaScript Python
curl https://api-hq.aiworkforceone.com/v1/me \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "HQ-Version: 2026-11-01" const res = await fetch ( 'https://api-hq.aiworkforceone.com/v1/me' , {
headers : {
Authorization : `Bearer ${ process .env[ 'HQ_API_KEY' ] } ` ,
'HQ-Version' : '2026-11-01' ,
} ,
});
console .log ( await res .json ()); import os
import requests
res = requests . get (
"https://api-hq.aiworkforceone.com/v1/me" ,
headers = {
"Authorization" : f "Bearer { os.environ[ 'HQ_API_KEY' ] } " ,
"HQ-Version" : "2026-11-01" ,
},
)
print (res. json ()) Response 200
{
"object" : "credential" ,
"id" : "key_ff7QejQ24AGmu5tv2IXIdw" ,
"kind" : "user_key" ,
"name" : "CI deploy bot" ,
"org" : {
"id" : "org_3SvwLF4ulih8bHz5KtmNOO" ,
"slug" : "acme"
} ,
"acting_user" : {
"id" : "user_yFfQdB3rxA41x3cTD5fx2Q" ,
"email" : "maya.chen@example.com"
} ,
"role" : null ,
"scopes" : [ "teams:read" , "sessions:read" , "sessions:chat.read" ] ,
"team_scope" : "all" ,
"teams" : null ,
"api_version" : "2026-11-01" ,
"expires_at" : "2027-10-01T00:00:00.000Z"
}
Objects
Health Attributes
okboolean required versionstring required The deployed image digest.
The Health object
{
"ok" : true ,
"version" : "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90"
}
Credential Attributes
objectstring idstring The key's id (key_…), or for an OAuth app the grant's (grant_…).
kindstring Open-ended; more credential kinds may be added.
namestring The key's name, or the OAuth app's.
appobject Present for an OAuth app only.
orgobject The organization this request acts in. For an agency key, the client named in HQ-Account.
agencyobject Present for an agency key only. The agency the key belongs to.
acting_userobject or null The member a user key or an OAuth app acts as. Null for a service key or an agency key.
rolestring or null A service key's role, or an agency key's (always sys:admin).
scopesarray of string team_scopestring One of all, selected.
teamsarray of string or null
api_versionstring (date)
expires_atstring (date-time) The Credential object
{
"object" : "credential" ,
"id" : "key_ff7QejQ24AGmu5tv2IXIdw" ,
"kind" : "user_key" ,
"name" : "CI deploy bot" ,
"org" : {
"id" : "org_3SvwLF4ulih8bHz5KtmNOO" ,
"slug" : "acme"
} ,
"acting_user" : {
"id" : "user_yFfQdB3rxA41x3cTD5fx2Q" ,
"email" : "maya.chen@example.com"
} ,
"role" : null ,
"scopes" : [ "teams:read" , "sessions:read" , "sessions:chat.read" ] ,
"team_scope" : "all" ,
"teams" : null ,
"api_version" : "2026-11-01" ,
"expires_at" : "2027-10-01T00:00:00.000Z"
} ← Previous API referenceNext → API keysWas this page helpful? Yes No