---
title: "Create a global variable"
method: POST
path: "/api/v1/synthetics/variables"
tags: ["Synthetics"]
---

# Create a global variable

`POST /api/v1/synthetics/variables`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v1/synthetics/variables`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `synthetics_global_variable_write`

Create a Synthetic global variable.

## Request body

- SyntheticsGlobalVariableRequest: Details of the global variable to create.
  - `attributes` SyntheticsGlobalVariableAttributes: Attributes of the global variable.
    - `restricted_roles` string[]: A list of role identifiers that can be pulled from the Roles API, for restricting read and write access. This field is deprecated. Use the restriction policies API to manage permissions.
  - `description` string, required: Description of the global variable.
  - `id` string: Unique identifier of the global variable.
  - `is_fido` boolean: Determines if the global variable is a FIDO variable.
  - `is_totp` boolean: Determines if the global variable is a TOTP/MFA variable.
  - `name` string, required: Name of the global variable. Unique across Synthetic global variables.
  - `parse_test_options` SyntheticsGlobalVariableParseTestOptions: Parser options to use for retrieving a Synthetic global variable from a Synthetic test. Used in conjunction with `parse_test_public_id`.
    - `field` string: When type is `http_header`, name of the header to use to extract the value.
    - `localVariableName` string: When type is `local_variable`, name of the local variable to use to extract the value.
    - `parser` SyntheticsVariableParser: Details of the parser to use for the global variable.
      - `type` 'raw' | 'json_path' | 'regex' | 'x_path', required: Type of parser for a Synthetic global variable from a synthetics test.
      - `value` string: Regex or JSON path used for the parser. Not used with type `raw`.
    - `type` 'http_body' | 'http_header' | 'http_status_code' | 'local_variable', required: Type of value to extract from a test for a Synthetic global variable.
  - `parse_test_public_id` string: A Synthetic test ID to use as a test to generate the variable value.
  - `tags` string[], required: Tags of the global variable.
  - `value` SyntheticsGlobalVariableValue: Value of the global variable.
    - `options` SyntheticsGlobalVariableOptions: Options for the Global Variable for MFA.
      - `totp_parameters` SyntheticsGlobalVariableTOTPParameters: Parameters for the TOTP/MFA variable
        - `digits` integer: Number of digits for the OTP code.
        - `refresh_interval` integer: Interval for which to refresh the token (in seconds).
    - `secure` boolean: Determines if the value of the variable is hidden.
    - `value` string: Value of the global variable. When reading a global variable, the value will not be present if the variable is hidden with the `secure` property.

## Response `200`

OK

- SyntheticsGlobalVariable: Synthetic global variable.
  - `attributes` SyntheticsGlobalVariableAttributes: Attributes of the global variable.
    - `restricted_roles` string[]: A list of role identifiers that can be pulled from the Roles API, for restricting read and write access. This field is deprecated. Use the restriction policies API to manage permissions.
  - `description` string, required: Description of the global variable.
  - `id` string: Unique identifier of the global variable.
  - `is_fido` boolean: Determines if the global variable is a FIDO variable.
  - `is_totp` boolean: Determines if the global variable is a TOTP/MFA variable.
  - `name` string, required: Name of the global variable. Unique across Synthetic global variables.
  - `parse_test_options` SyntheticsGlobalVariableParseTestOptions: Parser options to use for retrieving a Synthetic global variable from a Synthetic test. Used in conjunction with `parse_test_public_id`.
    - `field` string: When type is `http_header`, name of the header to use to extract the value.
    - `localVariableName` string: When type is `local_variable`, name of the local variable to use to extract the value.
    - `parser` SyntheticsVariableParser: Details of the parser to use for the global variable.
      - `type` 'raw' | 'json_path' | 'regex' | 'x_path', required: Type of parser for a Synthetic global variable from a synthetics test.
      - `value` string: Regex or JSON path used for the parser. Not used with type `raw`.
    - `type` 'http_body' | 'http_header' | 'http_status_code' | 'local_variable', required: Type of value to extract from a test for a Synthetic global variable.
  - `parse_test_public_id` string: A Synthetic test ID to use as a test to generate the variable value.
  - `tags` string[], required: Tags of the global variable.
  - `value` SyntheticsGlobalVariableValue, required: Value of the global variable.
    - `options` SyntheticsGlobalVariableOptions: Options for the Global Variable for MFA.
      - `totp_parameters` SyntheticsGlobalVariableTOTPParameters: Parameters for the TOTP/MFA variable
        - `digits` integer: Number of digits for the OTP code.
        - `refresh_interval` integer: Interval for which to refresh the token (in seconds).
    - `secure` boolean: Determines if the value of the variable is hidden.
    - `value` string: Value of the global variable. When reading a global variable, the value will not be present if the variable is hidden with the `secure` property.

## Other responses

- `400`: Invalid request
- `403`: Forbidden
- `409`: Conflict
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v1-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v1-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v1-collection/revisions/ca5871004d26?raw)