---
title: "Create Model"
method: POST
path: "/api/models"
tags: ["Models"]
---

# Create Model

`POST /api/models`

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.

## Query parameters

- `async` boolean

## Headers

- `X-Polytomic-Version` string

## Request body

- CreateModelRequest
  - `additional_fields` ModelModelFieldRequest[], nullable
    - `example` string
    - `label` string, required
    - `name` string, required
    - `type` string, required
  - `configuration` object, required
  - `connection_id` string, uuid, required
  - `enricher` Enrichment
    - `configuration` EnricherConfiguration — 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.
    - `connection_id` string, uuid
    - `enricher_id` string, uuid — Must be provided to update an existing enrichment
    - `fields` ModelField[] — If not provided, all fields will be enabled.
      - `created_at` string, date-time
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `description` string
      - `example` unknown
      - `id` string, uuid
      - `label` string
      - `name` string
      - `remote_type` string
      - `type` string
      - `unique` boolean
      - `updated_at` string, date-time
      - `user_added` boolean
    - `mappings` EnricherMapping — 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.
  - `fields` string[], nullable
  - `identifier` string
  - `labels` string[], nullable
  - `name` string, required
  - `organization_id` string, uuid, nullable
  - `policies` string[], nullable
  - `relations` ModelRelation[], nullable
    - `from` string
    - `to` ModelRelationTo
      - `field` string
      - `model_id` string, uuid
  - `tracking_columns` string[], nullable

## Response `200`

OK

- ModelResponseEnvelope
  - `data` ModelResponse
    - `configuration` object
    - `connection_id` string, uuid
    - `created_at` string, date-time
    - `created_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string
    - `enricher` Enrichment
      - `configuration` EnricherConfiguration — 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.
      - `connection_id` string, uuid
      - `enricher_id` string, uuid — Must be provided to update an existing enrichment
      - `fields` ModelField[] — If not provided, all fields will be enabled.
        - `created_at` string, date-time
        - `created_by` OutputActor
          - `id` string, uuid
          - `name` string
          - `type` string
        - `description` string
        - `example` unknown
        - `id` string, uuid
        - `label` string
        - `name` string
        - `remote_type` string
        - `type` string
        - `unique` boolean
        - `updated_at` string, date-time
        - `user_added` boolean
      - `mappings` EnricherMapping — 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.
    - `fields` ModelField[]
      - `created_at` string, date-time
      - `created_by` OutputActor
        - `id` string, uuid
        - `name` string
        - `type` string
      - `description` string
      - `example` unknown
      - `id` string, uuid
      - `label` string
      - `name` string
      - `remote_type` string
      - `type` string
      - `unique` boolean
      - `updated_at` string, date-time
      - `user_added` boolean
    - `id` string, uuid
    - `identifier` string
    - `labels` LabelLabel[]
    - `name` string
    - `organization_id` string, uuid
    - `policies` string[]
    - `relations` Relation[]
      - `from` string
      - `to` RelationTo
        - `field` string
        - `model_id` string, uuid
    - `tracking_columns` string[]
    - `type` string
    - `updated_at` string, date-time
    - `updated_by` OutputActor
      - `id` string, uuid
      - `name` string
      - `type` string
    - `version` integer
  - `job` JobResponse
    - `error` string, nullable — Error message if the job failed.
    - `job_id` string, uuid — Identifier of the job.
    - `result` unknown
    - `status` 'created' | 'running' | 'done' | 'failed'
    - `type` string — Job type. Matches the type used to fetch the job.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `500` — Internal Server Error

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/versions/5e9bcd4cfb2d/schema)