# Essentials

Health, the contract itself, and the calling credential.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## Check the API is up [#check-the-api-is-up]

    <ApiEndpointHeader method="GET" path="/v1/health" access="none" />

    No credential needed. `version` is the deployed build.

    **Returns** a [Health](#health) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The API is serving.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/health
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/health');
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import requests

        res = requests.get("https://api-hq.aiworkforceone.com/v1/health")
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "ok": true,
      "version": "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get this contract [#get-this-contract]

    <ApiEndpointHeader method="GET" path="/v1/openapi.json" access="none" />

    The OpenAPI 3.1 document this server implements, as JSON. No credential needed.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The OpenAPI document.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/openapi.json
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/openapi.json');
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import requests

        res = requests.get("https://api-hq.aiworkforceone.com/v1/openapi.json")
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="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": {}
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Describe the calling key [#describe-the-calling-key]

    <ApiEndpointHeader method="GET" path="/v1/me" access="key" />

    The key making this request, its organization, scopes, version and expiry.

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        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.
      </ApiParam>
    </ApiParams>

    **Returns** a [Credential](#credential) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The calling credential.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/me \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        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());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        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())
        ```
      </Tab>
    </Tabs>

    ```json title="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"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Health [#health]

    <ApiParams title="Attributes">
      <ApiParam name="ok" type="boolean" required="true" />

      <ApiParam name="version" type="string" required="true">
        The deployed image digest.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Health object"
    {
      "ok": true,
      "version": "sha256:4f2a9c81d3b7e6052a1f8c4d9e3b7a6f0c2d5e8b1a4f7c9d2e6b3a8f1c5d7e90"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Credential [#credential]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string">
        The key's id (`key_…`), or for an OAuth app the grant's (`grant_…`).
      </ApiParam>

      <ApiParam name="kind" type="string">
        Open-ended; more credential kinds may be added.
      </ApiParam>

      <ApiParam name="name" type="string">
        The key's name, or the OAuth app's.
      </ApiParam>

      <ApiParam name="app" type="object">
        Present for an OAuth app only.
      </ApiParam>

      <ApiParam name="org" type="object">
        The organization this request acts in. For an agency key, the client named in HQ-Account.
      </ApiParam>

      <ApiParam name="agency" type="object">
        Present for an agency key only. The agency the key belongs to.
      </ApiParam>

      <ApiParam name="acting_user" type="object or null">
        The member a user key or an OAuth app acts as. Null for a service key or an agency key.
      </ApiParam>

      <ApiParam name="role" type="string or null">
        A service key's role, or an agency key's (always sys:admin).
      </ApiParam>

      <ApiParam name="scopes" type="array of string" />

      <ApiParam name="team_scope" type="string">
        One of `all`, `selected`.
      </ApiParam>

      <ApiParam name="teams" type="array of string or null" />

      <ApiParam name="api_version" type="string (date)" />

      <ApiParam name="expires_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="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"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
