> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# Create an enrichment schema

`POST https://api.pagerduty.com/enrichment/schemas`

Creates an enrichment schema. Provide a JSON body to define the schema explicitly (returns `201`), or upload a CSV file as `multipart/form-data` or `text/csv` to auto-generate a schema from the file's columns — the first column becomes a query field and the rest become enriched fields (returns `202` once the file is accepted for processing). A schema must include 1-3 query fields and at least one enriched field, up to 25 fields total, with unique (case-insensitive) field names. Schemas created through the API are always `CSV`, and an account may have at most 25 CSV schemas. CSV uploads are limited to 10 MB.

<!-- theme: warning -->

> ### Early Access
> This API is in Early Access and may change at any time. Contact your PagerDuty account team to request access.

Scoped OAuth requires: `contextual_data.write`

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `filename` | string |  | The filename for the CSV content. Required when creating a schema from a `text/csv` body; optional for `text/csv` record uploads. Ignored for `multipart/form-data` and JSON requests. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Request body (`application/json`) — required

The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB.

| Field | Type | Required | Description |
|---|---|---|---|
| `integration_type` | string |  | The schema source. Only `CSV` is supported through the API; the schema is always recorded as `CSV` regardless of the value sent. One of: `CSV`. |
| `name` | string | yes | Display name of the enrichment schema. Max length: 50. |
| `description` | string |  | Description of this set of enrichment data. Max length: 2048. |
| `fields` | array of object | yes | The schema fields. Must include 1-3 query fields and at least one enriched field, up to 25 fields total. Field names must be unique (case-insensitive). Min items: 2. Max items: 25. |
| `fields[].name` | string | yes | The name of the field. Must be unique within the schema (case-insensitive). Max length: 256. |
| `fields[].type` | string | yes | How the field is used. `query` fields match incoming events to records (case-insensitive); `enriched` fields carry the data added to a matched event. One of: `query`, `enriched`. |

Example: Create a schema with multiple query fields

```json
{
  "integration_type": "CSV",
  "name": "Application Environment Enrichment",
  "description": "Maps applications to team and runbook info by environment",
  "fields": [
    {
      "name": "Application",
      "type": "query"
    },
    {
      "name": "Environment",
      "type": "query"
    },
    {
      "name": "Manager",
      "type": "enriched"
    },
    {
      "name": "Team",
      "type": "enriched"
    },
    {
      "name": "Runbook URL",
      "type": "enriched"
    }
  ]
}
```

## Request body (`multipart/form-data`) — required

The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB.

| Field | Type | Required | Description |
|---|---|---|---|
| `file` | string | yes | The CSV file to upload (max 10 MB). The schema name is derived from the filename. |

## Request body (`text/csv`) — required

The enrichment schema to create. Provide a JSON body to define the schema explicitly, or upload a CSV file (as `multipart/form-data` or `text/csv`) to auto-generate a schema in which the first column becomes the query field and the remaining columns become enriched fields. CSV uploads are limited to 10 MB.

Type: string

## Response 201

The enrichment schema was created successfully.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `schema` | object |  |  |
| `schema.id` | string (uuid) |  | Unique identifier for the enrichment schema. Read-only. |
| `schema.type` | string |  | The type of the resource. Read-only. |
| `schema.integration_type` | string |  | The source of the enrichment schema. `CSV` schemas are created and populated through the schema and CSV-upload endpoints; `SERVICENOW` schemas are managed by the ServiceNow CMDB integration. Schemas created through the API are always `CSV`, and only `CSV` schemas can be deleted. Read-only. One of: `CSV`, `SERVICENOW`. |
| `schema.name` | string |  | Display name of the enrichment schema. Max length: 50. |
| `schema.description` | string \| null |  | Description of this set of enrichment data. Max length: 2048. |
| `schema.fields` | array of object |  | The fields that make up the schema, including both query and enriched fields. A schema must contain 1-3 `query` fields and at least one `enriched` field, up to a maximum of 25 fields. Field names are unique within the schema (case-insensitive). Min items: 2. Max items: 25. |
| `schema.fields[].name` | string | yes | The name of the field. Unique within the schema (case-insensitive). Max length: 256. |
| `schema.fields[].type` | string | yes | How the field is used during enrichment. `query` fields are used to match incoming events to enrichment records (matching is case-insensitive), and `enriched` fields carry the contextual data added to a matched event. A schema has 1-3 query fields and at least one enriched field. `discriminator` is reserved for internal use (for example, by the ServiceNow CMDB integration). One of: `query`, `enriched`, `discriminator`. |
| `schema.created_at` | string (date-time) |  | Timestamp when the schema was created. Read-only. |
| `schema.updated_at` | string (date-time) |  | Timestamp when the schema was last updated. Read-only. |
| `schema.deleted_at` | string \| null (date-time) |  | Timestamp when the schema was deleted, or `null` if it has not been deleted. Read-only. |

Example: Example Response

```json
{
  "schema": {
    "id": "9f194d8d-0f58-4c5c-b1d2-a5adf7171821",
    "type": "enrichment_schema",
    "integration_type": "CSV",
    "name": "Team Lead and Runbooks",
    "description": "Attaches SME and Runbook URLs to Incident",
    "fields": [
      {
        "name": "Application",
        "type": "query"
      },
      {
        "name": "Manager",
        "type": "enriched"
      },
      {
        "name": "Runbook URL",
        "type": "enriched"
      }
    ],
    "created_at": "2026-06-30T15:17:30Z",
    "updated_at": "2026-06-30T15:17:30Z",
    "deleted_at": null
  }
}
```

## Response 202

The schema was created from the uploaded CSV and the file was accepted for asynchronous processing. The records become queryable once processing completes.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `schema` | object |  | Same fields as `schema` above. |

Example: Example Response

```json
{
  "schema": {
    "id": "b620bbb5-2571-4b7a-b0c6-47c55bd491d0",
    "type": "enrichment_schema",
    "integration_type": "CSV",
    "name": "users",
    "description": "Auto generated schema from CSV upload",
    "fields": [
      {
        "name": "email",
        "type": "query"
      },
      {
        "name": "team",
        "type": "enriched"
      },
      {
        "name": "manager",
        "type": "enriched"
      }
    ],
    "created_at": "2026-06-30T15:20:00Z",
    "updated_at": "2026-06-30T15:20:00Z",
    "deleted_at": null
  }
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 429

Too many requests have been made, the rate limit has been reached.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 500

Internal Server Error the PagerDuty server experienced an error.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).