Model definitions (SQL, table, dbt, visual) over a source.
openapi: 3.0.0
info:
title: Hightouch Models 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: Models
paths:
/models/{modelId}:
get:
operationId: GetModel
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
examples:
Example 1:
value:
id: 1
name: testModel
slug: testModel
description: ''
workspaceId: 1
primaryKey: id
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
sourceId: 1
queryType: raw_sql
tags:
foo: bar
isSchema: false
raw:
sql: select * from users
syncs:
- 1
- 2
lastRunSize: 12345
'401':
description: Unauthorized
'404':
description: Not found
description: Retrieve models from model ID
summary: Get Model
security:
- bearerAuth: []
parameters:
- description: The id of the model
in: path
name: modelId
required: true
schema:
format: double
type: number
tags:
- Models
patch:
operationId: UpdateModel
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Model'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 1
name: testModel
slug: testModel
description: ''
workspaceId: 1
primaryKey: id
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-17T23:19:05.000Z'
sourceId: 1
queryType: raw_sql
tags:
foo: bar
isSchema: false
raw:
sql: select name from users
syncs:
- 1
- 2
lastRunSize: 12345
'401':
description: Unauthorized
'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 model
Patch a model based on its Hightouch ID'
summary: Update Model
security:
- bearerAuth: []
parameters:
- description: The model's ID
in: path
name: modelId
required: true
schema:
format: double
type: number
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelUpdate'
example:
name: testmodel
primaryKey: id
raw:
sql: select name from users
tags:
- Models
/models:
get:
operationId: ListModel
responses:
'200':
description: Ok
content:
application/json:
schema:
properties:
data:
items:
$ref: '#/components/schemas/Model'
type: array
required:
- data
type: object
examples:
Example 1:
value:
data:
- id: 1
name: testModel
slug: testModel
description: ''
workspaceId: 1
primaryKey: id
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
sourceId: 1
queryType: raw_sql
tags:
foo: bar
isSchema: false
raw:
sql: select * from users
syncs:
- 1
- 2
lastRunSize: 12345
- id: 2
name: testModel2
slug: testModel2
description: ''
workspaceId: 1
primaryKey: id
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
sourceId: 1
queryType: raw_sql
tags:
foo: baz
isSchema: false
raw:
sql: select * from accounts
syncs:
- 1
- 2
lastRunSize: 6789
hasMore: false
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
description: List all the models in the current workspace including parent and related models
summary: List Models
security:
- bearerAuth: []
parameters:
- description: filter based on name
in: query
name: name
required: false
schema:
type: string
- description: filter based on slug
in: query
name: slug
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
- slug
- createdAt
- updatedAt
- description: 'filter models based on tags (format: key:value), ex: team:marketing. Repeat this
parameter for multiple tags.'
in: query
name: tags
required: false
schema:
default: []
type: array
items:
type: string
tags:
- Models
post:
operationId: CreateModel
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Model'
- $ref: '#/components/schemas/ValidateErrorJSON'
- $ref: '#/components/schemas/InternalServerError'
examples:
Example 1:
value:
id: 3
name: testModel3
slug: testModel3
description: ''
workspaceId: 1
primaryKey: id
createdAt: '2022-02-16T21:37:58.510Z'
updatedAt: '2022-02-16T21:37:58.510Z'
sourceId: 1
queryType: raw_sql
tags: {}
isSchema: false
raw:
sql: select id, last_name from users
syncs: []
lastRunSize: null
'401':
description: Unauthorized
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'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 model
summary: Create Model
security:
- bearerAuth: []
parameters:
- in: query
name: skipColumnQuery
required: false
schema:
default: false
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelCreate'
example:
name: testModel3
slug: testModel3
primaryKey: id
sourceId: 1
queryType: raw_sql
isSchema: false
raw:
sql: select id, last_name from users
tags:
- Models
components:
schemas:
InternalServerError:
type: string
enum:
- Internal Server Error
nullable: false
Model:
description: 'The SQL query that pulls data from your source to send to your destination.
We send your SQL query directly to your source so any SQL that is valid for your source (including
functions) is valid in Hightouch.'
properties:
id:
type: number
format: double
description: The id of the model
name:
type: string
description: The name of the model
slug:
type: string
description: The slug of the model
description:
type: string
description: The description of the model
workspaceId:
type: number
format: double
description: The id of the workspace where the model belongs to
primaryKey:
type: string
description: The primary key will be null if the query doesn't get directly synced (e.g. a relationship
table for visual querying)
createdAt:
type: string
format: date-time
description: The timestamp when model was created
updatedAt:
type: string
format: date-time
description: The timestamp when model was lastly updated
sourceId:
type: number
format: double
description: The id of the source that model is connected to
queryType:
type: string
description: 'The type of the query. Available options: custom, raw_sql, tabel, dbt and visual.'
tags:
properties: {}
additionalProperties:
type: string
type: object
description: The tags of the model
isSchema:
type: boolean
description: 'If is_schema is true, the model is just used to build other models.
Either as part of visual querying, or as the root of a visual query.'
syncs:
items:
type: number
format: double
type: array
description: The list of id of syncs that uses this model
visual:
properties:
secondaryLabel:
type: string
primaryLabel:
type: string
filter: {}
parentId:
type: number
format: double
description: Parent id of the schema that visual query is based on
required:
- filter
- parentId
type: object
description: Visual query, used by audience
custom:
properties:
query: {}
required:
- query
type: object
description: Custom query for sources that doesn't support sql. For example, Airtable.
table:
properties:
name:
type: string
required:
- name
type: object
description: Table-based query that fetches on a table instead of SQL
dbt:
properties:
dbtUniqueId:
type: string
description: Unique ID of the model assigned by dbt (usually some combination of the schema
and table name)
compiledSql:
type: string
description: Compiled SQL in the dbt model
rawSql:
type: string
description: Raw SQL in the dbt model
database:
type: string
description: Name of the database containing the generated table
schema:
type: string
description: Name of the schema containing the generated table
name:
type: string
description: Name of the table generated by the dbt model
modelId:
type: number
format: double
description: Model id that refer to a dbt model
required:
- dbtUniqueId
- compiledSql
- rawSql
- database
- schema
- name
- modelId
type: object
description: Query that is based on a dbt model
dbt_cloud:
properties:
dbtUniqueId:
type: string
description: Unique ID of the model assigned by dbt (usually some combination of the schema
and table name)
compiledSql:
type: string
description: Compiled SQL in the dbt model
rawSql:
type: string
name:
type: string
description: Name of the table generated by the dbt model
modelId:
type: number
format: double
description: Model id that refer to a dbt model
required:
- dbtUniqueId
- compiledSql
- rawSql
- name
- modelId
type: object
raw:
properties:
sql:
type: string
required:
- sql
type: object
description: Standard raw SQL query
folderId:
type: string
lastRunSize:
type: number
format: double
nullable: true
description: 'The number of rows returned by the most recent successful sync run of this model.
Null if the model has never been synced successfully.'
required:
- id
- name
- slug
- description
- workspaceId
- primaryKey
- createdAt
- updatedAt
- sourceId
- queryType
- tags
- isSchema
- syncs
- lastRunSize
type: object
additionalProperties: false
ModelCreate:
description: The input for creating a Model
properties:
name:
type: string
description: The name of the model
slug:
type: string
description: The slug of the model
queryType:
type: string
description: 'The type of the query. Available options: custom, raw_sql, tabel, dbt and visual.'
sourceId:
type: number
format: double
description: The id of the source that model is connected to
isSchema:
type: boolean
description: 'If is_schema is true, the model is just used to build other models.
Either as part of visual querying, or as the root of a visual query.'
primaryKey:
type: string
description: The primary key will be null if the query doesn't get directly synced (e.g. a relationship
table for visual querying)
visual:
properties:
secondaryLabel:
type: string
primaryLabel:
type: string
filter: {}
parentId:
type: number
format: double
description: Parent id of the schema that visual query is based on
required:
- filter
- parentId
type: object
description: Visual query, used by audience
custom:
properties:
query: {}
required:
- query
type: object
description: Custom query for sources that doesn't support sql. For example, Airtable.
table:
properties:
name:
type: string
required:
- name
type: object
description: Table-based query that fetches on a table instead of SQL
raw:
properties:
sql:
type: string
required:
- sql
type: object
description: Standard raw SQL query
folderId:
type: string
dbt:
properties:
modelId:
type: number
format: double
description: Model id that refers to a dbt model
required:
- modelId
type: object
dbt_cloud:
properties:
modelId:
type: number
format: double
description: Model id that refers to a dbt Cloud model
required:
- modelId
type: object
required:
- name
- slug
- queryType
- sourceId
- isSchema
- primaryKey
type: object
additionalProperties: false
ModelUpdate:
description: The input for updating a Model
properties:
name:
type: string
description: The name of the model
isSchema:
type: boolean
description: 'If is_schema is true, the model is just used to build other models.
Either as part of visual querying, or as the root of a visual query.'
primaryKey:
type: string
description: The primary key will be null if the query doesn't get directly synced (e.g. a relationship
table for visual querying)
visual:
properties:
secondaryLabel:
type: string
primaryLabel:
type: string
filter: {}
parentId:
type: number
format: double
description: Parent id of the schema that visual query is based on
required:
- filter
- parentId
type: object
description: Visual query, used by audience
custom:
properties:
query: {}
required:
- query
type: object
description: Custom query for sources that doesn't support sql. For example, Airtable.
table:
properties:
name:
type: string
required:
- name
type: object
description: Table-based query that fetches on a table instead of SQL
raw:
properties:
sql:
type: string
required:
- sql
type: object
description: Standard raw SQL query
folderId:
type: string
dbt:
properties:
modelId:
type: number
format: double
description: Model id that refers to a dbt model
required:
- modelId
type: object
type: object
additionalProperties: false
ValidateErrorJSON:
properties:
message:
type: string
enum:
- Validation failed
nullable: false
details:
properties: {}
additionalProperties: {}
type: object
required:
- message
- details
type: object
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
security:
- bearerAuth: []