> This page is for API Reference.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Update a design token by ID

PUT https://api.contentful.com/spaces/{spaceId}/environments/{environmentId}/design_tokens/{id}
Content-Type: application/json

Updates a design token by ID, or creates a new one with the specified ID if the design token does not exist.

Reference: https://contentful.com/developers/docs/references/experience-management-api/design-tokens/upsert-design-token

## Authentication

- `Authorization` header (bearer token, required) — Contentful Management API token

## Request

### Path parameters

- `spaceId` (string, required)
- `environmentId` (string, required)
- `id` (string, required)

### Query parameters

- `access_token` (string, optional)

### Body (application/json)

This endpoint expects an object.

- `name` (string, required)
- `type` (enum, required)
  - Allowed values: `DTCG.Color`, `DTCG.Dimension`, `DTCG.FontFamily`, `DTCG.FontWeight`, `DTCG.Duration`, `DTCG.CubicBezier`, `DTCG.Number`, `DTCG.StrokeStyle`, `DTCG.Border`, `DTCG.Transition`, `DTCG.Shadow`, `DTCG.Gradient`, `DTCG.Typography`
- `metadata` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadata, optional)

## Response

### 200

200

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `name` (string, required)
- `type` (enum, required)
  - Allowed values: `DTCG.Color`, `DTCG.Dimension`, `DTCG.FontFamily`, `DTCG.FontWeight`, `DTCG.Duration`, `DTCG.CubicBezier`, `DTCG.Number`, `DTCG.StrokeStyle`, `DTCG.Border`, `DTCG.Transition`, `DTCG.Shadow`, `DTCG.Gradient`, `DTCG.Typography`
- `metadata` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadata, optional)

### 201

201

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `name` (string, required)
- `type` (enum, required)
  - Allowed values: `DTCG.Color`, `DTCG.Dimension`, `DTCG.FontFamily`, `DTCG.FontWeight`, `DTCG.Duration`, `DTCG.CubicBezier`, `DTCG.Number`, `DTCG.StrokeStyle`, `DTCG.Border`, `DTCG.Transition`, `DTCG.Shadow`, `DTCG.Gradient`, `DTCG.Typography`
- `metadata` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadata, optional)

## Errors

### 400 Bad Request Error

400

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 401 Unauthorized Error

401

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 403 Forbidden Error

403

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 404 Not Found Error

404

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 409 Conflict Error

409

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 422 Unprocessable Entity Error

422

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 500 Internal Server Error

500

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

### 503 Service Unavailable Error

503

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys, required)
- `message` (string, optional)
- `requestId` (string, optional)
- `details` (any, optional)
- `i18nContext` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext, optional)

## Types

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadata

- `tags` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataTagsItems, optional)
- `concepts` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataConceptsItems, optional)
- `annotations` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotations, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaSys

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `Error`

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadata

- `tags` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataTagsItems, optional)
- `concepts` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataConceptsItems, optional)
- `annotations` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotations, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContext

- `code` (string, required)
- `pluralCount` (double, optional)
- `parameters` (map from string to SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataTagsItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataTagsItemsSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataConceptsItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataConceptsItemsSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotations

- `DesignSystem` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystem, optional)
- `ComponentType` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItems, optional, nullable)
- `Template` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsTemplateItems, optional, nullable)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataTagsItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataTagsItemsSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataConceptsItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataConceptsItemsSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotations

- `DesignSystem` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystem, optional)
- `ComponentType` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItems, optional, nullable)
- `Template` (list of SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsTemplateItems, optional, nullable)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters

- SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters0
- SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters1
- SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters2
- SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters3
- SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters4

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataTagsItemsSys

- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Tag`
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataConceptsItemsSys

- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `TaxonomyConcept`
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystem

- `source` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSource, optional, nullable)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItemsSys, required)
- `parameters` (map from string to any, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsTemplateItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsTemplateItemsSys, required)
- `parameters` (map from string to any, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataTagsItemsSys

- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Tag`
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataConceptsItemsSys

- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `TaxonomyConcept`
- `id` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystem

- `source` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSource, optional, nullable)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItemsSys, required)
- `parameters` (map from string to any, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsTemplateItems

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsTemplateItemsSys, required)
- `parameters` (map from string to any, optional)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters0

- `type` (enum, required)
  - Allowed values: `string`
- `value` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters1

- `type` (enum, required)
  - Allowed values: `number`
- `value` (double, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters2

- `type` (enum, required)
  - Allowed values: `date`
- `value` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters3

- `type` (enum, required)
  - Allowed values: `array.string`
- `value` (list of string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaI18NContextParameters4

- `type` (enum, required)
  - Allowed values: `array.number`
- `value` (list of double, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSource

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSourceSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItemsSys

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Annotation`

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsTemplateItemsSys

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Annotation`

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSource

- `sys` (SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSourceSys, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsComponentTypeItemsSys

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Annotation`

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsTemplateItemsSys

- `id` (string, required)
- `type` (enum, required)
  - Allowed values: `Link`
- `linkType` (enum, required)
  - Allowed values: `Annotation`

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutRequestBodyContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSourceSys

- `type` (enum, required)
  - Allowed values: `ResourceLink`
- `linkType` (enum, required)
  - Allowed values: `Contentful:DesignSystemSource`
- `urn` (string, required)

### SpacesSpaceIdEnvironmentsEnvironmentIdDesignTokensIdPutResponsesContentApplicationJsonSchemaMetadataAnnotationsDesignSystemSourceSys

- `type` (enum, required)
  - Allowed values: `ResourceLink`
- `linkType` (enum, required)
  - Allowed values: `Contentful:DesignSystemSource`
- `urn` (string, required)

## Examples

### Example 1

**Request**

```json
{
  "name": "string",
  "type": "DTCG.Color"
}
```

**Response**

```json
{
  "sys": {
    "id": "string",
    "type": "DesignToken",
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "designSystemSource": {
      "sys": {
        "linkType": "Contentful:DesignSystemSource",
        "type": "ResourceLink",
        "urn": "string"
      }
    },
    "environment": {
      "sys": {
        "id": "string",
        "linkType": "Environment",
        "type": "Link"
      }
    },
    "space": {
      "sys": {
        "id": "string",
        "linkType": "Space",
        "type": "Link"
      }
    },
    "updatedAt": "string",
    "updatedBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "version": 1.1
  },
  "name": "string",
  "type": "DTCG.Color",
  "metadata": {
    "tags": [
      {
        "sys": {
          "type": "Link",
          "linkType": "Tag",
          "id": "string"
        }
      }
    ],
    "concepts": [
      {
        "sys": {
          "type": "Link",
          "linkType": "TaxonomyConcept",
          "id": "string"
        }
      }
    ],
    "annotations": {
      "DesignSystem": {
        "source": {
          "sys": {
            "type": "ResourceLink",
            "linkType": "Contentful:DesignSystemSource",
            "urn": "string"
          }
        }
      },
      "ComponentType": [
        {
          "sys": {
            "id": "string",
            "type": "Link",
            "linkType": "Annotation"
          },
          "parameters": {}
        }
      ],
      "Template": [
        {
          "sys": {
            "id": "string",
            "type": "Link",
            "linkType": "Annotation"
          },
          "parameters": {}
        }
      ]
    }
  }
}
```

### Example 2

**Request**

```json
{
  "name": "string",
  "type": "DTCG.Color"
}
```

**Response**

```json
{
  "sys": {
    "id": "string",
    "type": "DesignToken",
    "createdAt": "string",
    "createdBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "designSystemSource": {
      "sys": {
        "linkType": "Contentful:DesignSystemSource",
        "type": "ResourceLink",
        "urn": "string"
      }
    },
    "environment": {
      "sys": {
        "id": "string",
        "linkType": "Environment",
        "type": "Link"
      }
    },
    "space": {
      "sys": {
        "id": "string",
        "linkType": "Space",
        "type": "Link"
      }
    },
    "updatedAt": "string",
    "updatedBy": {
      "sys": {
        "id": "string",
        "linkType": "User",
        "type": "Link"
      }
    },
    "version": 1.1
  },
  "name": "string",
  "type": "DTCG.Color",
  "metadata": {
    "tags": [
      {
        "sys": {
          "type": "Link",
          "linkType": "Tag",
          "id": "string"
        }
      }
    ],
    "concepts": [
      {
        "sys": {
          "type": "Link",
          "linkType": "TaxonomyConcept",
          "id": "string"
        }
      }
    ],
    "annotations": {
      "DesignSystem": {
        "source": {
          "sys": {
            "type": "ResourceLink",
            "linkType": "Contentful:DesignSystemSource",
            "urn": "string"
          }
        }
      },
      "ComponentType": [
        {
          "sys": {
            "id": "string",
            "type": "Link",
            "linkType": "Annotation"
          },
          "parameters": {}
        }
      ],
      "Template": [
        {
          "sys": {
            "id": "string",
            "type": "Link",
            "linkType": "Annotation"
          },
          "parameters": {}
        }
      ]
    }
  }
}
```