> This page is for version 2025-09-18 (default).
> For other versions, use one of these documentation indexes:
> - 2025-09-18 (default): https://apidocs.polytomic.com/2025-09-18/llms.txt
> - 2024-02-08: https://apidocs.polytomic.com/2024-02-08/llms.txt
> - 2023-04-25: https://apidocs.polytomic.com/2023-04-25/llms.txt
> - 2022-12-12: https://apidocs.polytomic.com/2022-12-12/llms.txt
> - 2021-05-23: https://apidocs.polytomic.com/2021-05-23/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.polytomic.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server.

# Update Model

PUT https://app.polytomic.com/api/models/{id}
Content-Type: application/json

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.

Reference: https://apidocs.polytomic.com/api-reference/models/update

## Authentication

- `Authorization` header (bearer token, required) — Bearer user API key
- `Authorization` header (basic auth, required) — Basic organization-scoped API key

## Request

### Path parameters

- `id` (string, required) — Model ID

### Query parameters

- `async` (boolean, optional) — Run in the background and return a job instead of the result.

### Body (application/json)

This endpoint expects an UpdateModelRequest.

- `configuration` (map from string to any, required) — Model configuration for the source connection type
- `connection_id` (string, required) — Connection ID of the model's source
- `name` (string, required) — Model name
- `additional_fields` (list of ModelModelFieldRequest, optional, nullable) — User-defined fields to add to the model alongside its source fields
- `enricher` (Enrichment, optional) — Enrichment to apply to the model
- `fields` (list of string, optional, nullable) — 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.
- `identifier` (string, optional) — Source field name of the model's unique identifier
- `labels` (list of string, optional, nullable)
- `organization_id` (string, optional, nullable)
- `policies` (list of string, optional, nullable) — Permissions policy IDs applied to the model
- `refresh` (boolean, optional) — Whether to refresh the enricher's fields and example values
- `relations` (list of ModelRelation, optional, nullable) — Joins from this model's fields to fields on other models
- `tracking_columns` (list of string, optional, nullable) — Source field names used to detect changed records

## Response

### 200

OK

- `data` (ModelResponse, optional) — The model
- `job` (JobResponse, optional) — Background job running the request when async is true

## Errors

### 400 Bad Request Error

Bad Request

- `key` (string, optional) — Machine-readable error key, when the error has one
- `message` (string, optional) — Error message
- `metadata` (map from string to any, optional) — Structured details about the error, when available
- `status` (integer, optional) — HTTP status code

### 404 Not Found Error

Not Found

- `key` (string, optional) — Machine-readable error key, when the error has one
- `message` (string, optional) — Error message
- `metadata` (map from string to any, optional) — Structured details about the error, when available
- `status` (integer, optional) — HTTP status code

### 500 Internal Server Error

Internal Server Error

- `key` (string, optional) — Machine-readable error key, when the error has one
- `message` (string, optional) — Error message
- `metadata` (map from string to any, optional) — Structured details about the error, when available
- `status` (integer, optional) — HTTP status code

## Types

### ModelModelFieldRequest

- `label` (string, required) — Display label of the field
- `name` (string, required) — Name of the field
- `type` (string, required) — Data type of the field
- `example` (string, optional) — Example value of the field

### Enrichment

- `configuration` (map from string to any, optional) — Enricher configuration
- `connection_id` (string, optional) — Connection ID of the enrichment source
- `enricher_id` (string, optional) — Must be provided to update an existing enrichment
- `fields` (list of ModelField, optional) — If not provided, all fields will be enabled.
- `mappings` (map from string to string, optional) — Mappings from model fields to enricher input fields

### ModelRelation

- `from` (string, optional) — Source field name on this model
- `to` (ModelRelationTo, optional) — Field on the related model

### ModelResponse

- `configuration` (map from string to any, optional) — Model configuration for the source connection type
- `connection_id` (string, optional) — Connection ID of the model's source
- `created_at` (datetime, optional) — When the model was created
- `created_by` (OutputActor, optional) — Actor that created the model
- `enricher` (Enrichment, optional) — Enrichment applied to the model
- `fields` (list of ModelField, optional) — Fields published by the model
- `id` (string, optional) — Model ID
- `identifier` (string, optional) — Source field name of the model's unique identifier
- `labels` (list of LabelLabel, optional)
- `name` (string, optional) — Model name
- `organization_id` (string, optional) — Organization ID of the model
- `policies` (list of string, optional) — Permissions policy IDs applied to the model
- `relations` (list of Relation, optional) — Joins from this model's fields to fields on other models
- `tracking_columns` (list of string, optional) — Source field names used to detect changed records
- `type` (string, optional) — Connection type of the model's source
- `updated_at` (datetime, optional) — When the model was last updated
- `updated_by` (OutputActor, optional) — Actor that most recently updated the model
- `version` (integer, optional) — Model version; increments when the configuration or field structure changes

### JobResponse

- `error` (string, optional, nullable) — Error message if the job failed
- `job_id` (string, optional) — Identifier of the job
- `result` (any, optional) — Job result. Shape depends on the job type; only populated once status is done.
- `status` (enum, optional) — Current execution status of the job (e.g. running, done, failed)
  - Allowed values: `created`, `running`, `done`, `failed`
- `type` (string, optional) — Job type. Matches the type used to fetch the job.

### ModelField

- `created_at` (datetime, optional) — When the field was created
- `created_by` (OutputActor, optional) — Actor that created the field
- `description` (string, optional) — Description of the field
- `example` (any, optional) — Example value for the field
- `id` (string, optional) — Model field ID
- `label` (string, optional) — Display label for the field
- `name` (string, optional) — Source field name
- `remote_type` (string, optional) — Field type reported by the source
- `type` (string, optional) — Polytomic field type
- `unique` (boolean, optional) — Whether the field uniquely identifies records
- `updated_at` (datetime, optional) — When the field was last updated
- `user_added` (boolean, optional) — Whether the field is user-defined rather than discovered from the source

### ModelRelationTo

- `field` (string, optional) — Source field name on the related model
- `model_id` (string, optional) — Model ID of the related model

### OutputActor

- `id` (string, optional) — ID of the actor, such as the user ID for a user
- `name` (string, optional) — Display name of the actor
- `type` (string, optional) — Kind of actor, such as user

### LabelLabel

### Relation

- `from` (string, optional) — Source field name on this model
- `to` (RelationTo, optional) — Field on the related model

### RelationTo

- `field` (string, optional) — Source field name on the related model
- `model_id` (string, optional) — Model ID of the related model

## Examples

**Request**

```json
{
  "configuration": {
    "table": "public.users"
  },
  "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "name": "Users"
}
```

**Response**

```json
{
  "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",
    "labels": [
      {}
    ],
    "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
  },
  "job": {
    "error": "error message",
    "job_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "result": null,
    "status": "created",
    "type": "createmodel"
  }
}
```

**SDK Code**

```python
import requests

url = "https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d"

payload = {
    "configuration": { "table": "public.users" },
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "name": "Users"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"configuration":{"table":"public.users"},"connection_id":"248df4b7-aa70-47b8-a036-33ac447e668d","name":"Users"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d"

	payload := strings.NewReader("{\n  \"configuration\": {\n    \"table\": \"public.users\"\n  },\n  \"connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n  \"name\": \"Users\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"configuration\": {\n    \"table\": \"public.users\"\n  },\n  \"connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n  \"name\": \"Users\"\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"configuration\": {\n    \"table\": \"public.users\"\n  },\n  \"connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n  \"name\": \"Users\"\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d', [
  'body' => '{
  "configuration": {
    "table": "public.users"
  },
  "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "name": "Users"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"configuration\": {\n    \"table\": \"public.users\"\n  },\n  \"connection_id\": \"248df4b7-aa70-47b8-a036-33ac447e668d\",\n  \"name\": \"Users\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "configuration": ["table": "public.users"],
  "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
  "name": "Users"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://app.polytomic.com/api/models/248df4b7-aa70-47b8-a036-33ac447e668d")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```