Preview Model | Polytomic Docs

curl -X POST https://app.polytomic.com/api/model-preview \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "configuration": {
    "table": "public.users"
  },
  "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "name": "Users"
}'

{
  "data": {
    "configuration": {
      "table": "public.contacts"
    },
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "enricher": {
      "configuration": {},
      "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
      "enricher_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
      "fields": [
        {
          "name": "phone_number"
        }
      ],
      "mappings": {}
    },
    "fields": [
      {
        "created_at": "2024-01-15T09:30:00Z",
        "created_by": {
          "id": "12345678-1234-1234-1234-123456789012",
          "name": "John Doe",
          "type": "user"
        },
        "description": "Unique identifier",
        "example": null,
        "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
        "label": "ID",
        "name": "id",
        "remote_type": "string",
        "type": "string",
        "unique": true,
        "updated_at": "2024-01-15T09:30:00Z",
        "user_added": false
      }
    ],
    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "identifier": "id",
    "name": "Contacts",
    "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "policies": [
      "248df4b7-aa70-47b8-a036-33ac447e668d"
    ],
    "relations": [
      {
        "from": "id",
        "to": {
          "field": "user_id",
          "model_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
        }
      }
    ],
    "tracking_columns": [
      "string"
    ],
    "type": "postgresql",
    "updated_at": "2024-01-15T09:30:00Z",
    "updated_by": {
      "id": "12345678-1234-1234-1234-123456789012",
      "name": "John Doe",
      "type": "user"
    },
    "version": 1,
    "labels": [
      {}
    ]
  },
  "job": {
    "error": "error message",
    "job_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "result": null,
    "status": "created",
    "type": "createmodel"
  }
}

Previews the fields a model exposes without saving the model.

The response contains the previewed model, including the fields it exposes. With async=true, the response contains a job instead; poll the job until it completes to retrieve the field list.

The model is not saved, and policies and labels are ignored. Use this endpoint to validate a query or configuration before calling POST /api/models to save it.

Field type overrides

Use field_overrides to choose types for detected source fields on CSV file, HTTP API, Google Sheets, and MongoDB models. Other model types reject overrides. Keep additional_fields for user-defined fields.

For example, include this fragment in a complete model request to treat amount as a number:

{
  "field_overrides": {
    "amount": { "type": "number" }
  }
}

Use fields separately to choose which fields to publish. The response’s fields[].type contains each published field’s effective type.

On update, only supplied override entries change types. Omitted entries, an empty map, or null preserve current types, including types chosen in the UI. Removing an entry does not restore its inferred type; supply another concrete type to change it. There is no separate inferred-type or override-state map in the response.

Authentication

AuthorizationBearer

Bearer user API key

AuthorizationBasic

Basic organization-scoped API key

Query parameters

asyncbooleanOptional

Run in the background and return a job instead of the result.

Request

This endpoint expects an object.

configurationmap from strings to anyRequired

Model configuration for the source connection type

connection_idstringRequiredformat: "uuid"

Connection ID of the model's source, which cannot be changed after the model is created

namestringRequired

Model name

additional_fieldslist of objects or nullOptional

User-defined fields to add to the model alongside its source fields

enricherobjectOptional

Enrichment to apply to the model

field_overridesmap from strings to objects or nullOptional

Type updates keyed by exact source field name, for models that support type selection. Applies only to detected source fields and does not publish them. Omitted entries retain their current types; an empty or omitted map leaves all types unchanged.

fieldslist of strings or nullOptional

Technical/source field names to publish in the model. Use source names, not model-field UUIDs or display labels. For example, use dealname rather than Deal Name. Omit or pass an empty array to publish all standard source fields.

identifierstringOptional

Source field name of the model's unique identifier

organization_idstring or nullOptionalformat: "uuid"

Ignored for user and organization-scoped API keys, which always act in their own organization

policieslist of strings or nullOptional

Permissions policy IDs applied to the model. On update, a non-empty list replaces the model’s policies and an empty or omitted list leaves them unchanged.

relationslist of objects or nullOptional

Joins from this model's fields to fields on other models

tracking_columnslist of strings or nullOptional

Source field names used to detect changed records

labelslist of strings or nullOptionalDeprecated

Deprecated; ignored

Response

dataobjectOptional

The model

jobobjectOptional

Background job running the request when async is true

Errors

400

Bad Request Error

404

Not Found Error

500

Internal Server Error