Polytomic subpackage_models API
The subpackage_models API from Polytomic — 6 operation(s) for subpackage_models.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference subpackage_bulkSync subpackage_models API
version: 1.0.0
servers:
- url: https://app.polytomic.com
tags:
- name: subpackage_models
paths:
/api/connections/{id}/modelsync/enrichment-source:
get:
operationId: get-enrichment-source
summary: Get Enrichment Source
description: 'Describes the enrichment source configuration available on a connection.
Not all connections support enrichment. Call this endpoint to determine
whether a connection can serve as an enrichment source in a model sync and,
if so, what configuration it accepts.
> ⚠️ If the connection does not support enrichment, this endpoint returns
> `404`. Check for that status before attempting to configure an enrichment
> source on a sync.
When a connection does support enrichment, the response describes the
configuration fields required to set it up. Pass those values in the
`enrichment` block when creating or updating a model sync.'
tags:
- subpackage_models
parameters:
- name: id
in: path
description: Unique identifier of the connection.
required: true
schema:
type: string
format: uuid
- name: params
in: query
description: Query parameters used to incrementally refine a dependent source configuration. Keys correspond to configuration fields returned by previous calls to this endpoint.
required: false
schema:
type: object
additionalProperties:
type: array
items:
type: string
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetSyncSourceMetaEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/enrichment/{connection_id}/inputfields:
post:
operationId: post
summary: Enrichment Fields
description: 'Returns the valid input field sets for an enrichment configuration on a connection.
When configuring an enrichment source in a model sync, use this endpoint to
discover which input fields the enrichment connection requires. Pass the
proposed enrichment configuration in the request body; the response lists the
valid input field sets that map your model''s fields to the enrichment service''s
expected inputs.'
tags:
- subpackage_models
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
format: uuid
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GetEnrichmentInputFieldsResponseEnvelope'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentInputFieldsRequest'
/api/model-preview:
post:
operationId: preview
summary: Preview Model
description: 'Submits a job that previews the fields a model would expose without persisting it.
The response contains a job ID that resolves to the list of fields the model
would expose. Poll the job until it completes to retrieve the field list. The
model is not persisted — this endpoint is useful for validating a query or
configuration before calling [`POST /api/models`](../../api-reference/models/create) to save it.'
tags:
- subpackage_models
parameters:
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
/api/models:
get:
operationId: list
summary: List Models
description: 'Lists all models in the caller''s organization.
Results are ordered by `updated_at` descending, with `id` used as a tiebreaker.
If more results are available, the response includes `pagination.next_page_token`.
Pass that token back unchanged to continue from the last item you received.
The token is opaque. Do not construct or edit it yourself.
The `limit` is capped at 50. Values above that cap are reduced to 50, and
non-positive values fall back to the same default.'
tags:
- subpackage_models
parameters:
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelListResponseEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
post:
operationId: create
summary: Create Model
description: 'Creates a new model.
A model defines a query or view over a connection''s data — for example, a SQL
query, a filtered object, or a joined dataset. Models are used as sources when
creating model syncs.
The connection referenced by `connection_id` must have source capabilities. Use
[`GET /api/connection_types/{id}`](../../api-reference/connections/get-connection-type-schema) to check
whether a connection type supports use as a source.'
tags:
- subpackage_models
parameters:
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
/api/models/{id}:
get:
operationId: get
summary: Get Model
description: 'Returns a single model by ID, including its source fields, identity, and filters.
The response includes the model''s source fields, identity column, and any
configured filters. To preview the data a model would return without saving
changes, use [`GET /api/models/{id}/sample`](../../../api-reference/models/sample).'
tags:
- subpackage_models
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponseEnvelope'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
put:
operationId: update
summary: Update Model
description: 'Updates a model''s configuration.
Updating a model is a **full replacement** of its configuration. Every field in
the request body is written to the model; any field you omit is cleared or reset
to its default value.
To make a partial change, fetch the current model with
[`GET /api/models/{id}`](../../../api-reference/models/get), modify the fields you want to change, and send
the complete object back in the update request.
Changes to source fields, filters, or the identity column take effect on the
next sync execution that uses this model.'
tags:
- subpackage_models
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateModelRequest'
delete:
operationId: delete
summary: Delete Model
description: 'Deletes a model.
> 🚧 Deleting a model used by one or more syncs will break those syncs. Remove
> or reconfigure any syncs that reference this model before deleting it.'
tags:
- subpackage_models
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: Successful response
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/api/models/{id}/sample:
get:
operationId: sample
summary: Sample Records
description: 'Returns a sample of records from a model.
Synchronous requests must complete within 10 seconds. If the source query or
enrichment step can exceed that budget, use the asynchronous option so the
work runs as a background job.'
tags:
- subpackage_models
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
- name: async
in: query
required: false
schema:
type: boolean
- name: Authorization
in: header
description: Bearer user API key
required: true
schema:
type: string
- name: X-Polytomic-Version
in: header
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ModelSampleResponseEnvelope'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
components:
schemas:
ModelSampleResponseEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/ModelSample'
job:
$ref: '#/components/schemas/JobResponse'
title: ModelSampleResponseEnvelope
WorkTaskStatus:
type: string
enum:
- created
- running
- done
- failed
title: WorkTaskStatus
JobResponse:
type: object
properties:
error:
type:
- string
- 'null'
description: Error message if the job failed.
job_id:
type: string
format: uuid
description: Identifier of the job.
result:
description: Job result. Shape depends on the job type; only populated once status is done.
status:
$ref: '#/components/schemas/WorkTaskStatus'
type:
type: string
description: Job type. Matches the type used to fetch the job.
title: JobResponse
ModelField:
type: object
properties:
created_at:
type: string
format: date-time
created_by:
$ref: '#/components/schemas/OutputActor'
description:
type: string
example:
description: Any type
id:
type: string
format: uuid
label:
type: string
name:
type: string
remote_type:
type: string
type:
type: string
unique:
type: boolean
updated_at:
type: string
format: date-time
user_added:
type: boolean
title: ModelField
ModelModelFieldRequest:
type: object
properties:
example:
type: string
label:
type: string
name:
type: string
type:
type: string
required:
- label
- name
- type
title: ModelModelFieldRequest
ModelResponse:
type: object
properties:
configuration:
type: object
additionalProperties:
description: Any type
connection_id:
type: string
format: uuid
created_at:
type: string
format: date-time
created_by:
$ref: '#/components/schemas/OutputActor'
enricher:
$ref: '#/components/schemas/Enrichment'
fields:
type: array
items:
$ref: '#/components/schemas/ModelField'
id:
type: string
format: uuid
identifier:
type: string
labels:
type: array
items:
$ref: '#/components/schemas/LabelLabel'
name:
type: string
organization_id:
type: string
format: uuid
policies:
type: array
items:
type: string
format: uuid
relations:
type: array
items:
$ref: '#/components/schemas/Relation'
tracking_columns:
type: array
items:
type: string
type:
type: string
updated_at:
type: string
format: date-time
updated_by:
$ref: '#/components/schemas/OutputActor'
version:
type: integer
title: ModelResponse
RelationTo:
type: object
properties:
field:
type: string
model_id:
type: string
format: uuid
title: RelationTo
LabelLabel:
type: object
properties: {}
title: LabelLabel
GetEnrichmentInputFieldsResponseEnvelope:
type: object
properties:
data:
type:
- array
- 'null'
items:
type: array
items:
type: string
title: GetEnrichmentInputFieldsResponseEnvelope
ModelListResponseEnvelope:
type: object
properties:
data:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ModelResponse'
title: ModelListResponseEnvelope
OutputActor:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
type:
type: string
title: OutputActor
ModelResponseEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/ModelResponse'
job:
$ref: '#/components/schemas/JobResponse'
title: ModelResponseEnvelope
CreateModelRequest:
type: object
properties:
additional_fields:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ModelModelFieldRequest'
configuration:
type: object
additionalProperties:
description: Any type
connection_id:
type: string
format: uuid
enricher:
$ref: '#/components/schemas/Enrichment'
fields:
type:
- array
- 'null'
items:
type: string
identifier:
type: string
labels:
type:
- array
- 'null'
items:
type: string
format: uuid
name:
type: string
organization_id:
type:
- string
- 'null'
format: uuid
policies:
type:
- array
- 'null'
items:
type: string
format: uuid
relations:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ModelRelation'
tracking_columns:
type:
- array
- 'null'
items:
type: string
required:
- configuration
- connection_id
- name
title: CreateModelRequest
SourceMeta:
type: object
properties:
has_items:
type: boolean
description: True when items is non-empty. Callers should present the values as a picker.
items:
type:
- array
- 'null'
items:
description: Any type
description: Valid values the caller may choose for this configuration item.
requires_one_of:
type:
- array
- 'null'
items:
type: string
description: Other configuration items this item depends on; exactly one of the listed items must also be selected.
title: SourceMeta
ModelRelation:
type: object
properties:
from:
type: string
to:
$ref: '#/components/schemas/ModelRelationTo'
title: ModelRelation
EnrichmentInputFieldsRequest:
type: object
properties:
configuration:
$ref: '#/components/schemas/EnricherConfiguration'
title: EnrichmentInputFieldsRequest
GetSyncSourceMetaEnvelope:
type: object
properties:
data:
$ref: '#/components/schemas/SyncSourceMetaResponse'
title: GetSyncSourceMetaEnvelope
Relation:
type: object
properties:
from:
type: string
to:
$ref: '#/components/schemas/RelationTo'
title: Relation
UpdateModelRequest:
type: object
properties:
additional_fields:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ModelModelFieldRequest'
configuration:
type: object
additionalProperties:
description: Any type
connection_id:
type: string
format: uuid
enricher:
$ref: '#/components/schemas/Enrichment'
fields:
type:
- array
- 'null'
items:
type: string
identifier:
type: string
labels:
type:
- array
- 'null'
items:
type: string
format: uuid
name:
type: string
organization_id:
type:
- string
- 'null'
format: uuid
policies:
type:
- array
- 'null'
items:
type: string
format: uuid
refresh:
type: boolean
relations:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ModelRelation'
tracking_columns:
type:
- array
- 'null'
items:
type: string
required:
- configuration
- connection_id
- name
title: UpdateModelRequest
Enrichment:
type: object
properties:
configuration:
$ref: '#/components/schemas/EnricherConfiguration'
connection_id:
type: string
format: uuid
enricher_id:
type: string
format: uuid
description: Must be provided to update an existing enrichment
fields:
type: array
items:
$ref: '#/components/schemas/ModelField'
description: If not provided, all fields will be enabled.
mappings:
$ref: '#/components/schemas/EnricherMapping'
title: Enrichment
ConfigurationValue:
type: object
properties:
items:
type: array
items:
description: Any type
type:
type: string
title: ConfigurationValue
EnricherMapping:
type: object
additionalProperties:
type: string
description: A map of parent model Source Name to child model Source Name. For example, if your model has a field called `work_email` and the enricher accepts a field called `email`, you'd send a map of `{"work_email":"email"}`. The set of required input mappings varies based on the configuration of the enrichment. You can use the `enrichment/{connection_id}/inputfields` API to discover available input field combinations for a given configuration.
title: EnricherMapping
EnricherConfiguration:
type: object
additionalProperties:
description: Any type
description: 'Similar to a model configuration, this configures the enricher. For example, if you wanted to use Apollo to enrich people, you would send `{"object": "people"}` as the configuration. Each enricher configuration can be found in the connection configuration docs.'
title: EnricherConfiguration
SyncSourceMetaResponse:
type: object
properties:
configuration:
type: object
additionalProperties:
$ref: '#/components/schemas/ConfigurationValue'
description: Additional configuration fields available for this source, keyed by field name.
items:
type:
- object
- 'null'
additionalProperties:
$ref: '#/components/schemas/SourceMeta'
description: Map of configuration item name to its metadata (available values, required-one-of groups).
requires_one_of:
type:
- array
- 'null'
items:
type: string
description: Configuration items where exactly one must be selected by the caller.
title: SyncSourceMetaResponse
ModelRelationTo:
type: object
properties:
field:
type: string
model_id:
type: string
format: uuid
title: ModelRelationTo
ModelSample:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/SampleRecord'
warnings:
type: array
items:
type: string
title: ModelSample
SampleRecord:
type: object
additionalProperties:
type: object
additionalProperties:
description: Any type
description: 'A map of `fieldSource` -> `fieldName: fieldValue`. Because there may be field name conflicts between the base model and enrichments, the base model fields are placed in a map under the model ID. Fields from enrichments are placed under the enricher ID.'
title: SampleRecord
ApiError:
type: object
properties:
key:
type: string
message:
type: string
metadata:
type: object
additionalProperties:
description: Any type
status:
type: integer
title: ApiError
securitySchemes:
bearerUserAPIKey:
type: http
scheme: bearer
description: Bearer user API key
orgScopedAPIKey:
type: http
scheme: basic
description: Basic organization-scoped API key
bearerPartnerKey:
type: http
scheme: bearer
description: Bearer partner API key