First-party event governance — event contracts and event domains.
openapi: 3.0.0
info:
title: Hightouch Events API
description: Hightouch Public Rest API to access syncs, models, sources and destinations
version: 1.0.0
contact:
name: Hightouch
url: https://hightouch.com
x-harvested-from: https://api.hightouch.io/api/swagger.json
x-harvested-on: '2026-08-13'
x-source-document: openapi/_original/hightouch-api-openapi.json
servers:
- url: https://api.hightouch.com/api/v1
tags:
- name: Events
paths:
/events/contracts/{contractId}:
get:
operationId: GetContract
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventContract'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: '1'
name: My Contract
slug: my-contract
workspaceId: 1
events:
- type: track
name: Checked Out
slug: track-checked-out
version: default
schema:
type: object
required:
- req
properties:
req:
type: string
description: ''
onSchemaViolation: ALLOW_EVENT
onUndeclaredFields: BLOCK_EVENT
onUndeclaredSchema: BLOCK_EVENT
eventSources:
- id: '1'
name: Marketing Site
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Retrieve a contract based on its contract ID
summary: Get Contract
security:
- bearerAuth: []
parameters:
- description: The id of the contract
in: path
name: contractId
required: true
schema:
type: string
tags:
- Events
patch:
operationId: UpdateContract
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventContractUpdate'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: '1'
name: My Contract
workspaceId: 1
events:
- type: track
name: Checked Out
slug: track-checked-out
version: default
schema:
type: object
required:
- req
properties:
req:
type: string
description: ''
onSchemaViolation: ALLOW_EVENT
onUndeclaredFields: BLOCK_EVENT
onUndeclaredSchema: BLOCK_EVENT
eventSources:
- id: '1'
name: Marketing Site
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: 'Update an existing event contract
Patch an event contract based on its Hightouch ID'
summary: Update an Event Contract
security:
- bearerAuth: []
parameters:
- in: path
name: contractId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventContractUpdate'
example:
events:
- type: track
name: Checked Out
onUndeclaredFields: BLOCK_EVENT
onSchemaViolation: BLOCK_EVENT
schema:
type: object
properties:
properties:
type: object
required:
- total
properties:
total:
type: number
tags:
- Events
/events/contracts:
get:
operationId: ListContracts
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/EventContract'
type: array
required:
- data
type: object
examples:
Example 1:
value:
data:
- id: '1'
name: My Contract
slug: my-contract
workspaceId: 1
events:
- type: track
name: Checked Out
slug: track-checked-out
version: default
schema:
type: object
required:
- req
properties:
req:
type: string
description: ''
onSchemaViolation: BLOCK_EVENT
onUndeclaredFields: BLOCK_EVENT
onUndeclaredSchema: BLOCK_EVENT
eventSources:
- id: '1'
name: Marketing Site
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
hasMore: false
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all event contracts in the current workspace
summary: List Event Contracts
security:
- bearerAuth: []
parameters:
- in: query
name: name
required: false
schema:
type: string
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- name
- createdAt
- updatedAt
tags:
- Events
post:
operationId: CreateContract
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventContract'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: '1'
name: My Contract
workspaceId: 1
events:
- type: track
name: Checked Out
version: default
schema:
type: object
required:
- req
properties:
req:
type: string
description: ''
onSchemaViolation: ALLOW_EVENT
onUndeclaredFields: BLOCK_EVENT
onUndeclaredSchema: BLOCK_EVENT
eventSources:
- id: '1'
name: Marketing Site
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Create a new event contract
summary: Create an Event Contract
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventContractCreate'
example:
name: My Contract
events:
- type: track
name: Checked Out
onUndeclaredFields: ALLOW_EVENT
onSchemaViolation: BLOCK_EVENT
schema:
type: object
properties:
properties:
type: object
required:
- total
properties:
total:
type: number
tags:
- Events
/events/domains/{domainId}:
get:
operationId: GetDomain
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventDomain'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: Retrieve a domain by its id, including its events and components.
summary: Get Domain
security:
- bearerAuth: []
parameters:
- description: The id of the domain
in: path
name: domainId
required: true
schema:
type: string
tags:
- Events
patch:
operationId: UpdateDomain
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventDomain'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Not found
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Update an existing event domain, replacing its events and components.
summary: Update an Event Domain
security:
- bearerAuth: []
parameters:
- description: The domain's id
in: path
name: domainId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventDomainUpdate'
tags:
- Events
/events/domains:
get:
operationId: ListDomains
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/EventDomain'
type: array
required:
- data
type: object
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all event domains in the current workspace.
summary: List Event Domains
security:
- bearerAuth: []
parameters:
- in: query
name: name
required: false
schema:
type: string
- description: set the offset on results (for pagination)
in: query
name: offset
required: false
schema:
default: 0
format: double
type: number
- description: limit the number of objects returned (default is 100)
in: query
name: limit
required: false
schema:
default: 100
format: double
type: number
- description: specify the order
in: query
name: orderBy
required: false
schema:
default: id
type: string
enum:
- id
- name
- createdAt
- updatedAt
tags:
- Events
post:
operationId: CreateDomain
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/EventDomain'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Create a new event domain, with its events and components.
summary: Create an Event Domain
security:
- bearerAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EventDomainCreate'
tags:
- Events
components:
schemas:
EventContract:
description: A collection of schemas that are used for validating your events.
properties:
id:
type: string
description: The contract's id
name:
type: string
description: The contract's name
slug:
type: string
description: The contract's slug. If not specified, one will be generated.
description:
type: string
description: The contract's description
onUndeclaredSchema:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that aren''t defined in the contract.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.'
events:
items:
properties:
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema that validates the event. Required.
onUndeclaredFields:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
- OMIT_FIELDS
description: '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:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that violate the schema.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.'
version:
type: string
description: The event version. Defaults to "default", optional. You probably don't need
to set this.
slug:
type: string
description: The event's slug. If not specified, one will be generated.
name:
type: string
description: The event's name. Required for track events.
type:
type: string
enum:
- track
- identify
- page
- screen
- group
description: The event's type. One of track, identify, page, screen, or group. Required.
required:
- schema
- type
type: object
type: array
description: The definitions for the events in the contract.
workspaceId:
type: number
format: double
description: The id of the workspace that the contract belongs to
createdAt:
type: string
format: date-time
description: The timestamp when the contract was created
updatedAt:
type: string
format: date-time
description: The timestamp when the contract was last updated
eventSources:
items:
properties:
name:
type: string
id:
type: string
required:
- name
- id
type: object
type: array
description: The Event Sources linked to the Contract.
required:
- id
- name
- workspaceId
- createdAt
- updatedAt
- eventSources
type: object
additionalProperties: false
EventContractCreate:
description: The input for creating a Contract
properties:
name:
type: string
description: The contract's name
slug:
type: string
description: The contract's slug. If not specified, one will be generated.
description:
type: string
description: The contract's description
onUndeclaredSchema:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that aren''t defined in the contract.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.'
events:
items:
properties:
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema that validates the event. Required.
onUndeclaredFields:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
- OMIT_FIELDS
description: '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:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that violate the schema.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.'
version:
type: string
description: The event version. Defaults to "default", optional. You probably don't need
to set this.
slug:
type: string
description: The event's slug. If not specified, one will be generated.
name:
type: string
description: The event's name. Required for track events.
type:
type: string
enum:
- track
- identify
- page
- screen
- group
description: The event's type. One of track, identify, page, screen, or group. Required.
required:
- schema
- type
type: object
type: array
description: The definitions for the events in the contract.
required:
- name
type: object
additionalProperties: false
EventContractUpdate:
description: The input for updating a Contract
properties:
name:
type: string
description: The contract's name
slug:
type: string
description: The contract's slug. If not specified, one will be generated.
description:
type: string
description: The contract's description
onUndeclaredSchema:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that aren''t defined in the contract.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.'
events:
items:
properties:
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema that validates the event. Required.
onUndeclaredFields:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
- OMIT_FIELDS
description: '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:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that violate the schema.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.'
version:
type: string
description: The event version. Defaults to "default", optional. You probably don't need
to set this.
slug:
type: string
description: The event's slug. If not specified, one will be generated.
name:
type: string
description: The event's name. Required for track events.
type:
type: string
enum:
- track
- identify
- page
- screen
- group
description: The event's type. One of track, identify, page, screen, or group. Required.
required:
- schema
- type
type: object
type: array
description: The definitions for the events in the contract.
type: object
additionalProperties: false
EventDomain:
description: A collection of event and component schemas used for validating events.
properties:
id:
type: string
description: The domain's id
name:
type: string
description: The domain's name
slug:
type: string
description: The domain's slug. If not specified, one will be generated.
description:
type: string
description: The domain's description
onUndeclaredSchema:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that aren''t defined in the domain.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.'
events:
items:
properties:
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema that validates the event. Required. May contain component
`$ref`s.
onUndeclaredFields:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
- OMIT_FIELDS
description: '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:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that violate the schema.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.'
version:
type: string
description: The event version. Defaults to "default", optional. You probably don't need
to set this.
slug:
type: string
description: The event's slug. If not specified, one will be generated.
name:
type: string
description: The event's name. Required for track events.
type:
type: string
enum:
- track
- identify
- page
- screen
- group
description: The event's type. One of track, identify, page, screen, or group. Required.
required:
- schema
- type
type: object
type: array
description: The definitions for the events in the domain.
components:
items:
$ref: '#/components/schemas/EventDomainComponent'
type: array
description: The reusable components defined in the domain.
workspaceId:
type: number
format: double
description: The id of the workspace that the domain belongs to
createdAt:
type: string
format: date-time
description: The timestamp when the domain was created
updatedAt:
type: string
format: date-time
description: The timestamp when the domain was last updated
eventSources:
items:
properties:
name:
type: string
id:
type: string
required:
- name
- id
type: object
type: array
description: The Event Sources linked to the Domain.
required:
- id
- name
- workspaceId
- createdAt
- updatedAt
- eventSources
type: object
additionalProperties: false
EventDomainComponent:
description: Reusable schema fragments that can be imported by event schemas.
properties:
id:
type: string
description: 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:
type: string
description: 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:
type: string
description: The component's name. Required.
version:
type: string
description: 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:
type: string
description: The component's description. On update, an omitted description keeps the stored
value; send an empty string to clear it.
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema fragment the component contributes. Required.
imports:
items:
type: string
type: array
description: 'Read-only: the slugs of the components this component imports (derived from its
`$ref`s).'
required:
- name
- schema
type: object
additionalProperties: false
EventDomainCreate:
description: The input for creating a Domain
properties:
name:
type: string
description: The domain's name
slug:
type: string
description: The domain's slug. If not specified, one will be generated.
description:
type: string
description: The domain's description
onUndeclaredSchema:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that aren''t defined in the domain.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to ALLOW_EVENT.'
events:
items:
properties:
schema:
properties: {}
additionalProperties: {}
type: object
description: The JSON schema that validates the event. Required. May contain component
`$ref`s.
onUndeclaredFields:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
- OMIT_FIELDS
description: '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:
type: string
enum:
- ALLOW_EVENT
- BLOCK_EVENT
description: 'What happens to events that violate the schema.
One of ALLOW_EVENT or BLOCK_EVENT. Optional, defaults to BLOCK_EVENT.'
version:
type: strin
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hightouch/refs/heads/main/openapi/hightouch-events-api-openapi.yml