---
title: Dictionary
summary: A Dictionary is a VCL data table that stores key-value pairs accessible to VCL during request processing. New, empty dictionaries can be attached to a draft version of a service, which must be activated for the dictionary to be included in VCL. Once installed, a dictionary's items may be updated via API calls without having to activate a new version of the associated service configuration. To remove a dictionary, delete it on a draft version of a service (one that is not locked and not active). Once removed, activate the draft service version without the dictionary.
url: https://www.fastly.com/documentation/reference/api/dictionaries/dictionary
---

A Dictionary is a VCL data table that stores key-value pairs accessible to VCL during request processing. New, empty dictionaries can be attached to a draft version of a service, which must be activated for the dictionary to be included in VCL. Once installed, a dictionary's items may be updated via API calls without having to activate a new version of the associated service configuration. To remove a dictionary, delete it on a draft version of a service (one that is not locked and not active). Once removed, activate the draft service version without the dictionary.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Name for the Dictionary (must start with an alphabetic character and can contain only alphanumeric characters, underscores, and whitespace). |
| `write_only` | boolean | Determines if items in the dictionary are readable or not. |
| `created_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `deleted_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `id` | string | Alphanumeric string identifying a Dictionary. (Read-only) |
| `service_id` | string | Alphanumeric string identifying the service. (Read-only) |
| `updated_at` | string | Date and time in ISO 8601 format. (Read-only) |
| `version` | integer | Integer identifying a service version. (Read-only) |

## API endpoints

### List dictionaries

**GET** `/service/{service_id}/version/{version_id}/dictionary`

List all dictionaries for the version of the service.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Create a dictionary

**POST** `/service/{service_id}/version/{version_id}/dictionary`

Create named dictionary for a particular service and version.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Get a dictionary

**GET** `/service/{service_id}/version/{version_id}/dictionary/{dictionary_name}`

Retrieve a single dictionary by name for the version and service.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dictionary_name` | string | path | Yes | Name for the Dictionary (must start with an alphabetic character and can contain only alphanumeric characters, underscores, and whitespace). |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Update a dictionary

**PUT** `/service/{service_id}/version/{version_id}/dictionary/{dictionary_name}`

Update named dictionary for a particular service and version.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dictionary_name` | string | path | Yes | Name for the Dictionary (must start with an alphabetic character and can contain only alphanumeric characters, underscores, and whitespace). |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |

### Delete a dictionary

**DELETE** `/service/{service_id}/version/{version_id}/dictionary/{dictionary_name}`

Delete named dictionary for a particular service and version.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `dictionary_name` | string | path | Yes | Name for the Dictionary (must start with an alphabetic character and can contain only alphanumeric characters, underscores, and whitespace). |
| `service_id` | string | path | Yes | Alphanumeric string identifying the service. |
| `version_id` | integer | path | Yes | Integer identifying a service version. |