# Variables

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



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

<ApiEndpoint>
  <ApiEndpointMain>
    ## List an AI team's variables [#list-an-ai-teams-variables]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/variables" scope="variables.team:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>
    </ApiParams>

    <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 list of [Variable](#variable) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of variables.
      </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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables \
          -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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables', {
          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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "variable",
          "id": "var_FfWaUwQBPtssmkpHrTLrC7",
          "name": "DEFAULT_BRANCH",
          "value": "main",
          "scope": "org",
          "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
          "created_at": "2026-09-02T10:15:00.000Z",
          "updated_at": null
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an AI team's variable [#create-an-ai-teams-variable]

    <ApiEndpointHeader method="POST" path="/v1/teams/{team_id}/variables" scope="variables.team:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Variable](#variable) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The variable.
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"STRIPE_API_KEY","value":"your-stripe-key"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'STRIPE_API_KEY', value: 'your-stripe-key' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "STRIPE_API_KEY", "value": "your-stripe-key"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an AI team's variable [#get-an-ai-teams-variable]

    <ApiEndpointHeader method="GET" path="/v1/teams/{team_id}/variables/{variable_id}" scope="variables.team:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <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 [Variable](#variable) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The variable.
      </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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \
          -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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          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/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Change an AI team's variable [#change-an-ai-teams-variable]

    <ApiEndpointHeader method="PATCH" path="/v1/teams/{team_id}/variables/{variable_id}" scope="variables.team:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Body parameters">
      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Variable](#variable) object.

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

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"value":"your-new-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ value: 'your-new-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"value": "your-new-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete an AI team's variable [#delete-an-ai-teams-variable]

    <ApiEndpointHeader method="DELETE" path="/v1/teams/{team_id}/variables/{variable_id}" scope="variables.team:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="team_id" type="string" required="true">
        An AI team id.
      </ApiParam>

      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Done.
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/teams/team_3kQ9vX2mR8tLpZ4wYc1aBd/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List organization variables [#list-organization-variables]

    <ApiEndpointHeader method="GET" path="/v1/variables" scope="variables.org:read" />

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>
    </ApiParams>

    <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 list of [Variable](#variable) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of variables.
      </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/variables \
          -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/variables', {
          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/variables",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "variable",
          "id": "var_FfWaUwQBPtssmkpHrTLrC7",
          "name": "DEFAULT_BRANCH",
          "value": "main",
          "scope": "org",
          "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
          "created_at": "2026-09-02T10:15:00.000Z",
          "updated_at": null
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create an org variable [#create-an-org-variable]

    <ApiEndpointHeader method="POST" path="/v1/variables" scope="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).

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="value" type="string" required="true" />

      <ApiParam name="scope" type="string">
        One of `org`, `selected`.
      </ApiParam>

      <ApiParam name="teams" type="array of string">
        With `scope: selected` only.
      </ApiParam>
    </ApiParams>

    **Returns** a [Variable](#variable) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The variable.
      </ApiParam>

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/variables \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"name":"GITHUB_TOKEN","value":"your-github-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ name: 'GITHUB_TOKEN', value: 'your-github-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/variables",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"name": "GITHUB_TOKEN", "value": "your-github-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get an organization variable [#get-an-organization-variable]

    <ApiEndpointHeader method="GET" path="/v1/variables/{variable_id}" scope="variables.org:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <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 [Variable](#variable) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The variable.
      </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/variables/var_FfWaUwQBPtssmkpHrTLrC7 \
          -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/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          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/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Change an org variable's value [#change-an-org-variables-value]

    <ApiEndpointHeader method="PATCH" path="/v1/variables/{variable_id}" scope="variables.org:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Body parameters">
      <ApiParam name="value" type="string" required="true" />
    </ApiParams>

    **Returns** a [Variable](#variable) object.

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

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

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7 \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"value":"your-new-token"}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ value: 'your-new-token' }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"value": "your-new-token"},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete an org variable [#delete-an-org-variable]

    <ApiEndpointHeader method="DELETE" path="/v1/variables/{variable_id}" scope="variables.org:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="variable_id" type="string" required="true">
        A variable id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        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.
      </ApiParam>

      <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>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Done.
      </ApiParam>

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

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

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/variables/var_FfWaUwQBPtssmkpHrTLrC7",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Done.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Variable [#variable]

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

      <ApiParam name="id" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="value" type="string" />

      <ApiParam name="scope" type="string">
        One of `org`, `team`.
      </ApiParam>

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

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="updated_at" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Variable object"
    {
      "object": "variable",
      "id": "var_FfWaUwQBPtssmkpHrTLrC7",
      "name": "DEFAULT_BRANCH",
      "value": "main",
      "scope": "org",
      "teams": ["team_3kQ9vX2mR8tLpZ4wYc1aBd"],
      "created_at": "2026-09-02T10:15:00.000Z",
      "updated_at": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
