---
title: "Create an Event Domain"
method: POST
path: "/events/domains"
---

# Create an Event Domain

`POST /events/domains`

Create a new event domain, with its events and components.

## Request body

- EventDomainCreate — The input for creating a Domain
  - `name` string, required — The domain's name
  - `slug` string — The domain's slug. If not specified, one will be generated.
  - `description` string — The domain's description
  - `onUndeclaredSchema` 'ALLOW_EVENT' | 'BLOCK_EVENT' — What happens to events that aren't defined in the domain. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.
  - `events` object[] — The definitions for the events in the domain.
    - `schema` object, required — The JSON schema that validates the event. Required. May contain component `$ref`s.
    - `onUndeclaredFields` 'ALLOW_EVENT' | 'BLOCK_EVENT' | 'OMIT_FIELDS' — What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.
    - `onSchemaViolation` 'ALLOW_EVENT' | 'BLOCK_EVENT' — What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.
    - `version` string — The event version. Defaults to "default", optional. You probably don't need to set this.
    - `slug` string — The event's slug. If not specified, one will be generated.
    - `name` string — The event's name. Required for track events.
    - `type` 'track' | 'identify' | 'page' | 'screen' | 'group', required — The event's type. One of track, identify, page, screen, or group. Required.
  - `components` EventDomainComponent[] — The reusable components defined in the domain.
    - `id` string — The component's id. Omit when creating. On update, a component matches an existing one by id when supplied, otherwise by (name, version); include the id to rename a component in place.
    - `slug` string — The component's slug. Optional when creating; generated from the name if omitted. Immutable after creation; an update that sends a different slug for an existing component is rejected.
    - `name` string, required — The component's name. Required.
    - `version` string — The component's version. Defaults to "default", optional. On update, an omitted version keeps the stored value when the component is matched by id; without an id, an omitted version only matches the stored "default" version, and the request is rejected if the name exists only under other versions.
    - `description` string — The component's description. On update, an omitted description keeps the stored value; send an empty string to clear it.
    - `schema` object, required — The JSON schema fragment the component contributes. Required.
    - `imports` string[] — Read-only: the slugs of the components this component imports (derived from its `$ref`s).

## Response `200`

Ok

- union
  - EventDomain — A collection of event and component schemas used for validating events.
    - `id` string, required — The domain's id
    - `name` string, required — The domain's name
    - `slug` string — The domain's slug. If not specified, one will be generated.
    - `description` string — The domain's description
    - `onUndeclaredSchema` 'ALLOW_EVENT' | 'BLOCK_EVENT' — What happens to events that aren't defined in the domain. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.
    - `schemaVersionPath` string[] — Path into the event payload where the schema version is read/written. Used by codegen wrappers to inject the version they were generated from.
    - `events` object[] — The definitions for the events in the domain.
      - `schema` object, required — The JSON schema that validates the event. Required. May contain component `$ref`s.
      - `onUndeclaredFields` 'ALLOW_EVENT' | 'BLOCK_EVENT' | 'OMIT_FIELDS' — What happens to events that contain fields not in the schema. One of ALLOW_EVENT, BLOCK_EVENT, or OMIT_FIELDS. Optional, defaults to OMIT_FIELDS.
      - `onSchemaViolation` 'ALLOW_EVENT' | 'BLOCK_EVENT' — What happens to events that violate the schema. One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.
      - `version` string — The event version. Defaults to "default", optional. You probably don't need to set this.
      - `slug` string — The event's slug. If not specified, one will be generated.
      - `name` string — The event's name. Required for track events.
      - `type` 'track' | 'identify' | 'page' | 'screen' | 'group', required — The event's type. One of track, identify, page, screen, or group. Required.
    - `components` EventDomainComponent[] — The reusable components defined in the domain.
      - `id` string — The component's id. Omit when creating. On update, a component matches an existing one by id when supplied, otherwise by (name, version); include the id to rename a component in place.
      - `slug` string — The component's slug. Optional when creating; generated from the name if omitted. Immutable after creation; an update that sends a different slug for an existing component is rejected.
      - `name` string, required — The component's name. Required.
      - `version` string — The component's version. Defaults to "default", optional. On update, an omitted version keeps the stored value when the component is matched by id; without an id, an omitted version only matches the stored "default" version, and the request is rejected if the name exists only under other versions.
      - `description` string — The component's description. On update, an omitted description keeps the stored value; send an empty string to clear it.
      - `schema` object, required — The JSON schema fragment the component contributes. Required.
      - `imports` string[] — Read-only: the slugs of the components this component imports (derived from its `$ref`s).
    - `workspaceId` number, double, required — The id of the workspace that the domain belongs to
    - `createdAt` string, date-time, required — The timestamp when the domain was created
    - `updatedAt` string, date-time, required — The timestamp when the domain was last updated
    - `eventSources` object[], required — The Event Sources linked to the Domain.
      - `name` string, required
      - `id` string, required
  - ValidateErrorJSON
    - `message` 'Validation failed', required
    - `details` object, required
  - 'Internal Server Error'

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `422` — Validation Failed
- `500` — Something went wrong

---

[API](https://skmtc.net/hightouch/apis/hightouch-api.md) · [All operations](https://skmtc.net/hightouch/apis/hightouch-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hightouch/hightouch-api/revisions/24a8012aa8c8/schema)