reference.md

# Reference
## BulkSync
<details><summary><code>client.bulkSync.list() -> BulkSyncListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists bulk syncs in the caller's organization.

Results are ordered by `updated_at` descending, with `id` as a tiebreaker for
syncs modified at the same instant. Pagination uses an opaque
`pagination.next_page_token` returned in the response; pass it back as the
`page_token` query parameter to fetch the next page. The `limit` parameter is
optional, and the default and maximum page size is 50 syncs.

> 📘 To retrieve a specific sync, use
> [`GET /api/bulk/syncs/{id}`](../../../api-reference/bulk-sync/get)
> instead of filtering the list client-side.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().list(
    BulkSyncListRequest
        .builder()
        .active(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**active:** `Optional<Boolean>` — Filter to only active (true) or only paused (false) syncs. Omit to return both.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.create(request) -> BulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new bulk sync.

Bulk syncs are used for the ELT pattern (Extract, Load, and Transform), where you want to sync un-transformed data to your data warehouses, databases, or cloud storage buckets like S3.

All of the functionality described in [the product
documentation](https://docs.polytomic.com/docs/bulk-syncs) is configurable via
the API.

Sample code examples:

- [Bulk sync (ELT) from Salesforce to S3](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-s-3)
- [Bulk sync (ELT) from Salesforce to Snowflake](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-snowflake)
- [Bulk sync (ELT) from HubSpot to PostgreSQL](../../../guides/code-examples/bulk-sync-elt-from-hub-spot-to-postgre-sql)

## Connection specific configuration

The `destination_configuration` is integration-specific configuration for the
selected bulk sync destination. This includes settings such as the output schema
and is required when creating a new sync.

The `source_configuration` is optional. It allows configuration for how
Polytomic reads data from the source connection. This will not be available for
integrations that do not support additional configuration.

Consult the [connection configurations](../../../guides/configuring-your-connections/overview)
to see configurations for particular integrations (for example, [here](../../../guides/configuring-your-connections/connections/postgre-sql#source-1) is the available source configuration for the PostgreSQL bulk sync source).

## Defaults and selection behavior

If `schemas` is omitted, the sync is created with all available source schemas
selected. Pass `schemas` explicitly if you want the initial sync to include
only a subset of tables or objects.

Schedule times are interpreted in UTC.

When omitted, automatic discovery defaults are conservative:

- `automatically_add_new_objects` defaults to not enabling newly discovered
  source objects automatically.
- `automatically_add_new_fields` defaults to enabling newly discovered fields
  on already selected objects.
- `normalize_names` defaults to enabled.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().create(
    CreateBulkSyncRequest
        .builder()
        .defaultSchedule(
            BulkSyncDefaultScheduleRequest
                .builder()
                .frequency(ScheduleFrequency.MANUAL)
                .build()
        )
        .destinationConnectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .name("My Bulk Sync")
        .sourceConnectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .destinationConfiguration(
            new HashMap<String, Object>() {{
                put("schema", "my_schema");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**active:** `Optional<Boolean>` — Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
    
</dd>
</dl>

<dl>
<dd>

**additionalSchedules:** `Optional<List<BulkSyncAdditionalScheduleRequest>>` — Additional bulk sync schedules. Schedule times are interpreted in UTC.
    
</dd>
</dl>

<dl>
<dd>

**automaticallyAddNewFields:** `Optional<BulkDiscover>` 
    
</dd>
</dl>

<dl>
<dd>

**automaticallyAddNewObjects:** `Optional<BulkDiscover>` 
    
</dd>
</dl>

<dl>
<dd>

**concurrencyLimit:** `Optional<Integer>` — Override the default concurrency limit for this sync.
    
</dd>
</dl>

<dl>
<dd>

**dataCutoffTimestamp:** `Optional<OffsetDateTime>` — Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
    
</dd>
</dl>

<dl>
<dd>

**defaultSchedule:** `BulkSyncDefaultScheduleRequest` 
    
</dd>
</dl>

<dl>
<dd>

**destinationConfiguration:** `Map<String, Object>` — Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.
    
</dd>
</dl>

<dl>
<dd>

**destinationConnectionId:** `String` — Unique identifier of the connection rows are written to.
    
</dd>
</dl>

<dl>
<dd>

**disableRecordTimestamps:** `Optional<Boolean>` — When true, Polytomic will not add its own timestamp columns to destination rows.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `Optional<BulkSyncTargetMode>` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable name for the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**normalizeNames:** `Optional<BulkNormalizeNames>` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` — Organization the sync is created in. Only used by partner callers; normal callers always create syncs in their own organization.
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` — Identifiers of permissions policies applied to the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**resyncConcurrencyLimit:** `Optional<Integer>` — Override the default resync concurrency limit for this sync.
    
</dd>
</dl>

<dl>
<dd>

**schemas:** `Optional<List<CreateBulkSyncRequestSchemasItem>>` — List of schemas to sync; if omitted, all schemas will be selected for syncing.
    
</dd>
</dl>

<dl>
<dd>

**sourceConfiguration:** `Optional<Map<String, Object>>` — Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.
    
</dd>
</dl>

<dl>
<dd>

**sourceConnectionId:** `String` — Unique identifier of the connection rows are read from.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.get(id) -> BulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a bulk sync by ID.

The response includes the sync's top-level configuration — source, destination,
schedules, and discovery settings.

- To check whether the sync is running and see the most-recent execution result,
  use [`GET /api/bulk/syncs/{id}/status`](../../../../api-reference/bulk-sync/get-status).
- To inspect which schemas are selected and how they are configured, use
  [`GET /api/bulk/syncs/{id}/schemas`](../../../../api-reference/bulk-sync/schemas/list).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().get(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    BulkSyncGetRequest
        .builder()
        .refreshSchemas(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**refreshSchemas:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.update(id, request) -> BulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing bulk sync's top-level configuration.

Updating a bulk sync is a **full replacement** of the sync's top-level
configuration. Every field in the request body is written to the sync; any
field you omit is cleared or reset to its default value.

To make a partial change — for example, toggling `active` or swapping a
schedule — fetch the current sync with
[`GET /api/bulk/syncs/{id}`](../../../../api-reference/bulk-sync/get),
modify the fields you want to change, and send the complete object back in
the update request.

Updates to `active`, `schedules`, and `policies` take effect immediately.
Changes to source or destination configuration take effect on the sync's
next execution.

Because omitted fields are reset to their defaults, the discovery and
naming options behave the same as on create when left out:

- `automatically_add_new_objects` resets to not enabling newly discovered
  source objects automatically.
- `automatically_add_new_fields` resets to enabling newly discovered
  fields on already selected objects.
- `normalize_names` resets to enabled.

Send the existing values explicitly if you want to preserve a non-default or
non-empty setting.

> 📘 Updating schemas
>
> When `schemas` is present, it replaces the sync's schema selection: schemas
> not in the list are disabled. When `schemas` is omitted or empty, the sync's
> schemas are left unchanged. Use the
> [Update Bulk Sync Schemas](../../../../api-reference/bulk-sync/schemas/patch)
> endpoint to change a subset of schemas, or
> [Update Bulk Sync Schema](../../../../api-reference/bulk-sync/schemas/update)
> to replace a single schema's configuration.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateBulkSyncRequest
        .builder()
        .defaultSchedule(
            BulkSyncDefaultScheduleRequest
                .builder()
                .frequency(ScheduleFrequency.MANUAL)
                .build()
        )
        .destinationConnectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .name("My Bulk Sync")
        .sourceConnectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .destinationConfiguration(
            new HashMap<String, Object>() {{
                put("schema", "my_schema");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync to update.
    
</dd>
</dl>

<dl>
<dd>

**active:** `Optional<Boolean>` — Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
    
</dd>
</dl>

<dl>
<dd>

**additionalSchedules:** `Optional<List<BulkSyncAdditionalScheduleRequest>>` — Additional bulk sync schedules. Schedule times are interpreted in UTC.
    
</dd>
</dl>

<dl>
<dd>

**automaticallyAddNewFields:** `Optional<BulkDiscover>` 
    
</dd>
</dl>

<dl>
<dd>

**automaticallyAddNewObjects:** `Optional<BulkDiscover>` 
    
</dd>
</dl>

<dl>
<dd>

**concurrencyLimit:** `Optional<Integer>` — Override the default concurrency limit for this sync.
    
</dd>
</dl>

<dl>
<dd>

**dataCutoffTimestamp:** `Optional<OffsetDateTime>` — Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
    
</dd>
</dl>

<dl>
<dd>

**defaultSchedule:** `BulkSyncDefaultScheduleRequest` 
    
</dd>
</dl>

<dl>
<dd>

**destinationConfiguration:** `Map<String, Object>` — Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.
    
</dd>
</dl>

<dl>
<dd>

**destinationConnectionId:** `String` — Unique identifier of the connection rows are written to.
    
</dd>
</dl>

<dl>
<dd>

**disableRecordTimestamps:** `Optional<Boolean>` — When true, Polytomic will not add its own timestamp columns to destination rows.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `Optional<BulkSyncTargetMode>` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable name for the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**normalizeNames:** `Optional<BulkNormalizeNames>` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` — Organization the sync belongs to. Only used by partner callers; normal callers are always scoped to their own organization.
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` — Identifiers of permissions policies applied to the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**resyncConcurrencyLimit:** `Optional<Integer>` — Override the default resync concurrency limit for this sync.
    
</dd>
</dl>

<dl>
<dd>

**schemas:** `Optional<List<UpdateBulkSyncRequestSchemasItem>>` — Schemas to sync. Schemas not in the list are disabled; if omitted or empty, the sync's schemas are left unchanged.
    
</dd>
</dl>

<dl>
<dd>

**sourceConfiguration:** `Optional<Map<String, Object>>` — Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.
    
</dd>
</dl>

<dl>
<dd>

**sourceConnectionId:** `String` — Unique identifier of the connection rows are read from.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a bulk sync, cancelling any running executions.

Any execution that is currently running is cancelled before the sync record is
removed.

> 🚧 All associated schedules, schema configurations, and execution history are
> deleted along with the sync.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().delete(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    BulkSyncDeleteRequest
        .builder()
        .refreshSchemas(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**refreshSchemas:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.activate(id, request) -> ActivateSyncEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Sets whether a bulk sync is active.

Only active syncs are eligible to execute on their configured schedule.
Deactivating a sync prevents future scheduled runs and requests cancellation of
any execution that is currently in progress.

> 📘 To start or stop a running execution directly, use
> [`POST /api/bulk/syncs/{id}/executions`](../../../../../api-reference/bulk-sync/start)
> or
> [`POST /api/bulk/syncs/{id}/cancel`](../../../../../api-reference/bulk-sync/cancel).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().activate(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActivateSyncInput
        .builder()
        .active(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `ActivateSyncInput` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.cancel(id) -> CancelBulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Requests cancellation of any running executions on a bulk sync.

Cancellation is asynchronous. A successful response means the cancellation
signal has been queued; the running execution continues until the signal is
processed. Poll `GET /api/bulk/syncs/{id}/status` until the current execution
reaches a terminal state (`completed`, `canceled`, or `failed`) to confirm
cancellation has taken effect.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().cancel("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — The active execution of this bulk sync ID will be cancelled.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.start(id, request) -> BulkSyncExecutionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Starts a new execution of a bulk sync.

This endpoint returns the execution record immediately after the run is queued
or started. Use the execution ID with the bulk-sync execution endpoints if you
need to monitor progress in detail.

## Execution modes

- Set `test=true` to validate the sync without writing to the destination.
- Use `resync_mode` for destructive or full-refresh style reruns.
- `test` and `resync_mode` are mutually exclusive.

The legacy `resync` boolean is no longer accepted on this v5 endpoint. Send
`resync_mode` instead.

If another execution is already running, the endpoint returns `409 Conflict`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().start(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    StartBulkSyncRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**fetchMode:** `Optional<BulkFetchMode>` 
    
</dd>
</dl>

<dl>
<dd>

**resyncMode:** `Optional<BulkResyncMode>` 
    
</dd>
</dl>

<dl>
<dd>

**schemas:** `Optional<List<String>>` — Optional list of schema IDs to include in this execution. If empty, all enabled schemas are included.
    
</dd>
</dl>

<dl>
<dd>

**test:** `Optional<Boolean>` — When true, runs a test execution that validates the configuration and syncs up to 5 records per schema. Mutually exclusive with resync_mode.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.getStatus(id) -> BulkSyncStatusEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the current status of a bulk sync.

The response includes the sync's current active/inactive state together with
information about the most recent execution — its status, start time, and any
errors — making this endpoint well-suited for health checks and monitoring
dashboards.

For the complete execution history, use
[`GET /api/bulk/syncs/{id}/executions`](../../../../../api-reference/bulk-sync/executions/list).
For the full details of a specific run, including per-schema breakdowns, use
[`GET /api/bulk/syncs/{id}/executions/{exec_id}`](../../../../../api-reference/bulk-sync/executions/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().getStatus("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.getSource(id) -> BulkSyncSourceEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists the schemas (tables or objects) available on a connection for use as a bulk sync source, optionally including per-schema field details.

The response reflects what the
connection currently has cached; if the upstream source has changed, trigger
a refresh first with
[`POST /api/connections/{id}/schemas/refresh`](../../../../../api-reference/schemas/refresh).

These are the schemas available for selection, not the schemas already
configured on any particular sync. To inspect schemas on a running sync, use
[`GET /api/bulk/syncs/{id}/schemas`](../../../../../api-reference/bulk-sync/schemas/list).

Pass `include_fields=true` to receive per-schema field details in a single call.
Omit it when you only need the schema list, as field enumeration can be slow for
large sources.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().getSource(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    BulkSyncGetSourceRequest
        .builder()
        .includeFields(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**includeFields:** `Optional<Boolean>` — When true, include per-schema field lists in the response. Set to false for a smaller payload when field details are not needed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.getDestination(id) -> BulkSyncDestEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Describes the destination configuration schema a connection accepts when used as a bulk sync destination.

The response is a JSON Schema object describing the shape of the
`destination_configuration` field you must supply when
[creating](../../../../../api-reference/bulk-sync/create) or
[updating](../../../../../api-reference/bulk-sync/update) a bulk sync that uses this
connection as its destination. Required fields vary by connection type.

> 📘 Fetch this endpoint once per connection type rather than once per sync.
> The configuration schema is the same for all syncs sharing the same
> destination connection.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().getDestination("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Connections
<details><summary><code>client.connections.getTypes() -> ConnectionTypeResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all connection types supported by this deployment.

Each entry includes per-type metadata:

- The available operations the connection type supports.
- Its category.
- Whether the connection type is enabled for the caller's organization.
- Which modes (source, destination, enrichment) it can act as.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getTypes();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.getConnectionTypeSchema(id) -> JsonschemaSchema</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the JSON schema for a connection type.

This schema is intended for building forms or validating configuration payloads
client-side. It describes the structure Polytomic expects when you create or
update a connection of the given type.

The response is metadata about the shape of the configuration, not a live
connection instance and not a set of current credential values.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getConnectionTypeSchema("postgresql");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Connection type identifier (e.g. postgresql, salesforce, hubspot).
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.getTypeParameterValues(type, request) -> ConnectionParameterValuesResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns completion values for parameter fields on a connection type.

This endpoint is useful during connection setup, before a connection exists or
before you want to persist it. The supplied `parameters` are applied to a
temporary in-memory connection shape and used to resolve dependent options.

When an endpoint requires upstream authorization before it can return values,
Polytomic returns an error instead of guessing. In that case, complete the
authorization flow first and call the endpoint again.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getTypeParameterValues(
    "type",
    GetConnectionTypeParameterValuesRequestSchema
        .builder()
        .field("field")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**type:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**field:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**parameters:** `Optional<Map<String, Object>>` 
    
</dd>
</dl>

<dl>
<dd>

**query:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.list() -> ConnectionListResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists every connection in the caller's organization, with sensitive fields redacted.

Sensitive configuration values — passwords, API tokens, private keys — are
redacted from all responses. To understand which fields a connection type
exposes, consult the parameter schema returned by
[`GET /api/connection_types`](../../api-reference/connections/get-types).

To inspect the data objects available on a specific connection, use
[`POST /api/connections/{id}/schemas/refresh`](../../api-reference/schemas/refresh)
followed by [`GET /api/connections/{id}/schemas/status`](../../api-reference/schemas/get-status).

## Observed rate limits

You can use `rate_limit` to inspect observed rate limiting separately from
Connection health. A Connection can be healthy while Polytomic has an active
rate-limit marker. Shared Connections combine observations recorded for their
own ID and their root Connection. Observations recorded only for another shared
copy are not included.

When these observed periods overlap or touch, `limited_since` reflects the start
of the continuous period and `expires_at` reflects its latest expiry. An expired
period separated from the active period by a gap does not extend that start.

> ⚠️ Observation, not a capacity guarantee
>
> An active marker does not mean every endpoint or sync is blocked. No active
> marker does not guarantee that the upstream service has capacity. The marker
> expiry can be extended and is not a promised provider reset or exact retry time.

If any required lookup is unavailable, `rate_limit` is `null`. This does not change
`status` or `status_error`, and the Connection response is still returned.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.create(request) -> CreateConnectionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new connection of the specified type.

Use [`GET /api/connection_types`](../../api-reference/connections/get-types) to retrieve the
list of available types and their parameter schemas. The `configuration`
object is type-specific; consult the [integration
guides](../../guides/configuring-your-connections/overview)
for the required and optional fields for each type.

> 📘 Polytomic validates the connection against the upstream service
> immediately on creation. The request will fail if the credentials or
> endpoint cannot be reached.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().create(
    CreateConnectionRequestSchema
        .builder()
        .name("My Postgres Connection")
        .type("postgresql")
        .configuration(
            new HashMap<String, Object>() {{
                put("database", "example");
                put("hostname", "postgres.example.com");
                put("password", "********");
                put("port", 5432);
                put("username", "user");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**configuration:** `Map<String, Object>` 
    
</dd>
</dl>

<dl>
<dd>

**healthcheckInterval:** `Optional<String>` — Override interval for connection health checking.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**redirectUrl:** `Optional<String>` — URL to redirect to after completing OAuth flow.
    
</dd>
</dl>

<dl>
<dd>

**type:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**validate:** `Optional<Boolean>` — Validate connection configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.connect(request) -> ConnectCardResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a Polytomic Connect session and returns a URL for creating or reconnecting a Connection.

Open the returned URL, or send it to the person who will set up the Connection.
Polytomic Connect guides them through authentication and configuration, then
redirects them to `redirect_url`.

Each session can create or reconnect one Connection.

See also:

- [Embedding authentication](../../../guides/embedding-authentication), a guide to using Polytomic Connect.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().connect(
    ConnectCardRequest
        .builder()
        .name("Salesforce Connection")
        .redirectUrl("redirect_url")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connection:** `Optional<String>` — The id of an existing connection to update.
    
</dd>
</dl>

<dl>
<dd>

**dark:** `Optional<Boolean>` — Whether to use the dark theme for the Connect modal.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Name of the new connection. Must be unique per organization.
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**redirectUrl:** `String` — URL to redirect to after connection is created.
    
</dd>
</dl>

<dl>
<dd>

**ttl:** `Optional<Integer>` — Connect session lifetime in seconds. Defaults to 300 and cannot exceed 604800.
    
</dd>
</dl>

<dl>
<dd>

**type:** `Optional<String>` — Connection type to create.
    
</dd>
</dl>

<dl>
<dd>

**useOrganizationName:** `Optional<Boolean>` — Whether to display the target organization name instead of the partner name in the Connect modal. Defaults to false; organizations without a partner always display their organization name.
    
</dd>
</dl>

<dl>
<dd>

**whitelist:** `Optional<List<String>>` — List of connection types which are allowed to be created. Ignored if type is set.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.getConnectSession() -> ConnectSessionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns trusted metadata for the authenticated Polytomic Connect session.

Returns the trusted metadata stored for a Polytomic Connect session. Authenticate with the opaque Connect token in the `token` query parameter.

The response includes the server-enforced connection name, fixed type or whitelist, bound connection ID, completion redirect, branding, and absolute expiration time.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getConnectSession();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.testConnection(request)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Tests a connection configuration.

This endpoint is useful for setup flows that want to verify credentials before
persisting them.

If you provide `connection_id`, Polytomic starts from the saved configuration
for that connection and then applies the request's `configuration` values on
top. This lets callers test a partial change without resending every existing
field.

The request does not persist any configuration changes even when validation
succeeds.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().testConnection(
    TestConnectionRequest
        .builder()
        .type("postgresql")
        .configuration(
            new HashMap<String, Object>() {{
                put("database", "example");
                put("hostname", "postgres.example.com");
                put("password", "password");
                put("port", 5432);
                put("username", "user");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**configuration:** `Map<String, Object>` — Connection configuration to test.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `Optional<String>` — Optional existing connection ID to use as a base for testing. The provided configuration will be merged over the stored configuration for this connection before testing.
    
</dd>
</dl>

<dl>
<dd>

**type:** `String` — The type of connection to test.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.get(id) -> ConnectionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single connection by ID, with sensitive fields redacted.

To inspect the schemas available on this connection, trigger a refresh with
[`POST /api/connections/{id}/schemas/refresh`](../../../api-reference/schemas/refresh) and
track progress via
[`GET /api/connections/{id}/schemas/status`](../../../api-reference/schemas/get-status).

## Observed rate limits

You can use `rate_limit` to inspect observed rate limiting separately from
Connection health. A Connection can be healthy while Polytomic has an active
rate-limit marker. Shared Connections combine observations recorded for their
own ID and their root Connection. Observations recorded only for another shared
copy are not included.

When these observed periods overlap or touch, `limited_since` reflects the start
of the continuous period and `expires_at` reflects its latest expiry. An expired
period separated from the active period by a gap does not extend that start.

> ⚠️ Observation, not a capacity guarantee
>
> An active marker does not mean every endpoint or sync is blocked. No active
> marker does not guarantee that the upstream service has capacity. The marker
> expiry can be extended and is not a promised provider reset or exact retry time.

If any required lookup is unavailable, `rate_limit` is `null`. This does not change
`status` or `status_error`, and the Connection response is still returned.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.update(id, request) -> CreateConnectionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates a connection's configuration.

Connections owned by a managed Harbor return `409 Conflict`. To rename the
Connection, [update its Harbor](../../../api-reference/harbors/update). Customer-managed
Harbor backing Connections remain independently editable.

Updating a connection is a **full replacement** of its configuration. Any
`configuration` field you omit is cleared. To make a partial change, fetch
the current connection with
[`GET /api/connections/{id}`](../../../api-reference/connections/get), apply your edits, and send the
complete object back.

> 📘 The connection is re-validated against the upstream service after every
> update. The request will fail if the new credentials or endpoint cannot be
> reached.

Syncs that are already running when the update is submitted are not
interrupted; the updated configuration takes effect on their next execution.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateConnectionRequestSchema
        .builder()
        .name("My Postgres Connection")
        .configuration(
            new HashMap<String, Object>() {{
                put("database", "example");
                put("hostname", "postgres.example.com");
                put("password", "********");
                put("port", 5432);
                put("username", "user");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**configuration:** `Map<String, Object>` 
    
</dd>
</dl>

<dl>
<dd>

**healthcheckInterval:** `Optional<String>` — Override interval for connection health checking.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**reconnect:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**type:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**validate:** `Optional<Boolean>` — Validate connection configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a connection.

A Connection that backs any active Harbor returns `409 Conflict`, including
when you pass `force=true`. No dependent resources are deleted in this case.
[Delete the Harbor](../../../api-reference/harbors/delete) first. Deleting a managed
Harbor also deletes its managed Connection; deleting a customer-managed Harbor
preserves its backing Connection.

> 🚧 Deleting a connection that is referenced by fieldsets, syncs, bulk
> syncs, or schedules returns `422 connection in use` unless you pass
> `force=true`. With `force=true`, the API deletes those dependent
> resources before removing the connection.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().delete(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ConnectionsDeleteRequest
        .builder()
        .force(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**force:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.getParameterValues(id) -> ConnectionParameterValuesResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns completion values for parameter fields on a persisted connection.

Use this endpoint when the available options for one parameter depend on the
connection's saved credentials or previously selected settings. For example,
after a connection is authorized, the upstream service may be able to return
lists of databases, schemas, or similar selectable values.

For new setup flows, prefer
[`POST /api/connection_types/{type}/parameter_values`](../../../../api-reference/connections/get-type-parameter-values),
which lets you resolve completions before the connection has been created.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getParameterValues("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.getUsage(id) -> GetConnectionUsageEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the connection's API consumption over the last 24 hours, broken down by sync when the backend supports it.

Not all integrations support usage reporting.

- `callsLast24h` is null when the backend does not expose a usage count.
- `reportsSyncStats` is `false`, and `bySync` is empty, when the backend
  reports a total but cannot attribute calls to individual syncs.

When per-sync stats are available, each entry in `bySync` carries a
`categories` breakdown. **Category keys and labels are integration-specific.**
For example, Salesforce reports `rest` and `bulk` categories
(collapsing Bulk API v1 and v2 into a single `bulk` bucket), while another
integration may report an entirely different set or none at all. Treat `key`
as an opaque, backend-defined identifier and use `label` for display; do not
assume a fixed vocabulary across connection types.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().getUsage("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose API consumption should be returned.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## QueryRunner
<details><summary><code>client.queryRunner.runQuery(connectionId, request) -> RunQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Submits a query for asynchronous execution against the connection.

This endpoint returns immediately with a query task ID. It does not wait for
the query to finish. Poll [`GET /api/queries/{id}`](../../../../api-reference/query-runner/get-query) until `status`
reaches `done`, `failed`, or `unknown`. These statuses are terminal.

A Harbor-bound scoped credential can submit freeform SQL only against its
Harbor's backing connection, even if its profile allows other connections.
Other credentials retain their existing connection access. Query results are
stored temporarily and may expire; use the `expires` field from the result
endpoint to understand how long they remain available.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.queryRunner().runQuery(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    RunQueryRequest
        .builder()
        .query("SELECT * FROM table")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the connection to run the query against.
    
</dd>
</dl>

<dl>
<dd>

**query:** `Optional<String>` — The query to execute against the connection.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.queryRunner.getQuery(id) -> QueryResultsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Fetches the latest status for a submitted query and, once complete, returns fields and paginated results.

This endpoint is the second step of the query-runner flow. First call
[`POST /api/connections/{connection_id}/query`](../../../api-reference/query-runner/run-query),
then poll this endpoint with the returned ID.

Results may be paginated across multiple blobs. When that happens, use the
opaque `links.next` and `links.previous` URLs exactly as returned. Do not try to
construct the `page` token yourself.

If the query is still running, the response may include only status metadata.
The terminal statuses are `done`, `failed`, and `unknown`. An `unknown` status
means execution started, but its durable terminal result was lost or expired.
Stop polling when you receive any terminal status.

If the task is complete but the caller is not the same user that created it,
the endpoint returns `404`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.queryRunner().getQuery(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    QueryRunnerGetQueryRequest
        .builder()
        .page("page")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the query task, as returned by POST /api/connections/{connection_id}/query.
    
</dd>
</dl>

<dl>
<dd>

**page:** `Optional<String>` — Opaque pagination token returned in the links.next or links.previous URL of the previous response.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Schemas
<details><summary><code>client.schemas.upsertField(connectionId, schemaId, request)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates or updates user-defined fields on a schema, matched by field_id.

Fields are matched by `field_id`. Reusing an existing `field_id` updates that
field; using a new `field_id` creates a new user-defined field.

This makes the endpoint safe to retry when you are intentionally upserting the
same field definitions. It is not a patch-by-position operation.

If some fields succeed and others fail, the endpoint can return a partial
success response. Validate the response status and message rather than assuming
the whole batch was applied uniformly.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().upsertField(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "public.users",
    UpsertSchemaFieldRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema the fields belong to.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<UserFieldRequest>>` — Fields to create or update on the schema. Existing user-defined fields with the same field_id are replaced.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.deleteField(connectionId, schemaId, fieldId)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Removes a user-defined field from a schema.

Only user-defined fields — those created via
[`POST /api/connections/{connection_id}/schemas/{schema_id}/fields`](../../../../../../../api-reference/schemas/upsert-field)
— can be removed through this endpoint. Fields detected automatically from
the source cannot be deleted here; they are managed through schema refresh.

> 🚧 Deleting a field that is referenced in an active sync mapping may cause
> that sync to error on its next execution. Remove or update any dependent
> mappings before deleting the field.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().deleteField("248df4b7-aa70-47b8-a036-33ac447e668d", "public.users", "first_name");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema the field belongs to.
    
</dd>
</dl>

<dl>
<dd>

**fieldId:** `String` — Identifier of the user-defined field to delete.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.patchField(connectionId, schemaId, fieldId, request) -> SchemaFieldResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Edits a single field on a schema, creating an override for a detected field if needed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().patchField(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "schema_id",
    "field_id",
    PatchSchemaFieldRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Connection holding the schema.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Schema identifier.
    
</dd>
</dl>

<dl>
<dd>

**fieldId:** `String` — Field identifier within the schema.
    
</dd>
</dl>

<dl>
<dd>

**definition:** `Optional<TypesDefinition>` 
    
</dd>
</dl>

<dl>
<dd>

**example:** `Optional<Object>` — Sample value surfaced in the UI.
    
</dd>
</dl>

<dl>
<dd>

**label:** `Optional<String>` — Human-readable label for the field.
    
</dd>
</dl>

<dl>
<dd>

**path:** `Optional<String>` — JSONPath used to extract the field from each source record; only meaningful for document-style backends. Pass an empty string to clear an existing path.
    
</dd>
</dl>

<dl>
<dd>

**type:** `Optional<String>` — One of: string, number, boolean, datetime, array, object, binary. Changing the type without supplying a matching definition clears any prior detailed type metadata.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.setPrimaryKeys(connectionId, schemaId, request)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Overrides the primary key detected on a schema.

This is a full replacement: the keys you supply become the complete override
set, replacing any previously configured overrides. Omitting a key that was
previously set removes it.

Primary key overrides are useful when the source does not expose a primary
key or when the source-detected key is not the correct deduplication
identifier for your use case.

> 📘 To revert to the source-detected primary keys and remove all overrides,
> use [`DELETE /api/connections/{connection_id}/schemas/{schema_id}/primary_keys`](../../../../../../api-reference/schemas/reset-primary-keys).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().setPrimaryKeys(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "public.users",
    SetPrimaryKeysRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema whose primary keys are being overridden.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<SchemaPrimaryKeyOverrideInput>>` — Ordered list of source fields that together form the primary key. Replaces any existing override; supply an empty list to clear.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.resetPrimaryKeys(connectionId, schemaId)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes all primary key overrides for a schema, reverting to the primary keys detected from the source.

To replace the overrides with a new set rather than clearing them entirely,
use [`PUT /api/connections/{connection_id}/schemas/{schema_id}/primary_keys`](../../../../../../api-reference/schemas/set-primary-keys)
instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().resetPrimaryKeys("248df4b7-aa70-47b8-a036-33ac447e668d", "public.users");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema whose primary key override should be cleared.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.refresh(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Refreshes a connection's cached schemas.

Call this when the upstream source has added, removed, or changed tables,
objects, or fields and you need Polytomic to re-inspect the connection before
creating or updating sync configuration.

This endpoint does not return the refreshed schemas directly. Follow the
`Location` header or poll [`GET /api/connections/{id}/schemas/status`](../../../../../api-reference/schemas/get-status)
until the refresh completes, then fetch the schemas you need.

> 📘 Schema refresh is asynchronous
>
> This endpoint kicks off a background refresh of the connection's cached
> schemas and returns a `Location` header pointing at
> [`GET /api/connections/{id}/schemas/status`](../../../../../api-reference/schemas/get-status).
> Poll that endpoint until `cache_status` transitions from `refreshing` to
> `fresh` (or until `last_refresh_finished` advances past
> `last_refresh_started`) to observe completion.
>
> Only connections whose current health status is healthy may be refreshed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().refresh("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose schema cache should be refreshed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.getStatus(id) -> BulkSyncSourceStatusEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the current schema inspection status for a connection.

Poll this endpoint after calling
[`POST /api/connections/{id}/schemas/refresh`](../../../../../api-reference/schemas/refresh) to track
progress. When `status` transitions to `completed`, the refreshed schemas
are available for use in sync configuration.

> 📘 Schema refresh is asynchronous
>
> This endpoint kicks off a background refresh of the connection's cached
> schemas and returns a `Location` header pointing at
> [`GET /api/connections/{id}/schemas/status`](../../../../../api-reference/schemas/get-status).
> Poll that endpoint until `cache_status` transitions from `refreshing` to
> `fresh` (or until `last_refresh_finished` advances past
> `last_refresh_started`) to observe completion.
>
> Only connections whose current health status is healthy may be refreshed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().getStatus("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose schema cache status should be returned.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.get(id, schemaId) -> BulkSyncSourceSchemaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single schema on a connection.

The schema is returned from the connection's cached schema set. If the
upstream source has changed since the last inspection, the result may be
stale.

> 📘 Trigger [`POST /api/connections/{id}/schemas/refresh`](../../../../../api-reference/schemas/refresh)
> and wait for it to complete before fetching this endpoint if you need
> up-to-date field definitions.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().get("248df4b7-aa70-47b8-a036-33ac447e668d", "public.users");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema within the connection. Format depends on the connection type (e.g. schema.table for databases, object name for SaaS backends).
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.schemas.getRecords(id, schemaId) -> SchemaRecordsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a sample of records from a schema on a connection.

The sample is intended for previewing the shape and values of data before
committing to a sync configuration, not for full data export.

> 🚧 The sample is not guaranteed to be representative of the full dataset.
> Row selection is implementation-defined and may differ across connection
> types.

> 📘 If the schema's field definitions are stale, refresh them first with
> [`POST /api/connections/{id}/schemas/refresh`](../../../../../../api-reference/schemas/refresh) to ensure
> the sample aligns with the current schema structure.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.schemas().getRecords("248df4b7-aa70-47b8-a036-33ac447e668d", "public.users");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Identifier of the schema within the connection.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Models
<details><summary><code>client.models.getEnrichmentSource(id) -> GetSyncSourceMetaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().getEnrichmentSource(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelsGetEnrichmentSourceRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**params:** `Optional<Map<String, Optional<List<String>>>>` — Query parameters used to incrementally refine a dependent source configuration. Keys correspond to configuration fields returned by previous calls to this endpoint.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.post(connectionId, request) -> GetEnrichmentInputFieldsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().post(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    EnrichmentInputFieldsRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**configuration:** `Optional<Map<String, Object>>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.preview(request) -> ModelResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().preview(
    ModelsPreviewRequest
        .builder()
        .body(
            CreateModelRequest
                .builder()
                .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
                .name("Users")
                .configuration(
                    new HashMap<String, Object>() {{
                        put("table", "public.users");
                    }}
                )
                .build()
        )
        .async(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `CreateModelRequest` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.list() -> ModelListResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.create(request) -> ModelResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().create(
    ModelsCreateRequest
        .builder()
        .body(
            CreateModelRequest
                .builder()
                .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
                .name("Users")
                .configuration(
                    new HashMap<String, Object>() {{
                        put("table", "public.users");
                    }}
                )
                .build()
        )
        .async(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `CreateModelRequest` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.get(id) -> ModelResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().get(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelsGetRequest
        .builder()
        .async(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.update(id, request) -> ModelResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateModelRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .name("Users")
        .async(false)
        .configuration(
            new HashMap<String, Object>() {{
                put("table", "public.users");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**additionalFields:** `Optional<List<ModelModelFieldRequest>>` 
    
</dd>
</dl>

<dl>
<dd>

**configuration:** `Map<String, Object>` 
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**enricher:** `Optional<Enrichment>` 
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<String>>` — 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.
    
</dd>
</dl>

<dl>
<dd>

**identifier:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**labels:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**refresh:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**relations:** `Optional<List<ModelRelation>>` 
    
</dd>
</dl>

<dl>
<dd>

**trackingColumns:** `Optional<List<String>>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().delete(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelsDeleteRequest
        .builder()
        .async(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.models.sample(id) -> ModelSampleResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

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.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.models().sample(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelsSampleRequest
        .builder()
        .async(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**async:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## ModelSync
<details><summary><code>client.modelSync.getSource(id) -> GetSyncSourceMetaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Describes the source configuration available on a connection for use as a model sync source.

Use this endpoint before creating a model to understand what configuration is
available. Once you have a configuration, resolve the fields available for
sync mapping with
[`GET /api/connections/{id}/modelsync/source/fields`](../../../../../api-reference/model-sync/get-source-fields).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().getSource(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelSyncGetSourceRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**params:** `Optional<Map<String, Optional<List<String>>>>` — Query parameters used to incrementally refine a dependent source configuration. Keys correspond to configuration fields returned by previous calls to this endpoint.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.getSourceFields(id) -> ModelFieldResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the source fields available on a connection for a given source configuration.

Pass the model's source configuration as query parameters to resolve the
fields that the connection will expose for that specific configuration. The
returned fields are what can be referenced in sync field mappings.

> 📘 Results depend on the source configuration you supply. A different
> table or query in the configuration may return a completely different field
> list.

The available source configuration parameters are described by
[`GET /api/connections/{id}/modelsync/source`](../../../../../../api-reference/model-sync/get-source).

## Query parameter format

Send each source setting as a bracketed key with a single string value. For
example, a source configured with `stream_id: "deals"` uses
`params[stream_id]=deals`.

With Polytomic MCP, pass the bracketed key directly in `query`:

```javascript
async () => {
  return polytomic.request({
    method: "GET",
    path: "/api/connections/<connection_id>/modelsync/source/fields",
    query: {"params[stream_id]": "deals"}
  });
}
```

> ⚠️ Send one value per setting
>
> Each setting uses only the first value if you repeat its query key. An empty
> array suffix, such as `params[stream_id][]=deals`, is rejected with
> `400 Bad Request`. Use `params[stream_id]=deals` instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().getSourceFields(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ModelSyncGetSourceFieldsRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**params:** `Optional<Map<String, Optional<String>>>` — Source configuration, matching the params used with GET /api/connections/{id}/modelsync/source, that selects the specific source to return fields for.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.list() -> ListSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists model syncs 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.

This endpoint returns syncs visible to the current caller's organization scope.
To inspect a specific sync in more detail, follow up with
[`GET /api/syncs/{id}`](../../api-reference/model-sync/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().list(
    ModelSyncListRequest
        .builder()
        .active(true)
        .mode(ModelsyncSyncTargetMode.CREATE)
        .targetConnectionId("0b155265-c537-44c9-9359-a3ceb468a4da")
        .pageToken("AmkYh8v0jR5B3kls2Qcc9y8MjrPmvR4CvaK7H0F4rEwqvg76K==")
        .limit(50)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**active:** `Optional<Boolean>` — Filter to only active or only paused syncs.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `Optional<ModelsyncSyncTargetMode>` — Filter by sync target mode (e.g. create, updateOrCreate, enrich).
    
</dd>
</dl>

<dl>
<dd>

**targetConnectionId:** `Optional<String>` — Filter to syncs that write to the specified target connection.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Pagination cursor returned in the previous response. Omit on the first request.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of syncs to return. Default and maximum is 50.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.create(request) -> ModelSyncV5ResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new model sync.

Create a new sync from one or more models to a destination.

All of the functionality described in [the product
documentation](https://docs.polytomic.com/docs/sync-destinations) is
configurable via the API.

Guides:

- [Model sync (Reverse ETL) from Snowflake query to Salesforce](../../guides/code-examples/model-sync-reverse-etl-from-snowflake-query-to-salesforce)
- [Joined model sync from Postgres, Airtable, and Stripe to Hubspot](../../guides/code-examples/joined-model-sync-from-postgres-airtable-and-stripe-to-hubspot)

## Targets (Destinations)

Polytomic refers to a model sync's destination as the "target object", or
target. Target objects are identified by a connection ID and an object ID. You
can retrieve a list of all target objects for a connection using the [Get Target
Objects](../../api-reference/model-sync/targets/list) endpoint.

The `target` object in the request specifies information about the sync destination.

```json
"target": {
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "object": "Users",
},
```

Some connections support additional configuration for targets. For example,
[Salesforce
connections](../../guides/configuring-your-connections/connections/salesforce#target)
support optionally specifying the ingestion API to use. The target specific
options are passed as `configuration`; consult the [integration
guides](../../guides/configuring-your-connections/overview)
for details about specific connection configurations.

### Creating a new target

Some integrations support creating a new target when creating a model sync. For
example, an ad audience or database table.

When creating a new target, `object` is omitted and `create` is specified
instead. The `create` property is an object containing integration specific
configuration for the new target.

```json
"target": {
    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
    "create": {
        "name": "New audience",
        "type": "user_audience"
    }
},
```

The [Get Target List](../../api-reference/model-sync/targets/list) endpoint returns information about whether
a connection supports target creation.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().create(
    CreateModelSyncV5Request
        .builder()
        .mode(ModelsyncSyncTargetMode.CREATE)
        .name("Users Sync")
        .schedule(
            Schedule
                .builder()
                .build()
        )
        .target(
            ModelSyncV5Target
                .builder()
                .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
                .build()
        )
        .fields(
            Arrays.asList(
                SyncField
                    .builder()
                    .target("name")
                    .build()
            )
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**active:** `Optional<Boolean>` — Whether the sync is enabled and scheduled.
    
</dd>
</dl>

<dl>
<dd>

**encryptionPassphrase:** `Optional<String>` — Passphrase for encrypting the sync data.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `List<SyncField>` — Fields to sync from source to destination.
    
</dd>
</dl>

<dl>
<dd>

**filterLogic:** `Optional<String>` — Deprecated. Use 'model_filters.logic'. Combines the model filters in 'filters' only.
    
</dd>
</dl>

<dl>
<dd>

**filters:** `Optional<List<Filter>>` — Deprecated. Use 'model_filters.conditions' and 'target_filters.conditions', which say which kind each condition is rather than inferring it. Ignored when either of those is present, except that a request carrying both shapes is rejected if they describe different filters.
    
</dd>
</dl>

<dl>
<dd>

**identities:** `Optional<ModelSyncIdentities>` — Identity mappings for the sync and the strategy combining them, replacing any the sync has. When this is omitted, 'identity' is used instead; updating a sync with more than one mapping requires this property.
    
</dd>
</dl>

<dl>
<dd>

**identity:** `Optional<Identity>` — Deprecated. Use 'identities'. Reports and accepts the first identity mapping only.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `ModelsyncSyncTargetMode` 
    
</dd>
</dl>

<dl>
<dd>

**modelFilters:** `Optional<ModelFilters>` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**onlyEnrichUpdates:** `Optional<Boolean>` — Whether to use enrichment models as a source of possible changes to sync. If true, only changes to the base models will cause a record to sync.
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` — Organization ID for the sync; read-only with a partner key.
    
</dd>
</dl>

<dl>
<dd>

**overrideFields:** `Optional<List<OverrideFieldInput>>` — Target fields which are set to a fixed value for every record, rather than mapped from a model field.
    
</dd>
</dl>

<dl>
<dd>

**overrides:** `Optional<List<Override>>` — Conditional value replacement for fields.
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**schedule:** `Schedule` 
    
</dd>
</dl>

<dl>
<dd>

**skipInitialBackfill:** `Optional<Boolean>` — Whether to skip the initial backfill of records; if true only records seen after the sync is enabled will be synced.
    
</dd>
</dl>

<dl>
<dd>

**syncAllRecords:** `Optional<Boolean>` — Whether to sync all records from the source, regardless of whether they've changed since the previous execution.
    
</dd>
</dl>

<dl>
<dd>

**target:** `ModelSyncV5Target` 
    
</dd>
</dl>

<dl>
<dd>

**targetFilters:** `Optional<TargetFilters>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.getScheduleOptions() -> ScheduleOptionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the schedule types available when creating or updating a model sync.

Use the `type` identifiers returned by this endpoint in the `schedule` field
when creating or updating a sync via
[`POST /api/syncs`](../../../api-reference/model-sync/create) or [`PUT /api/syncs/{id}`](../../../api-reference/model-sync/update).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().getScheduleOptions();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.get(id) -> ModelSyncV5ResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single model sync by ID.

To check whether a sync is currently running or has recently completed, use
[`GET /api/syncs/{id}/status`](../../../api-reference/model-sync/get-status). For the full history of
executions, use [`GET /api/syncs/{id}/executions`](../../../api-reference/model-sync/executions/list).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.update(id, request) -> ModelSyncV5ResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates a model sync's configuration.

Updating a model sync is a **full replacement** of the sync's configuration.
Every field in the request body is written to the sync; any field you omit is
cleared or reset to its default value.

To make a partial change — for example, toggling `active` or adjusting a
single field mapping — fetch the current sync with
[`GET /api/syncs/{id}`](../../../api-reference/model-sync/get),
modify the fields you want to change, and send the complete object back in
the update request.

Updates to `active`, `schedule`, and `policies` take effect immediately.
Changes to source fields, target configuration, filters, or field mappings
take effect on the sync's next execution.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateModelSyncV5Request
        .builder()
        .mode(ModelsyncSyncTargetMode.CREATE)
        .name("Users Sync")
        .schedule(
            Schedule
                .builder()
                .build()
        )
        .target(
            ModelSyncV5Target
                .builder()
                .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
                .build()
        )
        .fields(
            Arrays.asList(
                SyncField
                    .builder()
                    .target("name")
                    .build()
            )
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**active:** `Optional<Boolean>` — Whether the sync is enabled and scheduled.
    
</dd>
</dl>

<dl>
<dd>

**encryptionPassphrase:** `Optional<String>` — Passphrase for encrypting the sync data.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `List<SyncField>` — Fields to sync from source to destination.
    
</dd>
</dl>

<dl>
<dd>

**filterLogic:** `Optional<String>` — Deprecated. Use 'model_filters.logic'. Combines the model filters in 'filters' only.
    
</dd>
</dl>

<dl>
<dd>

**filters:** `Optional<List<Filter>>` — Deprecated. Use 'model_filters.conditions' and 'target_filters.conditions', which say which kind each condition is rather than inferring it. Ignored when either of those is present, except that a request carrying both shapes is rejected if they describe different filters.
    
</dd>
</dl>

<dl>
<dd>

**identities:** `Optional<ModelSyncIdentities>` — Identity mappings for the sync and the strategy combining them, replacing any the sync has. When this is omitted, 'identity' is used instead; updating a sync with more than one mapping requires this property.
    
</dd>
</dl>

<dl>
<dd>

**identity:** `Optional<Identity>` — Deprecated. Use 'identities'. Reports and accepts the first identity mapping only.
    
</dd>
</dl>

<dl>
<dd>

**mode:** `ModelsyncSyncTargetMode` 
    
</dd>
</dl>

<dl>
<dd>

**modelFilters:** `Optional<ModelFilters>` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**onlyEnrichUpdates:** `Optional<Boolean>` — Whether to use enrichment models as a source of possible changes to sync. If true, only changes to the base models will cause a record to sync.
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` — Organization ID for the sync; read-only with a partner key.
    
</dd>
</dl>

<dl>
<dd>

**overrideFields:** `Optional<List<OverrideFieldInput>>` — Target fields which are set to a fixed value for every record, rather than mapped from a model field.
    
</dd>
</dl>

<dl>
<dd>

**overrides:** `Optional<List<Override>>` — Conditional value replacement for fields.
    
</dd>
</dl>

<dl>
<dd>

**policies:** `Optional<List<String>>` 
    
</dd>
</dl>

<dl>
<dd>

**schedule:** `Schedule` 
    
</dd>
</dl>

<dl>
<dd>

**skipInitialBackfill:** `Optional<Boolean>` — Whether to skip the initial backfill of records; if true only records seen after the sync is enabled will be synced.
    
</dd>
</dl>

<dl>
<dd>

**syncAllRecords:** `Optional<Boolean>` — Whether to sync all records from the source, regardless of whether they've changed since the previous execution.
    
</dd>
</dl>

<dl>
<dd>

**target:** `ModelSyncV5Target` 
    
</dd>
</dl>

<dl>
<dd>

**targetFilters:** `Optional<TargetFilters>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a model sync, cancelling any running executions.

Deletion is permanent. Any running execution is cancelled before the sync
record is removed. Deleted syncs cannot be recovered; recreate them using
[`POST /api/syncs`](../../../api-reference/model-sync/create) if needed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.activate(id, request) -> ActivateSyncEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Sets whether a model sync is active.

Only active syncs execute on schedule or in response to a manual trigger. Set
`active` to `false` to pause a sync without deleting it.

> 📘 Deactivating a sync does not cancel an execution that is already in
> progress. Use [`POST /api/syncs/{id}/cancel`](../../../../api-reference/model-sync/cancel) to stop a
> running execution.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().activate(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActivateSyncInput
        .builder()
        .active(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**request:** `ActivateSyncInput` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.cancel(id) -> CancelSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Requests cancellation of any running executions on a model sync.

Cancellation is asynchronous. A successful response means the cancellation
signal has been queued; the running execution continues until the signal is
processed. Poll `GET /api/syncs/{id}/status` until the current execution
reaches a terminal state (`completed`, `canceled`, or `failed`) to confirm
cancellation has taken effect.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().cancel("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — The active execution of this sync ID will be cancelled.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.start(id, request) -> StartSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Starts a new execution of a model sync.

> 🚧 Force full resync
>
> Use caution when setting the `resync` parameter to `true`. This will force a full resync of the data from the source system. This can be a time-consuming operation and may impact the performance of the source system. It is recommended to only use this option when necessary.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().start(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    StartModelSyncRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**identities:** `Optional<List<String>>` — Values of the sync's identity source field naming the records to sync. A sync with more than one identity mapping requires 'source_identities' instead.
    
</dd>
</dl>

<dl>
<dd>

**resync:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**sourceIdentities:** `Optional<List<List<ModelSyncSourceIdentity>>>` — Records to sync, each identified by every source and value its entry lists. The sources of an entry are identity mapping sources of one model, and an entry for a sync whose identities strategy is 'and' lists all of them. Cannot be combined with 'identities'; at most 1000 entries.
    
</dd>
</dl>

<dl>
<dd>

**test:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.getStatus(id) -> SyncStatusEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the current status of a model sync.

The response includes a summary of the most recent execution, including its
start time, completion time, and record counts. For the complete execution
history, use [`GET /api/syncs/{id}/executions`](../../../../api-reference/model-sync/executions/list).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().getStatus("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Entities
<details><summary><code>client.entities.search() -> SearchEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Searches models, model fields, model syncs, bulk syncs, and connections in the caller's organization.

Supply a nonblank `search` term to search all five result categories. Unlike
[entity lookup](../../../api-reference/entities/get), this endpoint does not search
Organizations, users, executions, Harbors, or Harbor contexts. Model fields are
searchable but have no standalone lookup endpoint.

## Searchable resources

- Models: ID, name, and source Connection type.
- Model fields: ID, technical name, and label.
- Model Syncs: ID, name, source and target Connection types, and saved field and
  identity mappings. Mappings include source field names and labels, target
  field IDs, and available target field names.
- Bulk Syncs: ID, name, source and target Connection names and types, and enabled
  schema IDs, display names, and configured output names. Disabled schemas are
  excluded; enabled schemas remain searchable when the sync is inactive.
- Connections: ID and name.

Search uses cached metadata and does not refresh schemas. Names absent from
that metadata are not searchable. Bulk Sync fields, execution state,
expressions, filters, and constant values are not searched.

## Matching and evidence

Matching is case-insensitive and uses word prefixes, not fuzzy matching. Every
query word must match somewhere within a result. Spaces and punctuation split
words: `other emails` matches `other_emails`, but `mail` does not match `email`.
Some Model Sync source-type matches require a leading `~`.

Each resource appears once. Its `matches` explain which attributes matched and
which query terms contributed. Mapping and schema attributes carry their
respective `mapping` or `schema` context; resource metadata has neither. A name
or Connection type match alone does not establish mapping or schema use.
Results include canonical `links`, not complete configurations or schema lists.

## Limits and completeness

Results are ordered by category, then name or field label, then ID, not by
relevance. `limit` defaults to 50 and accepts 1–100. It limits resource hits,
not match evidence. When `metadata.truncated` is `true`, narrow your search or
increase the limit. There is no cursor pagination.

> ⚠️ Incomplete model-field coverage
>
> Above 40,000 published model fields, `metadata.model_fields_complete` is
> `false`: standalone field results cover a subset, not every published field.
> Model Sync mapping search is unaffected. Incomplete or truncated results
> cannot establish that no other matches exist.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.entities().search(
    EntitiesSearchRequest
        .builder()
        .search("email")
        .limit(50)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**search:** `String` — Search term matched, by word prefix, against models, model fields, model syncs, bulk syncs, and connections in the caller's organization.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of results to return across all result types. Defaults to 50 and cannot exceed 100.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.entities.get(id) -> EntityResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a resolved entity by ID.

Looks up a UUID within the caller's current organization and returns the
resource type plus enough context to fetch the canonical resource.

This endpoint is useful when you have an execution, sync, model, Connection,
Harbor, Harbor context, Organization, or user UUID and need to determine what
it refers to.

The response always includes:

- `id`: the UUID that was resolved.
- `type`: the resolved entity type.
- `canonical_path`: the canonical REST path for the resolved resource.

The response may also include:

- `relationships`: parent resources needed to address nested resources.
- `context`: lightweight additional context, such as bulk sync `schema_ids`.

For the normal user-scoped endpoint, `organization_id` is omitted from the
response.

Supported `type` values currently include:

- `organization`
- `user`
- `connection`
- `model`
- `model_sync`
- `model_sync_execution`
- `bulk_sync`
- `bulk_sync_execution`
- `harbor`
- `harbor_context`

Examples:

- A model sync execution resolves to a `model_sync_execution` and includes a
  `sync` relationship.
- A bulk sync execution resolves to a `bulk_sync_execution`, includes a
  `bulk_sync` relationship, and may include `context.schema_ids`.
- A Harbor context resolves to a `harbor_context` and includes a `harbor`
  relationship.

If the UUID does not exist, or exists outside the caller's scoped
organization, the endpoint returns `404`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.entities().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — UUID of the entity to resolve.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.entities.getForPartner(id) -> EntityResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a resolved entity by ID within a partner organization scope.

Looks up a UUID across organizations using partner authentication and returns
the resource type plus enough context to fetch the canonical resource.

This endpoint is intended for cross-organization partner workflows where the
caller has an arbitrary UUID and needs to discover both the resource type and
the organization it belongs to.

The response always includes:

- `id`: the UUID that was resolved.
- `type`: the resolved entity type.
- `canonical_path`: the canonical REST path for the resolved resource.
- `organization_id`: the organization that owns the resolved resource.

The response may also include:

- `relationships`: parent resources needed to address nested resources.
- `context`: lightweight additional context, such as bulk sync `schema_ids`.

Supported `type` values currently include:

- `organization`
- `user`
- `connection`
- `model`
- `model_sync`
- `model_sync_execution`
- `bulk_sync`
- `bulk_sync_execution`
- `harbor`
- `harbor_context`

Examples:

- A model sync execution resolves to a `model_sync_execution` and includes a
  `sync` relationship.
- A bulk sync execution resolves to a `bulk_sync_execution`, includes a
  `bulk_sync` relationship, and may include `context.schema_ids`.
- A Harbor context resolves to a `harbor_context` and includes a `harbor`
  relationship.

If the UUID does not exist, the endpoint returns `404`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.entities().getForPartner("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — UUID of the entity to resolve.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Events
<details><summary><code>client.events.list() -> EventsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists audit events for the caller's organization.

Results are paginated. If more events are available, the response includes
`pagination.next_page_token`; pass that token back unchanged to continue from
the last item you received.

Filter by event type using the `event_type` query parameter. Pass one of the
identifiers returned by [`GET /api/events_types`](../../api-reference/events/get-types) to
narrow results to a specific category of activity.

> 📘 Events reflect audit activity scoped to the caller's organization.
> The log captures both user-initiated and API-initiated actions.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.events().list(
    EventsListRequest
        .builder()
        .organizationId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .type("type")
        .startingAfter(OffsetDateTime.parse("2020-01-01T00:00:00Z"))
        .endingBefore(OffsetDateTime.parse("2020-01-01T00:00:00Z"))
        .limit(1)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**organizationId:** `Optional<String>` — Organization to list events for. Only used by system callers; normal and partner callers are always scoped to their own organization.
    
</dd>
</dl>

<dl>
<dd>

**type:** `Optional<String>` — Filter to a single event type. Use GET /api/events_types to list valid values.
    
</dd>
</dl>

<dl>
<dd>

**startingAfter:** `Optional<OffsetDateTime>` — Return events created strictly after this timestamp.
    
</dd>
</dl>

<dl>
<dd>

**endingBefore:** `Optional<OffsetDateTime>` — Return events created strictly before this timestamp.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of events to return. Default 10, maximum 100.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.events.getTypes() -> EventTypesEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the set of event type identifiers supported by GET /api/events.

Use the identifiers returned here as the `event_type` filter value when calling
[`GET /api/events`](../../api-reference/events/list).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.events().getTypes();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Harbors
<details><summary><code>client.harbors.listAuthorizedConnections() -> HarborConnectionListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists profile-authorized connections and capabilities for the current Harbor credential.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listAuthorizedConnections(
    HarborsListAuthorizedConnectionsRequest
        .builder()
        .limit(1)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**limit:** `Optional<Integer>` 
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listAuthorizedSchemas(connectionId) -> HarborSchemaListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists one bounded page of schema resources authorized by the current Harbor profile.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listAuthorizedSchemas(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListAuthorizedSchemasRequest
        .builder()
        .limit(1)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` 
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getAuthorizedSchema(connectionId, schemaId) -> HarborConnectionSchemaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one schema resource authorized by the current Harbor profile.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getAuthorizedSchema(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "schema_id",
    HarborsGetAuthorizedSchemaRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.registerSession(request) -> RegisterHarborSessionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Registers a service-attested MCP transport session for a scoped Harbor credential.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().registerSession(
    RegisterHarborSessionRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**polytomicMcpKeyId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpTimestamp:** `Optional<Long>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpNonce:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpSignature:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**clientName:** `Optional<String>` — MCP-observed client name.
    
</dd>
</dl>

<dl>
<dd>

**clientVersion:** `Optional<String>` — MCP-observed client version.
    
</dd>
</dl>

<dl>
<dd>

**externalRunId:** `Optional<String>` — Optional client-supplied run correlation value.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.closeSession(sessionId) -> CloseHarborSessionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Closes a service-attested Harbor MCP transport session.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().closeSession(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsCloseSessionRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**sessionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpKeyId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpTimestamp:** `Optional<Long>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpNonce:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicMcpSignature:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.list() -> HarborListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists Harbors in the caller's current organization.

Returns Harbors in creation order. Use `pagination.next_page_token` to continue when more results are available.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().list(
    HarborsListRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of Harbors to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.create(request) -> CreateHarborEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a managed or customer-managed Harbor in the caller's current organization.

`generate_api_key` defaults to `true`. Polytomic returns a new plaintext credential only in this response. Set it to `false` to create the Harbor without a credential.

For `customer_managed`, `backing_connection_id` must identify a queryable Connection that your credential can access.

Managed Harbors return with `status: provisioning` while Polytomic sets up their
storage in the background. Poll `GET /api/harbors/{harbor_id}` until the status is
`ready` before adding sources or querying data. If provisioning fails, the status
is `provisioning_failed` and Polytomic retries automatically.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().create(
    CreateHarborRequest
        .builder()
        .backingMode("managed")
        .name("Revenue Operations")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**backingConnectionId:** `Optional<String>` — Existing queryable Connection used by a customer-managed Harbor. Required only when backing_mode is customer_managed.
    
</dd>
</dl>

<dl>
<dd>

**backingMode:** `String` — How the Harbor's queryable data store is provided. Valid values are managed and customer_managed.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short description of the Harbor. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**generateApiKey:** `Optional<Boolean>` — Whether to generate a profile credential. Defaults to true.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable Harbor name.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.get(harborId) -> HarborEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one Harbor by its first-class Harbor ID.

The response exposes the backing Connection ID but not the internal profile used to authorize Harbor credentials.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.update(harborId, request) -> HarborEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates a Harbor's name and description.

Renaming a managed Harbor also renames its backing Connection. Both names
change together; a name conflict returns `409 Conflict` and leaves both
unchanged. Renaming a customer-managed Harbor preserves its Connection's name.

This operation does not change `backing_mode` or `backing_connection_id`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateHarborRequest
        .builder()
        .name("Revenue Operations")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short description of the Harbor. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable Harbor name.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.delete(harborId) -> DeletedHarborEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a Harbor and revokes its credentials.

> 🚧 Harbor deletion
>
> Deleting a Harbor revokes its credentials, context documents, and user assignments. A customer-managed backing Connection remains available. Polytomic deletes a managed backing Connection only when no other resource uses it.

The response confirms that access has been revoked. Polytomic removes managed
storage in the background and retries failed cleanup automatically. You can also
delete a Harbor while it is provisioning.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getActionConfiguration(harborId) -> HarborActionConfigurationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns configured action grants and revisions for a Harbor.

You must be an Organization administrator with permission to edit the Harbor.
Use a writable API credential, not a Harbor profile credential. Read-only keys
are denied because this endpoint requires Harbor edit permission.

This response includes grants for Connections that no longer populate the
Harbor. You can remove those stale grants without reattaching the Connection.
Reading configuration does not require the Harbor Actions entitlement.

Use each Connection's `revision` as `expected_revision` when replacing or
removing its grants. Configuration responses contain metadata only, not provider
credentials or record values.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getActionConfiguration("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.disableActionConfiguration(harborId) -> HarborActionConfigurationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Disables all configured actions for a Harbor.

You must be an Organization administrator with permission to edit the Harbor.
Use a normal writable API credential, not a Harbor profile credential. Your
Organization must have the Harbor Actions entitlement.

> 🚧 Disable all actions
>
> This removes every configured action grant from the Harbor, including grants
> for detached Connections. There is no per-Connection revision check.

The response contains the empty configuration. This request does not delete
Connections, syncs, or provider records.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().disableActionConfiguration("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listActionSourceConnections(harborId) -> HarborActionSourceConnectionsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists action-capable source Connections that populate a Harbor.

You must be an Organization administrator with permission to edit the Harbor.
Use a writable API credential, not a Harbor profile credential. Read-only keys
are denied because this endpoint requires Harbor edit permission. Discovery does
not require the Harbor Actions entitlement.

A Connection is eligible when it supports actions and is a source of a
non-deleted Bulk Sync or Model Sync targeting the Harbor's backing Connection.
Only saved, non-shared Connections in your Organization that you can query are
included. Disabled syncs still establish source membership.

Discover schemas and operations before choosing the grants to configure.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listActionSourceConnections("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.setActionConfiguration(harborId, connectionId, request) -> HarborActionConfigurationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates or replaces action grants for an eligible Harbor source Connection.

You must be an Organization administrator with permission to edit both the
Harbor and the source Connection. Use a normal writable API credential, not a
Harbor profile credential. Your Organization must have the Harbor Actions
entitlement.

The Connection must populate the Harbor through a non-deleted Bulk Sync or Model
Sync targeting its backing Connection. This requirement applies to new grants
and replacements, even when you only remove fields from an existing grant.

Submit the complete grant set for this Connection. Omit `expected_revision` to
create it, or supply the current revision to replace it. A missing, stale, or
unexpected revision returns `409 Conflict`; read configuration again before
retrying. Successful replacement creates a new revision.

For mutating operations, `field_ids` selects input fields and
`lookup_field_ids` must be omitted. For read-only operations, `field_ids`
selects output fields and `lookup_field_ids` selects allowed lookup fields.
Duplicate operations or field IDs are invalid. An empty grant set is invalid;
remove the Connection's grants instead.

This request changes permissions only. It does not execute provider actions.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().setActionConfiguration(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    SetHarborActionConfigurationRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Source Connection whose action grants you want to manage.
    
</dd>
</dl>

<dl>
<dd>

**expectedRevision:** `Optional<String>` — Current revision when replacing existing grants. Omit when creating grants for this Connection.
    
</dd>
</dl>

<dl>
<dd>

**grants:** `Optional<List<HarborActionGrantSchema>>` — Complete replacement of this Connection's action grants.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.removeActionConfiguration(harborId, connectionId) -> HarborActionConfigurationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Removes a Connection's action grants from a Harbor.

You must be an Organization administrator with permission to edit the Harbor.
Use a normal writable API credential, not a Harbor profile credential. Your
Organization must have the Harbor Actions entitlement.

Supply the current `expected_revision` as a query parameter. A stale revision
returns `409 Conflict`; read configuration again before retrying.

You can remove grants after the Connection stops populating the Harbor, or after
the Connection is deleted. The response contains the remaining configured action
Connections. This request does not delete the Connection or provider records.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().removeActionConfiguration(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsRemoveActionConfigurationRequest
        .builder()
        .expectedRevision("248df4b7-aa70-47b8-a036-33ac447e668d")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Source Connection whose action grants you want to manage.
    
</dd>
</dl>

<dl>
<dd>

**expectedRevision:** `String` — Current revision of the Connection's action grants.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listActionConfigurationSchemas(harborId, connectionId) -> HarborActionConfigurationSchemasEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists available action schemas for an eligible Harbor source Connection.

You must be an Organization administrator with permission to edit the Harbor
and query the source Connection. Use a writable API credential, not a Harbor
profile credential. Read-only keys are denied because this endpoint requires
Harbor edit permission. Discovery does not require the Harbor Actions entitlement.

The Connection must populate the Harbor through a non-deleted Bulk Sync or Model
Sync targeting its backing Connection. The response lists action schemas, not
records. Use the next page token with the same search filter to continue.

Operation IDs in the catalog are hints. Operation discovery returns the current
configurable fields for a schema.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listActionConfigurationSchemas(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListActionConfigurationSchemasRequest
        .builder()
        .search("search")
        .limit(1)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Source Connection whose action grants you want to manage.
    
</dd>
</dl>

<dl>
<dd>

**search:** `Optional<String>` — Filter action schemas by ID or name.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of schemas to return.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listActionConfigurationOperations(harborId, connectionId, schemaId) -> HarborActionConfigurationOperationsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists operations and configurable fields for an eligible Harbor action schema.

You must be an Organization administrator with permission to edit the Harbor
and query the source Connection. Use a writable API credential, not a Harbor
profile credential. Read-only keys are denied because this endpoint requires
Harbor edit permission. Discovery does not require the Harbor Actions entitlement.

The Connection must populate the Harbor through a non-deleted Bulk Sync or Model
Sync targeting its backing Connection. This request returns operation metadata,
not provider records, and does not execute an action.

For a mutating operation, choose input field IDs. For a read-only operation,
choose output field IDs and at least one lookup field ID. Required input fields
must be included in the grant.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listActionConfigurationOperations("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d", "schema_id");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Source Connection whose action grants you want to manage.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Exact action schema ID returned by schema discovery.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listContexts(harborId) -> HarborContextListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists context document metadata for a Harbor without returning document content.

Collection items include the current published `version` number and omit
`content`. Use the context item endpoint to retrieve a complete document.

A Harbor profile credential can read context only when `harbor_id` identifies
its own Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listContexts(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListContextsRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of context documents to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.createContext(harborId, request) -> HarborContextEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates and attaches a context document to a Harbor.

The new document belongs only to this Harbor. Context documents cannot be attached to multiple Harbors.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().createContext(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CreateHarborContextRequest
        .builder()
        .content("Bookings use the contract signed date...")
        .title("Revenue definitions")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**content:** `String` — Plain-text context content. Maximum 20,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short summary of the context document. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**title:** `String` — Human-readable context title. Maximum 200 characters.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listContextDrafts(harborId) -> HarborContextDraftListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists mutable Harbor context drafts without returning document content.

The collection includes drafts for published context documents and initial drafts
that have not yet been published. Use `context_id` with the draft detail,
replacement, promotion, and discard endpoints.

Draft metadata does not include `content`. Fetch a selected draft through its
detail endpoint to read the complete candidate. Normal context list and detail
operations continue to return published content only.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listContextDrafts(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListContextDraftsRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of mutable drafts to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.createContextDraft(harborId, request) -> HarborContextDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates an unpublished context document with its initial mutable draft.

Creates a stable context identity and its initial mutable draft without publishing
content to the Harbor. The response includes `context_id`, which identifies the
draft replacement, promotion, and discard routes.

The initial draft has a null `base_revision_id`. It remains absent from normal
context list/detail, GraphQL, entity lookup, and Harbor MCP reads until promoted.
Use the regular context creation endpoint instead when the initial payload should
be published immediately.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().createContextDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CreateHarborContextDraftRequest
        .builder()
        .content("Bookings use the contract signed date...")
        .title("Revenue definitions")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**changeNote:** `Optional<String>` — Optional note stored with the draft and copied to published version 1 on promotion.
    
</dd>
</dl>

<dl>
<dd>

**content:** `String` — Complete plain-text draft content. Maximum 20,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short summary of the draft. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**title:** `String` — Human-readable draft title. Maximum 200 characters.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getContext(harborId, contextId) -> HarborContextEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one complete Harbor context document.

The response includes the current published `version` number and complete
plain-text `content`.

A Harbor profile credential can read context only when `harbor_id` identifies
its own Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getContext(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsGetContextRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.updateContext(harborId, contextId, request) -> HarborContextEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Replaces one Harbor context document.

Each successful request publishes the next immutable version. You can omit
`change_note`.

A direct publication leaves an existing draft unchanged.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().updateContext(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    SaveHarborContextRequest
        .builder()
        .content("Bookings use the contract signed date...")
        .title("Revenue definitions")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**changeNote:** `Optional<String>` — Optional note describing this published change.
    
</dd>
</dl>

<dl>
<dd>

**content:** `String` — Plain-text context content. Maximum 20,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short summary of the context document. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**title:** `String` — Human-readable context title. Maximum 200 characters.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.deleteContext(harborId, contextId) -> DeletedHarborContextEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes one context document from a Harbor.

Deleting a context document does not affect the Harbor or its other context documents.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().deleteContext(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsDeleteContextRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getContextDraft(harborId, contextId) -> HarborContextDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the mutable draft for a Harbor context document.

Drafts are available only through the draft endpoints. `base_revision_id`
identifies the published revision from which the candidate was created. Normal
context reads and Harbor MCP tools continue to return the current published
version. Creator and updater IDs are null when their actor type is `system`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getContextDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsGetContextDraftRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.saveContextDraft(harborId, contextId, request) -> HarborContextDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates or completely replaces the mutable draft for a Harbor context document.

The request supplies the complete draft payload. If a draft already exists,
this request replaces it while preserving the draft ID, creation metadata, and
`base_revision_id`.

A new draft for a published document records the current revision as its base.
An unpublished document's initial draft keeps a null base when replaced. Saving
a draft does not change published content or its `updated_at`. Creator and
updater provenance comes from the request actor; system actors have a null actor
ID.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().saveContextDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    SaveHarborContextDraftRequest
        .builder()
        .content("Bookings use the contract signed date...")
        .title("Revenue definitions")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**changeNote:** `Optional<String>` — Optional note stored with the draft and copied to the published version on promotion.
    
</dd>
</dl>

<dl>
<dd>

**content:** `String` — Complete plain-text draft content. Maximum 20,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Short summary of the draft. Maximum 1,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**title:** `String` — Human-readable draft title. Maximum 200 characters.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.deleteContextDraft(harborId, contextId) -> DeletedHarborContextDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Discards the mutable draft for a Harbor context document.

Discarding a draft does not change the current published version or its
history. If the draft belongs to a context that has never been published,
discarding it also removes the otherwise empty context identity.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().deleteContextDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsDeleteContextDraftRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.promoteContextDraft(harborId, contextId) -> HarborContextVersionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Promotes the draft to the next immutable published context version.

Promotion publishes the draft's exact title, description, content, and optional
change note as the next version. An unpublished context's initial draft becomes
version 1. The draft is removed after publication.

Promotion returns a conflict when the current published revision differs from
the draft's `base_revision_id`. The stale draft remains available so an author
can compare it with the current version before discarding and recreating it.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().promoteContextDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsPromoteContextDraftRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listContextVersions(harborId, contextId) -> HarborContextVersionListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists immutable published versions of a Harbor context document without returning content.

Versions are ordered from newest to oldest. Collection items omit `content`,
and the draft is never included. Pagination tokens continue from the last
returned version, so publishing a newer version between requests does not shift
or duplicate older results.

Published revision IDs are durable artifact identities intended for future
Harbor activity and audit records. Publisher IDs are paired with actor types.
System publications have `published_by_type: "system"` and a null
`published_by` because the system actor has no UUID.

A Harbor profile credential can read versions only when `harbor_id` identifies
its own Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listContextVersions(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListContextVersionsRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of published versions to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getContextVersion(harborId, contextId, versionId) -> HarborContextVersionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one immutable published version of a Harbor context document.

The response includes the complete title, description, and plain-text
`content` captured when the version was published.

Published versions cannot be changed or deleted. System publications have
`published_by_type: "system"` and a null `published_by`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getContextVersion(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsGetContextVersionRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**contextId:** `String` — Unique identifier of the context document.
    
</dd>
</dl>

<dl>
<dd>

**versionId:** `String` — Unique identifier of the published context version.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listKeys(harborId) -> HarborKeyListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists active masked credentials for a Harbor.

Each item contains a masked `key_hint`. Polytomic never returns a credential plaintext after creation.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listKeys(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListKeysRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of active credentials to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.createKey(harborId) -> HarborKeyEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Generates a new Harbor credential and returns its plaintext value once.

Store the returned `value` securely. Polytomic returns it only in this response.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().createKey("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.deleteKey(harborId, keyId) -> RevokedHarborKeyEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Revokes one Harbor credential by its credential ID.

Revocation affects only the selected credential. Other active Harbor credentials remain valid.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().deleteKey("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**keyId:** `String` — Unique identifier of the Harbor credential.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.runQuery(harborId, request) -> RunQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Submits a query against the Harbor backing connection for asynchronous execution.

Use a scoped credential bound to this Harbor. The query runs only against the
Harbor's backing connection; you cannot select another connection on this route.
Send a unique `X-Polytomic-Activity-Request-ID` UUID with each submission. The
`X-Polytomic-Harbor-Session` header is optional; if you send one, it must be
valid for this Harbor.

The response contains a query ID and an initial `created` status. Poll
[`GET /api/queries/{id}`](../../../../api-reference/query-runner/get-query) with that ID
until the status is `done`, `failed`, or `unknown`. Follow the result endpoint's
pagination links for additional rows. Results are temporary; check `expires`
on the completed query.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().runQuery(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    RunHarborQueryRequest
        .builder()
        .query("SELECT 1 AS n")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor whose backing connection runs the query.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**query:** `String` — SQL query to execute against the Harbor backing connection.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listSavedQueries(harborId) -> HarborSavedQueryListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists current published saved queries for a Harbor.

Saved queries are supported only for Polytomic-managed Harbors whose backing
Connection type is `polytomic_harbor`.

Collection items contain current published metadata and omit SQL, parameter
values, and unpublished drafts. A Harbor profile credential can list saved
queries only when `harbor_id` identifies its own Harbor.

## Harbor Activity

When you use a Harbor profile credential, send a new nonzero UUID in
`X-Polytomic-Activity-Request-ID` for each request, including each page. A
missing or invalid ID returns `400 Bad Request`. Reusing a consumed ID returns
`409 Conflict`.

If you supply `X-Polytomic-Harbor-Session`, the session must be active and bound
to your credential and Harbor. An invalid session returns `403 Forbidden`.
Direct scoped REST requests may omit the session header.

Polytomic records `saved_query.listed` before returning data. The event describes
only the returned page, including saved-query IDs, immutable revision IDs,
version numbers, and bounded name snapshots. Activity excludes SQL, parameter
values, and expected column names. If Polytomic cannot record the event, the
request returns `503 Service Unavailable` without saved-query data.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listSavedQueries(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListSavedQueriesRequest
        .builder()
        .limit(1)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of saved queries to return.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.createSavedQueryDraft(harborId, request) -> HarborSavedQueryDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a stable Harbor saved query with its initial mutable draft.

Saved queries are supported only for Polytomic-managed Harbors whose backing
Connection type is `polytomic_harbor`. Customer-managed Harbor backings return
an unsupported-backing error.

The saved query receives a stable ID, but it remains absent from published
saved-query reads until an administrator publishes its initial draft.

Use `{{parameter_name}}` references in `sql_template`. Each reference must have
one scalar declaration. Validation values and defaults must match the declared
`string`, `number`, `boolean`, `date`, `timestamp`, or `uuid` type.

Unknown JSON fields, including fields inside parameter declarations, return
`400 Bad Request` before the draft is saved. Use `default_value`, not `default`,
for parameter defaults.

When you omit a parameter during execution, Polytomic uses its published
`default_value`, never its draft validation value. An omitted optional parameter
without a default binds SQL `NULL`. A required parameter allows omission when a
default exists, but rejects explicit `null` even with a default.

For a report window, use a required parameter with a default so omission selects
a useful window and explicit `null` is rejected:

```json
{"name": "days", "type": "number", "required": true, "default_value": 7}
```
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().createSavedQueryDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CreateHarborSavedQueryDraftRequest
        .builder()
        .name("Monthly revenue")
        .sqlTemplate("SELECT account_id, sum(amount) AS revenue FROM orders WHERE created_at >= {{start_date}} GROUP BY account_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**changeNote:** `Optional<String>` — Optional note copied to the immutable published version.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Business definition and usage notes. Maximum 2,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable saved-query name. Maximum 200 characters.
    
</dd>
</dl>

<dl>
<dd>

**owner:** `Optional<String>` — Human-readable owner label. Maximum 200 characters.
    
</dd>
</dl>

<dl>
<dd>

**parameters:** `Optional<List<HarborSavedQueryParameter>>` — Typed scalar parameter declarations.
    
</dd>
</dl>

<dl>
<dd>

**sqlTemplate:** `String` — DuckDB SQL template using {{name}} references for bound parameters.
    
</dd>
</dl>

<dl>
<dd>

**validationValues:** `Optional<Map<String, Object>>` — Author-supplied JSON scalar values used only to validate this draft.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listSavedQueryDrafts(harborId) -> HarborSavedQueryDraftListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists mutable Harbor saved-query drafts.

Drafts are ordered from newest to oldest and include complete SQL, typed
parameter declarations, and author-supplied validation values. Harbor profile
credentials cannot access this endpoint.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listSavedQueryDrafts(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListSavedQueryDraftsRequest
        .builder()
        .limit(1)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of saved-query drafts to return.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getSavedQuery(harborId, savedQueryId) -> HarborSavedQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the current published version of one Harbor saved query.

The response contains the current immutable `revision_id`, SQL template,
parameter contract, expected columns, and publication provenance. Validation
inputs are draft-only and are never part of a published response.

A Harbor profile credential can retrieve a saved query only from its own Harbor.

## Harbor Activity

When you use a Harbor profile credential, send a new nonzero UUID in
`X-Polytomic-Activity-Request-ID` for each request. A missing or invalid ID
returns `400 Bad Request`. Reusing a consumed ID returns `409 Conflict`.

If you supply `X-Polytomic-Harbor-Session`, the session must be active and bound
to your credential and Harbor. An invalid session returns `403 Forbidden`.
Direct scoped REST requests may omit the session header.

Polytomic records `saved_query.fetched` before returning the definition. The
event identifies the saved query, exact immutable revision, published version,
and bounded name snapshot. It does not indicate query execution. Activity
excludes SQL, parameter defaults and validation values, expected column names,
and result rows. If Polytomic cannot record the event, the request returns
`503 Service Unavailable` without saved-query data.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getSavedQuery(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsGetSavedQueryRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.deleteSavedQuery(harborId, savedQueryId) -> DeletedHarborSavedQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Archives one Harbor saved query and removes it from active reads.

Archiving removes the saved query and any draft from active reads while
retaining its immutable revisions for provenance. The operation does not run
the saved SQL or modify the Harbor backing Connection. Archiving does not cancel
in-flight execution requests or queued executions.

This REST operation archives the saved query; it does not merely unpublish it.
Unpublish is available only through the GraphQL `unpublishHarborSavedQuery`
mutation. There is no REST unpublish endpoint.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().deleteSavedQuery("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.saveSavedQueryDraft(harborId, savedQueryId, request) -> HarborSavedQueryDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates or completely replaces the mutable draft for a Harbor saved query.

Replacement is complete rather than partial. The next validation or publication
uses the replacement SQL, parameter declarations, and validation values.

Unknown JSON fields, including fields inside parameter declarations, return
`400 Bad Request` before the draft is saved. Use `default_value`, not `default`,
for parameter defaults.

When you omit a parameter during execution, Polytomic uses its published
`default_value`, never its draft validation value. An omitted optional parameter
without a default binds SQL `NULL`. A required parameter allows omission when a
default exists, but rejects explicit `null` even with a default.

For a report window, use a required parameter with a default so omission selects
a useful window and explicit `null` is rejected:

```json
{"name": "days", "type": "number", "required": true, "default_value": 7}
```
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().saveSavedQueryDraft(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    SaveHarborSavedQueryDraftRequest
        .builder()
        .name("Monthly revenue")
        .sqlTemplate("SELECT account_id, sum(amount) AS revenue FROM orders WHERE created_at >= {{start_date}} GROUP BY account_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>

<dl>
<dd>

**changeNote:** `Optional<String>` — Optional note copied to the immutable published version.
    
</dd>
</dl>

<dl>
<dd>

**description:** `Optional<String>` — Business definition and usage notes. Maximum 2,000 characters.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable saved-query name. Maximum 200 characters.
    
</dd>
</dl>

<dl>
<dd>

**owner:** `Optional<String>` — Human-readable owner label. Maximum 200 characters.
    
</dd>
</dl>

<dl>
<dd>

**parameters:** `Optional<List<HarborSavedQueryParameter>>` — Typed scalar parameter declarations.
    
</dd>
</dl>

<dl>
<dd>

**sqlTemplate:** `String` — DuckDB SQL template using {{name}} references for bound parameters.
    
</dd>
</dl>

<dl>
<dd>

**validationValues:** `Optional<Map<String, Object>>` — Author-supplied JSON scalar values used only to validate this draft.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.deleteSavedQueryDraft(harborId, savedQueryId) -> DeletedHarborSavedQueryDraftEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Discards the mutable draft for one Harbor saved query.

Discarding an initial unpublished draft also removes its otherwise empty stable
saved-query identity. Discarding a later draft preserves every immutable
published version.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().deleteSavedQueryDraft("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.publishSavedQueryDraft(harborId, savedQueryId) -> HarborSavedQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Validates and publishes the current draft as the next immutable saved-query version.

Only organization administrators can publish. Publication executes and validates
the current draft with the Polytomic-managed Harbor's MotherDuck `read_scaling`
credential. It fails instead of using the Harbor writer credential when the
reader credential is missing or incomplete.

After execution, publication verifies that the draft did not change. A
concurrent edit returns a conflict and remains a draft. Successful publication
creates the next immutable revision, records the observed ordered columns as its
output contract, removes validation inputs from the published definition, and
deletes the mutable draft. The response includes the immutable `revision_id`
that future executions use for exact provenance.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().publishSavedQueryDraft("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.validateSavedQueryDraft(harborId, savedQueryId) -> HarborSavedQueryValidationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Validates the exact current saved-query draft and returns a bounded ephemeral preview.

Only organization administrators can validate drafts. Named template references
compile to DuckDB placeholders, and typed values are passed separately rather
than interpolated into SQL.

The query runs with the Polytomic-managed Harbor's MotherDuck `read_scaling`
credential. Validation fails when that credential is missing or incomplete and
never falls back to the Harbor writer credential. Preview rows and serialized
response size are bounded. The preview and validation attempt are not persisted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().validateSavedQueryDraft("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.executeSavedQuery(harborId, savedQueryId, request) -> ExecuteHarborSavedQueryEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Submits the current published Harbor saved query for asynchronous reader-only execution.

Use a Harbor-bound scoped credential with query access to the Harbor's backing
Connection. Administrator credentials cannot submit executions here. Saved
queries require a Polytomic-managed Harbor.

Polytomic selects the current published revision while processing your request.
The response identifies that exact immutable revision. Selection happens before
Polytomic accepts the execution. Drafts, unpublished queries, and archived
queries are unavailable for selection. You cannot select a historical revision
or supply SQL through this endpoint.

> ⚠️ Concurrent publication changes
>
> Publishing, unpublishing, or archiving a saved query after selection does not
> change the selected revision. An in-flight request may still be accepted and
> execute that revision. Unpublishing or archiving does not cancel in-flight
> requests or queued executions. Query access is checked again before execution
> and result retrieval.

Parameter values are bound separately from SQL. Omitted parameters use the
published `default_value`, never draft validation values. An omitted optional
parameter without a default binds SQL `NULL`. Required parameters allow omission
when a default exists, but reject explicit `null` even with a default. Missing
required values without defaults, explicit `null` for required parameters,
unknown parameter names, and invalid scalar types return
`422 Unprocessable Entity` without accepting an execution. Execution requires
reader credentials and never falls back to writer credentials.

For report windows, define parameters with `required: true` and a
`default_value`, such as `7` for a `days` parameter. This allows omission while
preventing explicit `null` from turning a time filter into a SQL `NULL`
comparison.

To archive a saved query through REST, use
[`DELETE /api/harbors/{harbor_id}/saved-queries/{saved_query_id}`](../../../../../../api-reference/harbors/delete-saved-query).
Unpublish is available only through the GraphQL `unpublishHarborSavedQuery`
mutation, not a REST endpoint.

## Results

The response returns a task ID with status `created`, not result rows. Poll
[`GET /api/queries/{id}`](../../../../../../api-reference/query-runner/get-query) using a credential
from the same Harbor profile. Query access is checked again before execution and
result retrieval. Stop polling at `done`, `failed`, or `unknown`; `unknown` means
execution started but no durable terminal result is available.

Results and detailed failure information expire after 24 hours. Use the
`expires` field and follow `links.next` to retrieve additional result pages.

## Harbor Activity

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID`. Missing or invalid
IDs return `400 Bad Request`. Reusing a consumed ID returns `409 Conflict` and
does not create another execution.

You may omit `X-Polytomic-Harbor-Session` for direct REST requests. If supplied,
the session must be active and bound to your credential and Harbor.

Polytomic records `query.submitted` atomically with acceptance. The event
identifies the saved query, immutable revision, published version, and bounded
name snapshot. SQL, parameter values and defaults, column names, and result rows
remain outside Activity metadata. If Activity persistence is unavailable, the
request returns `503 Service Unavailable` without accepting an execution.

`query.started` records provider invocation. `query.succeeded` means results are
available for authorized retrieval, not that you have consumed them.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().executeSavedQuery(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecuteHarborSavedQueryRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**savedQueryId:** `String` — Unique stable identifier of the saved query.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**parameters:** `Optional<Map<String, Object>>` — Named JSON scalar overrides for declared parameters. Omission uses published default_value, or SQL NULL for optional parameters without a default. Required parameters reject explicit null even with a default; without a default they also reject omission. Unknown names and invalid types are rejected.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.resolveSourceMappings(harborId, request) -> ResolveHarborSourceMappingsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Resolves documented source table and field identities to the names a Harbor's backing Connection accepts.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().resolveSourceMappings(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ResolveHarborSourceMappingsRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**sources:** `Optional<List<HarborSourceReference>>` — Source tables to resolve. Answered in request order; maximum 200 entries, each naming at most 500 fields.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.getStatus(harborId) -> HarborStatusEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns raw Polytomic refresh evidence for datasets written to a Harbor.

Each pipeline corresponds to a bulk sync or model sync that writes at least one
dataset to the Harbor's backing Connection. Tables populated outside Polytomic
are not included, even when they are queryable through a customer-managed
backing Connection.

The response groups shared pipeline evidence so schedules and configuration are
not repeated for every dataset:

- Each entry in `pipelines` identifies the producer through `type` and `id`.
  Separate pipelines targeting the same physical dataset remain separate
  entries.
- `datasets` is keyed by the effective destination dataset name.
  `last_success_at` is the start time of the most recent execution in which that
  dataset completed successfully, including a successful dataset within a bulk
  execution that completes with errors. The start time is a conservative upper
  bound because source reads and destination writes happen afterward.
- `latest_status` preserves the latest Polytomic execution status. Never-run
  datasets omit this field.
- Pipeline-level `schedules` preserves schedule parameters and selectors. A
  schedule can be manual, event-driven, advanced, selective, or limited to
  named source schemas, so callers should not reduce the list to one inferred
  cadence.
- Continuous schedules use the scheduler's persisted next firing. If scheduler
  state is unavailable, `next_run_at` is omitted rather than recalculated with
  new jitter.
- Paused pipelines remain present with `refresh_enabled` set to `false` and no
  `next_run_at`.

Use absolute timestamps and the raw statuses to apply the maximum acceptable
staleness for your task. The endpoint does not classify datasets or the Harbor
as healthy, stale, or unhealthy.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().getStatus("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.listUsers(harborId) -> HarborUserListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists Harbor-only users assigned to a Harbor.

The response contains only Harbor-only users currently assigned to this Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().listUsers(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    HarborsListUsersRequest
        .builder()
        .limit(50)
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of assigned users to return. Defaults to 50 and cannot exceed 50.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.inviteUser(harborId, request) -> HarborUserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Invites and assigns a new Harbor-only user.

The invited account is restricted to assigned Harbors and does not receive regular Polytomic application access.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().inviteUser(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    InviteHarborUserRequest
        .builder()
        .email("analyst@example.com")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**email:** `String` — Email address used to invite the Harbor-only user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.assignUser(harborId, userId) -> HarborUserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Assigns an existing Harbor-only user to a Harbor.

The assignment is idempotent. Regular Polytomic users cannot be assigned because they already have application access to Harbors.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().assignUser("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**userId:** `String` — Unique identifier of the Harbor-only user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.unassignUser(harborId, userId) -> UnassignedHarborUserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Removes a Harbor assignment without deleting the user.

This removes only the Harbor assignment. The organization user remains available and may retain assignments to other Harbors.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().unassignUser("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**userId:** `String` — Unique identifier of the Harbor-only user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Jobs
<details><summary><code>client.jobs.get(type, id) -> JobResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the current state of an asynchronous job.

This endpoint is used as a polling target by other asynchronous workflows such
as model preview and log export. The caller must know the job `type` and `id`
that were returned when the job was created.

If the job is still running, the response returns `status: running` and may not
include a `result` yet. Once complete, `status` becomes `done` or `failed`.

Only specific job types are supported by this endpoint. Passing an unknown
`type` returns `400`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.jobs().get("createmodel", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**type:** `String` — Job type. One of: createmodel, updatemodel, previewmodel, samplemodel, exportlogs, connectionproxy.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the job (usually returned by whichever endpoint started the job).
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Identity
<details><summary><code>client.identity.get() -> GetIdentityResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns information about the authenticated caller and, if applicable, the organization they are scoped to.

Use this endpoint to confirm which kind of credential is being used before
calling endpoints with stricter authorization rules.

For user-scoped credentials, the response includes the resolved user and
organization details. For non-user keys, the response identifies the key class
with the corresponding boolean flags instead of impersonating a user.

This endpoint is especially useful when debugging why a request is being
accepted or rejected by endpoints that are limited to particular caller types.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.identity().get();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Notifications
<details><summary><code>client.notifications.getGlobalErrorSubscribers() -> GlobalErrorSubscribersResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the list of email addresses subscribed to global sync error notifications for the caller's organization.

To update the subscriber list, use
[`PUT /api/notifications/global-error-subscribers`](../../../api-reference/notifications/set-global-error-subscribers).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.notifications().getGlobalErrorSubscribers();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.notifications.setGlobalErrorSubscribers(request) -> GlobalErrorSubscribersResponse</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Replaces the list of email addresses subscribed to global sync error notifications for the caller's organization.

This is a **full replacement** — the request body becomes the complete
subscriber list. To add or remove a single address without affecting others,
fetch the current list with
[`GET /api/notifications/global-error-subscribers`](../../../api-reference/notifications/get-global-error-subscribers), apply your change,
and send the modified list back.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.notifications().setGlobalErrorSubscribers(
    GlobalErrorSubscribersRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**emails:** `Optional<List<String>>` — Email addresses to subscribe to global sync error notifications. Replaces the current subscriber list; pass an empty list to unsubscribe everyone.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Operations
<details><summary><code>client.operations.search(request) -> SearchOperationsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Finds documented REST operations for up to three plain-language tasks in one request.

This endpoint returns HTTP 503 when operation search is not configured for the
API deployment. Check [search availability](../../../api-reference/operations/get-search-availability)
before offering operation search in a client.

Each question counts against three fixed UTC-window budgets: 12 questions per
Organization per minute, 300 per Organization per day, and 60 per minute
across the deployment. A request with three tasks uses three questions from
each budget. At most eight provider calls run concurrently across the
deployment. These are initial defaults; operators can adjust them with
`API_DISCOVERY_ORG_QUESTIONS_PER_MINUTE`,
`API_DISCOVERY_ORG_QUESTIONS_PER_DAY`,
`API_DISCOVERY_GLOBAL_QUESTIONS_PER_MINUTE`, and
`API_DISCOVERY_GLOBAL_IN_FLIGHT`. All settings must be positive integers.
Daily budgets reset at 00:00 UTC; minute budgets reset on UTC minute
boundaries, which can allow a short burst across adjacent minutes. Calls
rejected by a limit return HTTP 429 with a `Retry-After` header in seconds.
A submitted call still counts if the provider fails. If admission is
unavailable, the endpoint returns HTTP 503 instead of contacting the provider.

Pass `operationIds` to rank only those documented operations. The list must
contain at least one unique, known `METHOD /api/path` ID. If you omit it,
Polytomic ranks all documented operations. Every ranking also includes the
no-match option. The response's `sourceSha256` is the SHA-256 of the internal processed MCP
spec artifact used to build the operation catalog. It is not the digest of the
public OpenAPI document. Treat it as an opaque catalog version for detecting
drift between the API and MCP deployments.

Each task has its own ranking in the same order as `queries`. The scores within
one task describe the relative probability of choosing each operation as the
single best option, including the no-match option. They are not independent
relevance scores and cannot be compared across tasks.

If no documented operation is the best choice, `matches` is empty. Results
come from the public API contract, not your Organization's data. Finding an
operation does not authorize you to call it; the operation's own authentication
and permissions still apply.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.operations().search(
    SearchOperationsRequest
        .builder()
        .queries(
            Arrays.asList("queries")
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum operations per task, from 1 to 10; defaults to 5.
    
</dd>
</dl>

<dl>
<dd>

**operationIds:** `Optional<List<String>>` — Optional nonempty list of unique stable operation IDs to rank; omitted to rank the full catalog.
    
</dd>
</dl>

<dl>
<dd>

**queries:** `List<String>` — One to three plain-language tasks to find API operations for.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.operations.getSearchAvailability() -> OperationSearchAvailabilityEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Reports whether operation search is configured on this API deployment.

When a request for one question would exceed an Organization-minute,
Organization-day, or deployment-minute question budget, the response includes
`rate_limited` with a reason and a UTC `reset_at` timestamp. If more than one
budget is exhausted, the timestamp reflects the latest reset. The check does
not use any question allowance.

> ⚠️ The result is a snapshot. A later request can be limited even if this
> response has no `rate_limited` field, especially if it contains two or three
> questions or other requests use the shared budget. Concurrent-call limits
> are not included. The search request's `429` response and `Retry-After` header
> are authoritative.

If your request does not identify an Organization, the response reports only
`enabled`. When `enabled` is `false`, `rate_limited` is omitted. If Polytomic
cannot check the question budgets, the endpoint returns `503`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.operations().getSearchAvailability();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Organization
<details><summary><code>client.organization.getCurrent() -> OrganizationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the organization the caller is authenticated against.

This endpoint is the safest way to discover the effective organization for a
user-scoped or organization-scoped credential. It does not let callers inspect
arbitrary organizations; it only returns the organization implied by the
credential that authenticated the request.

If you need to enumerate or look up organizations across a partner account, use
[`GET /api/organizations`](../../api-reference/organization/list) or
[`GET /api/organizations/{id}`](../../api-reference/organization/get) instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().getCurrent();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.getRecordLogging() -> RecordLoggingSettingsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the organization's record logging settings, including the connection record logs are delivered to.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().getRecordLogging();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.updateRecordLogging(request) -> RecordLoggingSettingsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Replaces the organization's record logging settings. `deliveryConnectionId` and `deliveryPrefix` are replaced, not merged: omitting either, or sending null, removes what was previously configured.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().updateRecordLogging(
    UpdateRecordLoggingSettingsRequest
        .builder()
        .enabled(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**deliveryConnectionId:** `Optional<String>` — Blobstorage connection that receives record logs after each model sync execution. Omit or send null to deliver nowhere; this field is replaced, not merged.
    
</dd>
</dl>

<dl>
<dd>

**deliveryPrefix:** `Optional<String>` — Path record logs are delivered under, ahead of the organization ID. Omit or send null for none; this field is replaced, not merged.
    
</dd>
</dl>

<dl>
<dd>

**enabled:** `Boolean` — Whether record logging is enabled for the organization.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.list() -> OrganizationsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists every organization accessible to the calling partner, with the partner's owner organization first.

In `2025-09-18`, this endpoint is partner-scoped rather than a general
"current caller visibility" listing. The partner owner organization is returned
first, followed by child organizations.

This ordering matters for partner workflows such as shared connections, where
the parent connection must live in the partner owner organization.

If you need only the organization implied by the current credential, use
[`GET /api/organization`](../../api-reference/organization/get-current) instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.create(request) -> OrganizationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new organization under the calling partner account, optionally configuring SSO or OIDC at creation time.

> 🚧 Requires partner key
>
> This endpoint is only accessible using [partner keys](../../guides/obtaining-api-keys#partner-keys).

SSO and OIDC settings supplied at creation time can be updated later via
`PUT /api/organizations/{id}`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().create(
    CreateOrganizationRequestSchema
        .builder()
        .name("My Organization")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**clientId:** `Optional<String>` — OIDC client ID issued by the identity provider.
    
</dd>
</dl>

<dl>
<dd>

**clientSecret:** `Optional<String>` — OIDC client secret issued by the identity provider. Write-only; never returned in responses.
    
</dd>
</dl>

<dl>
<dd>

**issuer:** `Optional<String>` — OIDC issuer URL for organizations using OpenID Connect single sign-on.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable name of the organization. Must be unique across the partner account.
    
</dd>
</dl>

<dl>
<dd>

**ssoDomain:** `Optional<String>` — Email domain used to match users to this organization during SSO sign-in.
    
</dd>
</dl>

<dl>
<dd>

**ssoOrgId:** `Optional<String>` — WorkOS organization identifier linking this organization to its SAML/SSO configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.get(id) -> OrganizationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single organization by ID.

> 📘 Credential scope varies by endpoint and API version
>
> Organization endpoints do not all share the same credential requirements.
> Check each endpoint's description for the caller scope that applies in that
> API version.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the organization.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.update(id, request) -> OrganizationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an organization's name and SSO or OIDC configuration.

> 🚧 Requires partner key
>
> This endpoint is only accessible using [partner keys](../../../guides/obtaining-api-keys#partner-keys).

> 📘 SSO and OIDC configuration is replaced in full on each update. Include all
> desired settings in the request body, not just the fields you want to change.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateOrganizationRequestSchema
        .builder()
        .name("My Organization")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the organization to update.
    
</dd>
</dl>

<dl>
<dd>

**clientId:** `Optional<String>` — OIDC client ID issued by the identity provider.
    
</dd>
</dl>

<dl>
<dd>

**clientSecret:** `Optional<String>` — OIDC client secret issued by the identity provider. Write-only; never returned in responses.
    
</dd>
</dl>

<dl>
<dd>

**issuer:** `Optional<String>` — OIDC issuer URL for organizations using OpenID Connect single sign-on.
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` — Human-readable name of the organization. Must be unique across the partner account.
    
</dd>
</dl>

<dl>
<dd>

**ssoDomain:** `Optional<String>` — Email domain used to match users to this organization during SSO sign-in.
    
</dd>
</dl>

<dl>
<dd>

**ssoOrgId:** `Optional<String>` — WorkOS organization identifier linking this organization to its SAML/SSO configuration.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.organization.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes an organization.

Partner callers cannot delete their own owner organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.organization().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the organization.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Activity
<details><summary><code>client.activity.list() -> HarborActivityListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists Harbor Activity recorded for the caller's organization.

You must be an active Organization administrator to use this endpoint.

`start_time` is inclusive and `end_time` is exclusive. Both filter the time at
which Polytomic recorded each event, which can differ from `occurred_at`. A
single request can cover at most 90 days.

Results are ordered from newest to oldest by default. Set `order` to `asc` to
retrieve the oldest events first. A page contains at most 100 events. Pass
`next_page_token` from the response as `page_token` with the same time range,
filters, order, and limit to retrieve the next page. The token expires 24 hours
after the first page. Pagination uses a live descending cursor, so an event from
a transaction that commits between pages can require a fresh traversal.

Responses include stable identities, bounded resource snapshots, schema label
snapshots with truncation state, field counts, and row counts when available.
They do not include internal recorded-order values, submitted SQL, raw field
names, detailed provider errors, result rows, or raw pagination tokens.

> ℹ️ Activity retention
>
> Polytomic retains Activity events for at least 90 days. Pagination tokens
> expire 24 hours after the first page.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.activity().list(
    ActivityListRequest
        .builder()
        .startTime(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
        .endTime(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
        .harborId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .eventType(
            Arrays.asList("event_type")
        )
        .outcome(
            Arrays.asList("outcome")
        )
        .operationId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .sessionId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .actorId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .credentialId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .connectionId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .limit(1)
        .pageToken("page_token")
        .order(ActivityListRequestOrder.ASC)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**startTime:** `OffsetDateTime` — Inclusive start of the event recorded-time range.
    
</dd>
</dl>

<dl>
<dd>

**endTime:** `OffsetDateTime` — Exclusive end of the event recorded-time range. The range can span at most 90 days.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of events to return. Defaults to 50 and cannot exceed 100.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request. It expires 24 hours after the first page.
    
</dd>
</dl>

<dl>
<dd>

**order:** `Optional<ActivityListRequestOrder>` — Order in which events were recorded. Defaults to desc.
    
</dd>
</dl>

<dl>
<dd>

**harborId:** `Optional<String>` — Return events for these Harbors. Repeat the parameter to filter by multiple IDs.
    
</dd>
</dl>

<dl>
<dd>

**eventType:** `Optional<String>` — Return events with these event types. Repeat the parameter to filter by multiple types.
    
</dd>
</dl>

<dl>
<dd>

**outcome:** `Optional<String>` — Return events with these outcomes. Repeat the parameter to filter by multiple outcomes.
    
</dd>
</dl>

<dl>
<dd>

**operationId:** `Optional<String>` — Return events for these operation IDs.
    
</dd>
</dl>

<dl>
<dd>

**sessionId:** `Optional<String>` — Return events for these session IDs.
    
</dd>
</dl>

<dl>
<dd>

**actorId:** `Optional<String>` — Return events for these actor IDs.
    
</dd>
</dl>

<dl>
<dd>

**credentialId:** `Optional<String>` — Return events for these credential IDs.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `Optional<String>` — Return events for these Connection IDs.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.activity.getSession(sessionId) -> HarborActivitySessionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one Harbor Activity session and its events.

You must be an active Organization administrator to use this endpoint. The
session must belong to the Organization against which you authenticated.

Events are ordered from oldest to newest by default. Set `order` to `desc` to
retrieve the newest events first. A page contains at most 100 events. Pass
`next_page_token` from the response as `page_token` with the same order and
limit to retrieve the next page.

`history_truncated` is `true` when Activity retention removed events from the
beginning of the session. The lifecycle summary remains available while the
session itself is retained.

The response uses the same event allowlist as the Activity list and detail
endpoints. It does not include session tokens, submitted SQL, raw field names,
detailed provider errors, result rows, or raw pagination tokens.

> ℹ️ Activity retention
>
> Polytomic retains Activity events for at least 90 days. Pagination tokens
> expire 24 hours after the first page.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.activity().getSession(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActivityGetSessionRequest
        .builder()
        .limit(1)
        .pageToken("page_token")
        .order(ActivityGetSessionRequestOrder.ASC)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**sessionId:** `String` — Harbor Activity session ID.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of events to return. Defaults to 50 and cannot exceed 100.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Opaque pagination cursor returned by the previous request. It expires 24 hours after the first page.
    
</dd>
</dl>

<dl>
<dd>

**order:** `Optional<ActivityGetSessionRequestOrder>` — Order in which events were recorded. Defaults to asc.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.activity.get(eventId) -> HarborActivityEventEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns one Harbor Activity event from the caller's organization.

You must be an active Organization administrator to use this endpoint. The
event must belong to the Organization against which you authenticated.

The response can include stable identities, bounded resource snapshots, schema
label snapshots with truncation state, field counts, and row counts. It does
not include internal recorded-order values, submitted SQL, raw field names,
detailed provider errors, result rows, or raw pagination tokens.

> ℹ️ Activity retention
>
> Polytomic retains Activity events for at least 90 days.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.activity().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**eventId:** `String` — Activity event ID.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Users
<details><summary><code>client.users.listCurrentOrgUsers() -> CurrentOrgListUsersEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists every user in the caller's current organization.

Returns user records including each user's ID, email, and assigned roles.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().listCurrentOrgUsers();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.createCurrentOrgUser(request) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new user in the caller's current organization and assigns the requested permissions roles.

The new user receives an invitation email prompting them to set up their
account. Role assignments take effect as soon as the invitation is accepted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().createCurrentOrgUser(
    CurrentOrgCreateUserRequestSchema
        .builder()
        .email("mail@example.com")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**email:** `String` — Email address used to sign the user in and receive notifications.
    
</dd>
</dl>

<dl>
<dd>

**role:** `Optional<String>` — Deprecated legacy role name. Use role_ids instead; setting both role and role_ids in the same request is rejected.
    
</dd>
</dl>

<dl>
<dd>

**roleIds:** `Optional<List<String>>` — Identifiers of the permissions roles to assign to the user. Must contain at least one entry when provided.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.getCurrentOrgUser(id) -> CurrentOrgUserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single user from the caller's current organization.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().getCurrentOrgUser("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.updateCurrentOrgUser(id, request) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates the permissions roles assigned to a user in the caller's current organization.

Only the user's role assignments are modified. Profile information such as name
and email address is not affected by this endpoint.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().updateCurrentOrgUser(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CurrentOrgUpdateUserRequestSchema
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the user to update.
    
</dd>
</dl>

<dl>
<dd>

**role:** `Optional<String>` — Deprecated legacy role name. Use role_ids instead.
    
</dd>
</dl>

<dl>
<dd>

**roleIds:** `Optional<List<String>>` — Identifiers of the permissions roles to assign to the user. Must contain at least one entry when provided.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.deleteCurrentOrgUser(id) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a user from the caller's current organization.

> 🚧 This action is permanent. The user is immediately removed from the
> organization and loses access to all resources within it. This cannot be
> undone.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().deleteCurrentOrgUser("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.list(orgId) -> ListUsersEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all users in the specified organization.

> 🚧 Requires partner key
>
> User endpoints are only accessible using [partner keys](../../../../guides/obtaining-api-keys#partner-keys).

Returns user records including each user's ID, email, and assigned roles.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().list("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization whose users should be listed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.create(orgId, request) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new user in the specified organization and assigns the requested permissions roles.

> 🚧 Requires partner key
>
> User endpoints are only accessible using [partner keys](../../../../guides/obtaining-api-keys#partner-keys).

The new user receives an invitation email prompting them to set up their
account. Role assignments take effect as soon as the invitation is accepted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().create(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CreateUserRequestSchema
        .builder()
        .email("mail@example.com")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization the user belongs to.
    
</dd>
</dl>

<dl>
<dd>

**email:** `String` — Email address used to sign the user in and receive notifications.
    
</dd>
</dl>

<dl>
<dd>

**role:** `Optional<String>` — Deprecated legacy role name. Use role_ids instead; setting both role and role_ids in the same request is rejected.
    
</dd>
</dl>

<dl>
<dd>

**roleIds:** `Optional<List<String>>` — Identifiers of the permissions roles to assign to the user. Must contain at least one entry when provided.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.get(orgId, id) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single user in the specified organization.

> 🚧 Requires partner key
>
> User endpoints are only accessible using [partner keys](../../../../../guides/obtaining-api-keys#partner-keys).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().get("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization the user belongs to.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.update(orgId, id, request) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates a user's assigned permissions roles.

> 🚧 Requires partner key
>
> User endpoints are only accessible using [partner keys](../../../../../guides/obtaining-api-keys#partner-keys).

Only the user's role assignments are modified. Profile information such as name
and email address is not affected by this endpoint.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateUserRequestSchema
        .builder()
        .email("mail@example.com")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization the user belongs to.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the user to update.
    
</dd>
</dl>

<dl>
<dd>

**email:** `String` — Email address used to sign the user in and receive notifications.
    
</dd>
</dl>

<dl>
<dd>

**role:** `Optional<String>` — Deprecated legacy role name. Use role_ids instead; setting both role and role_ids in the same request is rejected.
    
</dd>
</dl>

<dl>
<dd>

**roleIds:** `Optional<List<String>>` — Identifiers of the permissions roles to assign to the user. Must contain at least one entry when provided.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.delete(orgId, id) -> UserEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a user from the specified organization.

> 🚧 Requires partner key
>
> User endpoints are only accessible using [partner keys](../../../../../guides/obtaining-api-keys#partner-keys).

> 🚧 This action is permanent. The user is immediately removed from the
> organization and loses access to all resources within it. This cannot be
> undone.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().delete("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization the user belongs to.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the user.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.users.createApiKey(orgId, id) -> ApiKeyResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Issues a new API key for the specified user.

> 🚧 The API key value is only included in the response at creation time and
> cannot be retrieved again. Store it securely immediately after creation.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.users().createApiKey(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UsersCreateApiKeyRequest
        .builder()
        .force(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization the user belongs to.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the user the key will be issued for.
    
</dd>
</dl>

<dl>
<dd>

**force:** `Optional<Boolean>` — If true, revoke any existing API key for the user before creating a new one.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## RecordViewLinks
<details><summary><code>client.recordViewLinks.create(request) -> CreateRecordViewLinkEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a short-lived capability link for viewing one stored record snapshot.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.recordViewLinks().create(
    CreateRecordViewLinkRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .lookupKeyField("lookup_key_field")
        .lookupKeyValue("lookup_key_value")
        .schemaId("schema_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Connection containing the record.
    
</dd>
</dl>

<dl>
<dd>

**expiresAt:** `Optional<OffsetDateTime>` — Optional expiry timestamp. Defaults to 72 hours and cannot exceed 7 days.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<String>>` — Optional field IDs to include. If omitted, all eligible readable fields are included.
    
</dd>
</dl>

<dl>
<dd>

**lookupKeyField:** `String` — The schema lookup-key field used to identify the record. V1 only accepts the schema's single effective primary key.
    
</dd>
</dl>

<dl>
<dd>

**lookupKeyValue:** `String` — The lookup-key value for the record.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Schema containing the record.
    
</dd>
</dl>

<dl>
<dd>

**source:** `Optional<String>` — Optional creator/source label.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.recordViewLinks.getCapabilities() -> GetRecordViewCapabilitiesEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Checks whether record-view links can be created for a connection schema.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.recordViewLinks().getCapabilities(
    RecordViewLinksGetCapabilitiesRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .schemaId("schema_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` — Connection to check for record-view link support.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Schema to check for record-view link support.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## TemporaryCredentials
<details><summary><code>client.temporaryCredentials.create(request) -> TemporaryCredentialResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Issues a non-renewable credential with a bounded lifetime for a user or Harbor.

The response contains the credential secret once. Store it securely and send it
as a Bearer token in the `Authorization` header.

Set `subject.type` to `user` to issue a credential for your authenticated user.
Omit `organization_id` and `user_id`; Polytomic derives both values from your
credential. Set `mode` to `read_only` to limit the credential to the
intersection of the user's current permissions and read-only actions. A
read-only caller can issue only read-only credentials.

Partner callers must provide both `organization_id` and `user_id`. The target
must be an active user in an organization owned by the partner. User subjects
must be application users; Harbor-only users continue to use Harbor
credentials.

User credentials resolve the subject's current permissions on every request.
Permission changes take effect immediately, and deleting the user invalidates
the credential.

Set `subject.type` to `harbor` and provide the Harbor ID in `harbor_id`. The
credential uses the Harbor's current connection access on every request;
changes take effect immediately. Missing and deleted Harbors cannot be
targeted.

A temporary credential stops authenticating at `expires_at`. It cannot be
refreshed, extended, or used to create another temporary credential. Create a
new credential with a durable authorized credential when you need a later
expiration.

Each organization may have up to 1,000 active temporary credentials. The
endpoint returns `429 Too Many Requests` at the limit. Expired credentials stop
counting toward the limit immediately, before periodic cleanup removes them.

> ⚠️ Session names are audit labels
>
> Use `session_name` only for non-sensitive job or agent-session correlation.
> Do not include secrets or personal data.

Polytomic periodically removes expired credential records. API usage history
keeps its credential ID according to the normal API usage retention period.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.temporaryCredentials().create(
    CreateTemporaryCredentialRequest
        .builder()
        .subject(
            TemporaryCredentialSubject
                .builder()
                .type(TemporaryCredentialSubjectType.USER)
                .build()
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**durationSeconds:** `Optional<Integer>` — Credential lifetime in seconds. Defaults to 3600 (1 hour); minimum 600 and maximum 14400.
    
</dd>
</dl>

<dl>
<dd>

**sessionName:** `Optional<String>` — Optional audit correlation label, limited to 128 characters. Do not include secrets or personal data.
    
</dd>
</dl>

<dl>
<dd>

**subject:** `TemporaryCredentialSubject` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Webhooks
<details><summary><code>client.webhooks.list() -> WebhookListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists the webhooks for the caller's organization.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../guides/events) for the
> list of event types and payload shapes.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.create(request) -> WebhookEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates the organization's webhook.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../guides/events) for the
> list of event types and payload shapes.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().create(
    CreateWebhooksSchema
        .builder()
        .endpoint("https://example.com/webhook")
        .secret("secret")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**endpoint:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**secret:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.get(id) -> WebhookEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single webhook by ID.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../../guides/events) for the
> list of event types and payload shapes.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.update(id, request) -> WebhookEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing webhook.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../../guides/events) for the
> list of event types and payload shapes.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateWebhooksSchema
        .builder()
        .endpoint("https://example.com/webhook")
        .secret("secret")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**endpoint:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**secret:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a webhook.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../../guides/events) for the
> list of event types and payload shapes.

Deletion is permanent. To stop delivery without losing the webhook
configuration, use
[`POST /api/webhooks/{id}/disable`](../../../api-reference/webhooks/disable) instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.listDeliveries(id) -> WebhookDeliveriesEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists delivery attempts for a webhook, newest first.

Use `success`, `event_id`, `start`, and `end` to narrow the results.
Results are ordered by attempt time, newest first. Pass the returned
`next_page_token` as `page_token` to fetch the next page. An empty token means
there are no more results. Response bodies contain content returned by your
webhook endpoint. Attempts are listed only while their event is retained.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().listDeliveries(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    WebhooksListDeliveriesRequest
        .builder()
        .success(true)
        .eventId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .start(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
        .end(OffsetDateTime.parse("2024-01-15T09:30:00Z"))
        .pageToken("page_token")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**success:** `Optional<Boolean>` — Filter by delivery result.
    
</dd>
</dl>

<dl>
<dd>

**eventId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**start:** `Optional<OffsetDateTime>` — Include attempts at or after this time.
    
</dd>
</dl>

<dl>
<dd>

**end:** `Optional<OffsetDateTime>` — Include attempts before this time.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Token from the previous page.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.disable(id) -> WebhookEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Disables a webhook without deleting it.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../../../guides/events) for the
> list of event types and payload shapes.

Events are not queued while the webhook is disabled — any activity that occurs
during the disabled period is not delivered retroactively. To resume
delivery, re-enable the webhook using
[`POST /api/webhooks/{id}/enable`](../../../../api-reference/webhooks/enable).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().disable("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.webhooks.enable(id) -> WebhookEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Re-enables a previously disabled webhook.

> 📘 One webhook per organization
>
> An organization can register a single webhook, which receives every event
> produced in that organization. See the
> [Events documentation](../../../../guides/events) for the
> list of event types and payload shapes.

Delivery resumes from the next event generated after this call. Events that
occurred while the webhook was disabled are not replayed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.webhooks().enable("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## BulkSync Executions
<details><summary><code>client.bulkSync.executions.listStatus() -> ListBulkSyncExecutionsStatusEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a concise per-schema status for one or more bulk syncs.

This endpoint is a summary view, not an execution-history view. Each schema is
represented at most once with its most recent execution status, and running
executions are preferred over older terminal ones.

Use this endpoint when you want a dashboard-style answer to "what is each sync
doing now?" If you need the full execution history or a single execution's
details, use [`GET /api/bulk/syncs/{id}/executions`](../../../../api-reference/bulk-sync/executions/list) or
[`GET /api/bulk/syncs/{id}/executions/{exec_id}`](../../../../api-reference/bulk-sync/executions/get) instead.

Setting `all=true` or `active=true` ignores any explicit `sync_id` filters and
expands the request to the caller's organization scope.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().listStatus(
    ExecutionsListStatusRequest
        .builder()
        .syncId(
            Arrays.asList("248df4b7-aa70-47b8-a036-33ac447e668d")
        )
        .all(true)
        .active(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**all:** `Optional<Boolean>` — When true, return status for every sync in the caller's organization. Overrides any sync_id values.
    
</dd>
</dl>

<dl>
<dd>

**active:** `Optional<Boolean>` — When true, return status only for active syncs in the caller's organization. Overrides any sync_id values.
    
</dd>
</dl>

<dl>
<dd>

**syncId:** `Optional<String>` — Return status for the specified bulk sync. Repeat the parameter to target multiple syncs. Ignored if all or active is true.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.list(id) -> ListBulkSyncExecutionsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists executions for a bulk sync.

Results are ordered by start time descending by default. When more results are
available, the response includes an opaque `pagination.next_page_token`; pass it
back as the `page_token` query parameter to retrieve the next page. The `limit`
parameter is optional, and the maximum page size is 100 executions.

Use `only_terminal=true` to return only finished executions. In that mode,
executions are ordered by `updated_at` so recently completed runs appear first.

Use `ascending=true` to walk forward from the oldest execution instead of
starting with the newest execution.

For the full details of a single run — including per-schema execution status —
use [`GET /api/bulk/syncs/{id}/executions/{exec_id}`](../../../../../api-reference/bulk-sync/executions/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().list(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecutionsListRequest
        .builder()
        .pageToken("AmkYh8v0jR5B3kls2Qcc9y8MjrPmvR4CvaK7H0F4rEwqvg76K==")
        .onlyTerminal(true)
        .ascending(true)
        .limit(100)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Pagination cursor returned in the previous response. Omit on the first request.
    
</dd>
</dl>

<dl>
<dd>

**onlyTerminal:** `Optional<Boolean>` — When true, only return executions that have finished. Terminal executions are ordered by updated_at.
    
</dd>
</dl>

<dl>
<dd>

**ascending:** `Optional<Boolean>` — When true, return executions from oldest to newest. Default is newest first.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of executions to return. Capped at 100.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.get(id, execId) -> BulkSyncExecutionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single bulk sync execution, including per-schema execution status.

The response includes a breakdown of each schema (table or object) that
participated in the execution, with its individual status, row counts, and any
error details. This makes it suitable for diagnosing partial failures where
some schemas succeeded while others did not.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().get("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**execId:** `String` — Unique identifier of the execution.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.cancel(id, execId) -> CancelBulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Requests cancellation of a specific bulk sync execution.

Cancellation is asynchronous. A successful response means the cancellation
signal has been queued; the execution continues to run until the signal is
processed. Poll `GET /api/bulk/syncs/{id}/executions/{exec_id}` until the
execution reaches a terminal state (`completed`, `canceled`, or `failed`) to
confirm cancellation has taken effect.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().cancel("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — The bulk sync ID.
    
</dd>
</dl>

<dl>
<dd>

**execId:** `String` — The execution ID to cancel.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.getConsoleLogs(syncId, executionId) -> ExecutionConsoleLogsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Fetch the latest console log entries for a bulk sync execution. Returns the most recent 50 entries.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().getConsoleLogs(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "0ecd09c1-b901-4d27-9053-f0367c427254",
    ExecutionsGetConsoleLogsRequest
        .builder()
        .limit(50)
        .after("1744311099250-0")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of entries to return. Values above the logger retention limit are capped to 50.
    
</dd>
</dl>

<dl>
<dd>

**after:** `Optional<String>` — Return only entries newer than this cursor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.getLogs(syncId, executionId) -> BulkSyncExecutionLogsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns signed URLs for the log files produced by a single bulk sync execution.

Each URL in the response is pre-signed and grants temporary read access to the
corresponding log file. URLs expire after a short period; if you need to access
a file after the URL has expired, call this endpoint again to obtain a fresh set
of signed URLs.

> 📘 To export logs asynchronously to a destination of your choice, use
> [`POST /api/bulk/syncs/{sync_id}/executions/{execution_id}/logs/export`](../../../../../../../api-reference/bulk-sync/executions/export-logs)
> instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().getLogs("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` — Unique identifier of the execution whose log files should be listed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.exportLogs(syncId, executionId) -> ExportSyncLogsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Starts an asynchronous job that packages the log files for a single bulk sync execution into a downloadable archive.

> 📘 Log export is asynchronous
>
> This endpoint starts a background job that packages an execution's log
> files into a downloadable archive. The first call typically returns a
> `job` descriptor instead of a completed result. Poll
> [`GET /api/jobs/exportlogs/{id}`](../../../../../../../../api-reference/jobs/get)
> with the returned `job_id` until `status` is `done`; the final response
> contains a signed `url` that can be used to download the archive.
>
> Set `notify=true` to also email the requesting user when the archive is
> ready.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().exportLogs(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecutionsExportLogsRequest
        .builder()
        .notify_(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` — Unique identifier of the execution whose logs should be exported.
    
</dd>
</dl>

<dl>
<dd>

**notify:** `Optional<Boolean>` — Send a notification to the user when the logs are ready for download.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.getSchemaConsoleLogs(syncId, executionId, schemaId) -> ExecutionConsoleLogsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Fetch the latest console log entries for a schema within a bulk sync execution. Returnst the most recent 50 entries.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().getSchemaConsoleLogs(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "0ecd09c1-b901-4d27-9053-f0367c427254",
    "users",
    ExecutionsGetSchemaConsoleLogsRequest
        .builder()
        .limit(50)
        .after("1744311099250-0")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Schema identifier for schema-scoped console logs.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of entries to return. Values above the logger retention limit are capped to 50.
    
</dd>
</dl>

<dl>
<dd>

**after:** `Optional<String>` — Return only entries newer than this cursor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.executions.getIngestConsoleLogs(connectionId) -> ExecutionConsoleLogsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Fetch the latest console log entries for ingestion scoped by connection and optional bulk sync. Returns the most recent 50 entries.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().executions().getIngestConsoleLogs(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecutionsGetIngestConsoleLogsRequest
        .builder()
        .syncId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .limit(50)
        .after("1744311099250-0")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**syncId:** `Optional<String>` — Optional bulk sync ID for sync-scoped ingestion logs.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of entries to return. Values above the logger retention limit are capped to 50.
    
</dd>
</dl>

<dl>
<dd>

**after:** `Optional<String>` — Return only entries newer than this cursor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## BulkSync ErrorHandling
<details><summary><code>client.bulkSync.errorHandling.get(id) -> BulkSyncErrorHandlingEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the error handling settings for a bulk sync.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().errorHandling().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.errorHandling.update(id, request) -> BulkSyncErrorHandlingEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates the error handling settings for a bulk sync.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().errorHandling().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateBulkSyncErrorHandlingRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**ingestionFailureThreshold:** `Optional<Integer>` — How far behind ingestion may fall before a terminal execution is failed, in the unit this sync's source reports: seconds for a source carrying event timestamps, outstanding items for a queue-backed source such as S3. Send 0 to clear this sync's own threshold, after which a source reporting seconds follows the deployment-wide default and a queue-backed source is left unchecked. Omit to leave unchanged.
    
</dd>
</dl>

<dl>
<dd>

**subscribers:** `Optional<List<String>>` — Email addresses notified when this sync fails. Replaces the current list; pass an empty list to unsubscribe everyone. Omit to leave the list unchanged.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## BulkSync Schemas
<details><summary><code>client.bulkSync.schemas.list(id) -> ListBulkSchemaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists the schemas (tables, objects) configured for a bulk sync.

This endpoint returns the schemas that have been added to and configured on this
specific bulk sync — not the full set of schemas available from the source
connection. To discover what the source connection exposes, use the source
schemas endpoint for the relevant connection type.

Each schema in the response includes its sync mode, field selections, and any
custom configuration applied via
[`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../api-reference/bulk-sync/schemas/patch)
or
[`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../api-reference/bulk-sync/schemas/update).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schemas().list(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    SchemasListRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**filters:** `Optional<Map<String, Optional<String>>>` — Optional filters applied to the returned schemas. Supports enabled=true to return only enabled schemas and enabled=false to return only disabled schemas.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schemas.patch(id, request) -> UpdateBulkSyncSchemasEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Patches one or more schemas on a bulk sync at once.

Only schemas explicitly included in the request body are modified; schemas
omitted from the request are left unchanged. This makes PATCH the right choice
when you want to update a subset of tables without affecting the rest of the
sync's schema configuration.

Within each provided schema, omitting `fields` enables all available fields on
that schema. To control which fields are enabled, include the `fields` array
with explicit `enabled` values for each field.

> 📘 To replace a single schema's configuration in full (clearing any fields you
> omit), use
> [`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../api-reference/bulk-sync/schemas/update)
> instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schemas().patch(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateBulkSyncSchemasRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**schemas:** `Optional<List<BulkSchema>>` — Schemas to patch. Schemas are matched by id; only schemas present in this list are updated.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schemas.get(id, schemaId) -> BulkSchemaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the configuration of a single schema on a bulk sync.

Returns the sync mode, field selections, and any other configuration applied to
this schema on the bulk sync.

To modify the configuration, use
[`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../../api-reference/bulk-sync/schemas/patch)
for a partial update across multiple schemas, or
[`PUT /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../../api-reference/bulk-sync/schemas/update)
to fully replace this schema's configuration.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schemas().get("248df4b7-aa70-47b8-a036-33ac447e668d", "Contact");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Source-side schema identifier.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schemas.update(id, schemaId, request) -> BulkSchemaEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Replaces the configuration of a single schema on a bulk sync.

This is a full replacement: every field in the request body is written to the
schema, and any field you omit is cleared or reset to its default. Fetch the
current configuration with
[`GET /api/bulk/syncs/{id}/schemas/{schema_id}`](../../../../../../api-reference/bulk-sync/schemas/get)
first if you want to preserve existing settings while changing only a subset.

Omitting `fields` enables all available fields on the schema. To control which
fields are enabled, include the `fields` array with explicit `enabled` values.

> 📘 To update multiple schemas in a single request without affecting others,
> use the partial-update endpoint
> [`PATCH /api/bulk/syncs/{id}/schemas`](../../../../../../api-reference/bulk-sync/schemas/patch)
> instead.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schemas().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "contact",
    UpdateBulkSchema
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Source-side schema identifier.
    
</dd>
</dl>

<dl>
<dd>

**dataCutoffTimestamp:** `Optional<OffsetDateTime>` — Per-schema cutoff. Records older than this timestamp are excluded from sync runs.
    
</dd>
</dl>

<dl>
<dd>

**disableDataCutoff:** `Optional<Boolean>` — When true, the sync ignores any configured data_cutoff_timestamp for this schema.
    
</dd>
</dl>

<dl>
<dd>

**enabled:** `Optional<Boolean>` — Whether this schema is included in sync runs.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<UpdateBulkField>>` — Field-level configuration. Supplying an empty list enables every field discovered on the source.
    
</dd>
</dl>

<dl>
<dd>

**filters:** `Optional<List<BulkFilter>>` — Row-level filters applied when reading from the source.
    
</dd>
</dl>

<dl>
<dd>

**historyEnabled:** `Optional<Boolean>` — Whether a companion history table is maintained beside this schema's output. Requires a replicate-mode sync to a destination reporting supports_history_mode. Omit to keep the current value.
    
</dd>
</dl>

<dl>
<dd>

**partitionKey:** `Optional<String>` — Source field used to partition rows when writing to the destination.
    
</dd>
</dl>

<dl>
<dd>

**trackingField:** `Optional<String>` — Source field used to detect changes between incremental sync runs.
    
</dd>
</dl>

<dl>
<dd>

**userOutputName:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schemas.cancel(id, schemaId) -> CancelBulkSyncResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Requests cancellation of any running executions for a specific schema on a bulk sync. A schema whose only running work is a backfill returns a conflict.

Cancellation is asynchronous. A successful response means the cancellation
signal for this schema has been queued; the schema's in-flight work continues
until the signal is processed. Poll
`GET /api/bulk/syncs/{id}/schemas/{schema_id}` and the parent execution via
`GET /api/bulk/syncs/{id}/status` to confirm the schema has reached a terminal
state.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schemas().cancel("248df4b7-aa70-47b8-a036-33ac447e668d", "schema_id");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — The bulk sync ID.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — The schema ID to cancel for the bulk sync.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## BulkSync Schedules
<details><summary><code>client.bulkSync.schedules.list(syncId) -> SchedulesEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all schedules configured for a bulk sync.

A bulk sync can have multiple schedules attached; this endpoint returns all
of them. Schedule times are returned in UTC.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schedules().list("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync whose schedules should be returned.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schedules.create(syncId, request) -> ScheduleEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Adds a new schedule to a bulk sync.

A bulk sync can have multiple schedules attached; adding one here does not
replace existing schedules. Schedule times are interpreted in UTC.

Creating a schedule only affects future automatic executions. To run the
sync immediately, call
[`POST /api/bulk/syncs/{id}/executions`](../../../../../api-reference/bulk-sync/start).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schedules().create(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    CreateScheduleRequest
        .builder()
        .schedule(
            BulkSyncScheduleApi
                .builder()
                .frequency(ScheduleFrequency.MANUAL)
                .build()
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync to add a schedule to.
    
</dd>
</dl>

<dl>
<dd>

**schedule:** `BulkSyncScheduleApi` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schedules.get(syncId, scheduleId) -> ScheduleEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single schedule configured on a bulk sync.

Schedule times are returned in UTC.

To see all schedules on this sync, use
[`GET /api/bulk/syncs/{sync_id}/schedules`](../../../../../../api-reference/bulk-sync/schedules/list).
To update the schedule, use
[`PUT /api/bulk/syncs/{sync_id}/schedules/{schedule_id}`](../../../../../../api-reference/bulk-sync/schedules/update).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schedules().get("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**scheduleId:** `String` — Unique identifier of the schedule.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schedules.update(syncId, scheduleId, request) -> ScheduleEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing schedule on a bulk sync.

Updates replace the stored schedule. Send the full schedule definition
rather than only the field you want to change. Schedule times are
interpreted in UTC.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schedules().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateScheduleRequest
        .builder()
        .schedule(
            BulkSyncScheduleApi
                .builder()
                .frequency(ScheduleFrequency.MANUAL)
                .build()
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**scheduleId:** `String` — Unique identifier of the schedule to update.
    
</dd>
</dl>

<dl>
<dd>

**schedule:** `BulkSyncScheduleApi` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.bulkSync.schedules.delete(syncId, scheduleId)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Removes a schedule from a bulk sync.

Deleting a schedule only stops future automatic executions. It does not
cancel an execution that is already running.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.bulkSync().schedules().delete("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the bulk sync.
    
</dd>
</dl>

<dl>
<dd>

**scheduleId:** `String` — Unique identifier of the schedule to delete.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Connections Proxy
<details><summary><code>client.connections.proxy.executeProxy(id, request) -> ExecuteConnectionProxyEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Proxies an HTTP request to a connection's underlying API using the connection's stored credentials, subject to per-connection rate limits and size caps.

This endpoint is intended for controlled passthrough use, not as a general
replacement for Polytomic's modeled endpoints. The request is executed with the
connection's stored credentials and inherited base URL, headers, and query
parameters.

Before building requests dynamically, call
[`GET /api/connections/{id}/proxy/info`](../../../../api-reference/connections/get-proxy-info)
to inspect the inherited base URL, blocked headers, accepted body types, and
size and rate limits.

## Important behavior

- For connections that expose more than one API (listed in `apis` in the proxy
  info response), set `request.api` to the name of the API to call. Requests
  without `request.api` go to the default API. `request.api` is rejected for
  connections that expose a single API.
- `request.path` must be relative and start with `/`.
- Use either `request.query` or `request.rawQuery`, not both.
- Caller-supplied headers are merged with inherited headers, but inherited auth
  headers cannot be overridden.
- The proxy strips a fixed set of request and response headers for safety.
- Response bodies larger than the configured maximum are truncated, and
  `truncated` is set to `true`.
- A `429` means Polytomic's proxy rate limit was reached, or the connection's
  upstream quota, which the proxy shares with the connection's syncs, is
  exhausted.

To run a `GET` request asynchronously, set `async` to `true`. The initial
response returns `status: 202`, `jobId`, `jobStatus`, and `jobUrl`. Poll
[`GET /api/jobs/{type}/{id}`](../../../../api-reference/jobs/get-job) with
`type=connectionproxy` and the returned `jobId` until the job is complete. The
completed job result includes the upstream `status`, sanitized `headers`,
`contentType`, `contentLength`, `latencyMs`, and a short-lived
`bodyDownloadUrl` for the upstream response body.

The response includes `proxyCallId`, which you can use to correlate the call
with audit logs.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().proxy().executeProxy(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecuteConnectionProxyRequest
        .builder()
        .request(
            ConnectionProxyCall
                .builder()
                .method("GET")
                .path("/v1/objects")
                .build()
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection to proxy the request through.
    
</dd>
</dl>

<dl>
<dd>

**async:** `Optional<Boolean>` — When true, submits a GET request for asynchronous execution and returns a job handle instead of a synchronous upstream response.
    
</dd>
</dl>

<dl>
<dd>

**request:** `ConnectionProxyCall` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.proxy.getProxyInfo(id) -> GetConnectionProxyInfoEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the proxy contract for a connection.

Use this endpoint before calling
[`POST /api/connections/{id}/proxy`](../../../../../api-reference/connections/execute-proxy)
when you need to build requests programmatically. The response shows:

- the inherited base URL that all proxied requests are sent to
- locked headers and query parameters that are attached automatically
- blocked request and response headers
- allowed HTTP methods and body shapes
- timeout, rate-limit, and payload-size limits

Some connections reach more than one upstream API, each with its own base URL
and quota. For these, the response includes `apis`: one entry per API with its
`name`, `description`, whether it is the `default`, and its own
`inheritedBase`. The top-level `inheritedBase` describes the default API.
Connections with a single API omit `apis`.

Sensitive inherited header and query values are redacted in the response. The
contract is still useful for discovering which keys are fixed by the
connection, even though their raw values are not exposed.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().proxy().getProxyInfo("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose proxy contract should be returned.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.proxy.getProxySettings(id) -> ConnectionProxySettingsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns whether a connection can be used through the Connection Proxy API.

The setting is stored on the parent connection. When you request settings for a
shared connection, the response includes both the requested `connectionId` and the
`parentConnectionId` that controls proxy access. For non-shared connections,
`parentConnectionId` is omitted.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().proxy().getProxySettings("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose proxy settings should be returned.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.proxy.updateProxySettings(id, request) -> ConnectionProxySettingsEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Enables or disables use of a connection through the Connection Proxy API.

The setting is stored on the parent connection. To update proxy access for a
shared connection, the caller must have edit permission for the parent
connection.

Enabling proxy access requires a backend that supports the Connection Proxy API.
If the connection backend is unsupported, the request returns `400 Bad Request`.
Disabling proxy access is allowed for any connection the caller can edit.

Setting `enabled` to `false` prevents proxy calls for the connection.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().proxy().updateProxySettings(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateConnectionProxySettingsRequest
        .builder()
        .enabled(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection whose proxy settings should be updated.
    
</dd>
</dl>

<dl>
<dd>

**enabled:** `Boolean` — Whether the connection can be used through the Connection Proxy API.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Connections SharedConnections
<details><summary><code>client.connections.sharedConnections.listSharedConnections(id) -> ConnectionListResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists shared copies of a connection that the caller's organization owns.

The returned connections are the child copies, not the parent connection
itself. This is useful when a partner workflow needs to confirm which
downstream organizations have already received a shared copy.

Creating a new shared copy is a separate operation. Use
[`POST /api/organizations/{org_id}/connections/{connection_id}/share`](../../../../api-reference/connections/create-shared-connection)
for the v5 partner-scoped flow.

## Observed rate limits

You can use `rate_limit` to inspect observed rate limiting separately from
Connection health. A Connection can be healthy while Polytomic has an active
rate-limit marker. Shared Connections combine observations recorded for their
own ID and their root Connection. Observations recorded only for another shared
copy are not included.

When these observed periods overlap or touch, `limited_since` reflects the start
of the continuous period and `expires_at` reflects its latest expiry. An expired
period separated from the active period by a gap does not extend that start.

> ⚠️ Observation, not a capacity guarantee
>
> An active marker does not mean every endpoint or sync is blocked. No active
> marker does not guarantee that the upstream service has capacity. The marker
> expiry can be extended and is not a promised provider reset or exact retry time.

If any required lookup is unavailable, `rate_limit` is `null`. This does not change
`status` or `status_error`, and the Connection response is still returned.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().sharedConnections().listSharedConnections("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the parent connection whose shared copies should be listed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.sharedConnections.listSharedConnectionsForPartner(orgId, connectionId) -> ConnectionListResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists shared copies of a connection owned by a specific organization in the partner account.

The `org_id` must match the organization that owns the parent connection. If it
does not, the endpoint returns `404` rather than exposing information about the
parent connection.

This endpoint is useful in partner workflows where the parent connection is in
the partner owner organization and the caller needs to audit which child
organizations already have a shared copy.

## Observed rate limits

You can use `rate_limit` to inspect observed rate limiting separately from
Connection health. A Connection can be healthy while Polytomic has an active
rate-limit marker. Shared Connections combine observations recorded for their
own ID and their root Connection. Observations recorded only for another shared
copy are not included.

When these observed periods overlap or touch, `limited_since` reflects the start
of the continuous period and `expires_at` reflects its latest expiry. An expired
period separated from the active period by a gap does not extend that start.

> ⚠️ Observation, not a capacity guarantee
>
> An active marker does not mean every endpoint or sync is blocked. No active
> marker does not guarantee that the upstream service has capacity. The marker
> expiry can be extended and is not a promised provider reset or exact retry time.

If any required lookup is unavailable, `rate_limit` is `null`. This does not change
`status` or `status_error`, and the Connection response is still returned.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().sharedConnections().listSharedConnectionsForPartner("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization that owns the parent connection.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the parent connection whose shared copies should be listed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.connections.sharedConnections.createSharedConnection(orgId, connectionId, request) -> CreateSharedConnectionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Shares a connection with another organization in the caller's partner account.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.connections().sharedConnections().createSharedConnection(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    PartnerCreateSharedConnectionRequestSchema
        .builder()
        .childOrganizationId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**orgId:** `String` — Unique identifier of the organization that owns the parent connection.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Unique identifier of the parent connection to share.
    
</dd>
</dl>

<dl>
<dd>

**childOrganizationId:** `String` — Unique identifier of the child organization that should receive the shared connection.
    
</dd>
</dl>

<dl>
<dd>

**name:** `Optional<String>` — Optional name for the shared copy. Defaults to the parent connection name.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Harbors Actions
<details><summary><code>client.harbors.actions.getExecution(harborId, executionId) -> HarborActionExecutionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Read a metadata-only action receipt without resubmitting the action.

Use a currently valid scoped credential belonging to the original Harbor. The
receipt remains readable after the action or rollout feature is disabled. A
credential from another Harbor cannot inspect it. The response does not contain
lookup values, input values, output payloads, credential secrets, or raw provider
errors. It includes structured operation identity, lookup field names, submitted
field names, and the original credential ID.

An overdue executing receipt transitions atomically to `unknown`; this read
never invokes the destination provider. Stop polling at `succeeded`, `failed`, or `unknown`.
Unknown is terminal for this execution identifier and means the update may have
happened. Investigate rather than preparing a replacement action to retry.

Preparation alone has no execution receipt. A `404 Not Found` after an uncertain
execution does not prove the operation never happened.

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID`. Direct REST requests
may omit `X-Polytomic-Harbor-Session`; a supplied session must be active and bound
to the same credential and Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().getExecution(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActionsGetExecutionRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.actions.list(harborId) -> HarborActionListEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

List a page of configured action identities without loading provider capabilities or field metadata.

Use a scoped credential belonging to this Harbor. An administrator must first
select Connections and explicitly enable object operations and fields. These
grants apply to existing and future eligible Harbor credentials without changing
read access. Newly available objects and fields remain disabled until selected.

Each entry identifies a configured operation by `connection_id`, `schema_id`, and
`operation_id`. Search filters those identities. Follow
`pagination.next_page_token` with the same search to read additional pages.
Pages contain saved identities without field metadata or provider capability
checks. `unavailable: true` means the saved Connection is unavailable for actions;
its permissions remain saved and revocable. An available Connection does not
confirm that its operations or granted fields are currently available.

Use [Describe action](../../../../api-reference/harbors/actions/describe) for the selected
operation before looking up a record or
[preparing an action](../../../../api-reference/harbors/actions/prepare). Description checks
current provider capabilities and returns the operation's `effect` (`read_only`
or `mutating`) and effective granted fields.
Always submit the intended Connection explicitly when looking up or preparing,
even if only one is enabled. If several destinations match your intent, clarify
which one to use.

Read-only operations use [Lookup action](../../../../api-reference/harbors/actions/lookup)
without preparation or approval. Salesforce and HubSpot support exact lookups by
their canonical record ID. Listing does not grant additional permissions or
authorize mutations by a read-only credential.

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID`. For direct REST
requests, `X-Polytomic-Harbor-Session` is optional. If supplied, the session must
be active and bound to the credential and Harbor. Discovery is recorded as
`action.listed`; no response is returned if that event cannot be recorded.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().list(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActionsListRequest
        .builder()
        .search("search")
        .pageToken("page_token")
        .limit(1)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**search:** `Optional<String>` — Filter configured schema or operation identities.
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` — Continuation token from the previous page; keep search unchanged.
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.actions.describe(harborId) -> HarborActionDescribeEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Describe one granted operation and its currently available enabled fields.

Select an identity from [List actions](../../../../../api-reference/harbors/actions/list).
Supply its `connection_id`, `schema_id`, and `operation_id`. Use a scoped
credential belonging to this Harbor; description does not require write access.

`effect` identifies an operation as `read_only` or `mutating`. For read-only
operations, `lookup_fields` and `output_fields` contain only fields both granted
by the administrator and currently available through the Connection.
`input_fields` is empty. Use
[Lookup action](../../../../../api-reference/harbors/actions/lookup) to return one projected
record without preparation.

For mutations, `input_fields` contains only granted, currently available fields.
`lookup_fields` and `output_fields` describe the connector's lookup and output.
Fields retain their types, constraints, required flags, and nullability. Supply
exactly one lookup when `lookup_fields` is nonempty; otherwise omit it. Omitted
input fields remain unchanged. Explicit null requires `nullable: true`.

For mutations, `idempotency` describes remote deduplication, not permission to
retry. Harbor write receipts remain metadata-only.

A provider discovery failure or a granted operation that is no longer available
returns `503 Service Unavailable`, not an empty field list. An ungranted identity
returns `403 Forbidden`. These responses do not revoke saved permissions.
Polytomic checks current grants and provider capabilities again at execution.

Description fetches only the selected object's operations. It does not fetch
fields for the entire catalog. Lookup permissions are checked against fresh
provider metadata. Provider permissions and automation still apply.

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID`. A supplied
`X-Polytomic-Harbor-Session` must be active and bound to this credential and
Harbor. Successful description is recorded as `action.listed`.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().describe(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ActionsDescribeRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .schemaId("schema_id")
        .operationId("operation_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**operationId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.actions.execute(harborId, request) -> HarborActionExecutionEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Execute a prepared action with at most one application attempt per server-issued execution identifier.

First call [Prepare action](../../../../../api-reference/harbors/actions/prepare). Submit only
its server-issued `execution_id` using a writable scoped credential belonging to
the same Harbor. The destination, operation, lookup, and input are fixed by
preparation. No per-request approval is required.

Polytomic checks current grants, provider capabilities, and the saved Connection
again before execution. Preparation does not reserve permission. An expired
preparation cannot start an execution. It returns `410 Gone` while the expired
preparation remains available, or `404 Not Found` after cleanup.

> 🚧 Updates can overwrite intervening edits
>
> Enabled operations can act on records accessible through the saved Connection
> and may trigger provider automation. Preparation does not lock the destination
> record. Action permission does not grant read access.

## One intended attempt

An identifier already claimed for execution returns its original receipt,
including through another eligible credential or after action disablement.
Receipts remain available after prepared arguments are removed or expire.
They are retained independently of Activity history.

An `action.attempt_started` event means permission to attempt the action was
claimed, not that the provider received it. Disabling actions blocks new claims
but does not recall an accepted attempt. This is at most one application attempt
per execution identifier, not a remote exactly-once guarantee. Advertised remote
idempotency does not authorize automatic replay.

## Results and recovery

Keep `execution_id` and the returned `status_path`. `succeeded` means the provider
confirmed the operation and Polytomic recorded that outcome. `failed` means the
operation was rejected. `executing` is incomplete. `recovery_required: true`
does not confirm durable acceptance or completion. Use the status path after a
timeout or server error. A missing receipt does not prove no operation occurred.

> ⚠️ An unknown outcome is terminal
>
> `unknown` means the operation may have happened. Investigate the record and
> provider automation. Do not resubmit or prepare a replacement action to retry.
> Polytomic never automatically retries an uncertain attempt. An overdue
> executing receipt becomes unknown after its 90-second deadline.

Send a separate nonzero UUID in `X-Polytomic-Activity-Request-ID` for each HTTP
request. MCP supplies this transport header automatically.
`X-Polytomic-Harbor-Session` is optional for direct REST requests; a supplied
session must be active and bound to your credential and Harbor. Receipts and
Activity contain operation identity, lookup field names, submitted field names,
original attribution, and safe outcome categories. They exclude lookup values,
input values, output payloads, and raw provider errors.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().execute(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecuteHarborActionRequest
        .builder()
        .executionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**executionId:** `String` — Server-issued identifier returned by prepare. Preserve it for status recovery; never prepare a replacement to retry uncertainty.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.actions.lookup(harborId, request) -> HarborActionLookupEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Look up exactly one record using a granted read-only Harbor action.

Use a scoped credential belonging to this Harbor, including a read-only
credential. An administrator must grant the Connection, read-only operation,
lookup field, and returned fields. Select an identity with
[List actions](../../../../../api-reference/harbors/actions/list), then inspect its effective
lookup and output fields with
[Describe action](../../../../../api-reference/harbors/actions/describe).

Polytomic checks current grants and provider capabilities on each lookup. The
response contains one record under `data`, limited to the selected fields.
Omitting `fields` returns all currently available granted outputs;
new provider fields remain excluded until an administrator grants them.
Salesforce uses `Id`; HubSpot uses `hs_object_id`. Preserve these IDs as strings.
Alternate keys, fuzzy matches, search, and batching are unsupported.

A definite absence returns `404 Not Found`. More than one exact match returns
`409 Conflict`. Invalid selections return `400 Bad Request`; unavailable
capabilities or provider failures return `503 Service Unavailable`. Errors do
not include lookup values or provider response bodies.

This request is synchronous and read-only. It requires no preparation, approval,
execution identifier, or status polling. It creates no write receipt or private
write evidence. Harbor Activity records `action.looked_up` with field names and
an outcome, never the lookup value or returned values. If Activity cannot be
recorded, Polytomic returns no record.

Unknown properties, duplicate keys, invalid Unicode, trailing JSON, and bodies
larger than 256 KiB are rejected. Lookup values must be JSON scalars. Numeric
values must use integer notation within +/-9007199254740991.

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID` for each request.
`X-Polytomic-Harbor-Session` is optional for direct REST requests. A supplied
session must be active and bound to your credential and Harbor.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().lookup(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    LookupHarborActionRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .lookup(
            ActionLookup
                .builder()
                .build()
        )
        .operationId("operation_id")
        .schemaId("schema_id")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Connection ID from Harbor action discovery.
    
</dd>
</dl>

<dl>
<dd>

**fields:** `Optional<List<String>>` — Unique, nonempty subset of granted output field IDs. Omit to return all currently available granted outputs. Null and empty arrays are invalid.
    
</dd>
</dl>

<dl>
<dd>

**lookup:** `ActionLookup` 
    
</dd>
</dl>

<dl>
<dd>

**operationId:** `String` — Exact read-only operation ID from action discovery.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Exact schema ID from action discovery.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.harbors.actions.prepare(harborId, request) -> HarborActionPreparationEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Validate and prepare an enabled action without executing it, returning a server-issued execution identifier.

Use a writable scoped credential belonging to this Harbor. An administrator must
first enable the destination Connection, operation, and input fields. Select an
identity with [List actions](../../../../../api-reference/harbors/actions/list), then inspect
its fields with [Describe action](../../../../../api-reference/harbors/actions/describe).

Preparation validates and temporarily stores the exact destination, lookup, and
input. It returns a server-generated `execution_id` and `expires_at`. You do not
supply an execution UUID. Preparation neither performs nor approves a destination
mutation. Call [Execute action](../../../../../api-reference/harbors/actions/execute) with only
the returned identifier within 15 minutes. Polytomic checks current permissions,
provider capabilities, and the saved Connection again at execution.

Supply one advertised lookup when `lookup_fields` is nonempty. Otherwise omit
`lookup`. Omitted input fields remain unchanged. Explicit `null` requires
`nullable: true`. Empty and blank strings follow the advertised constraints.
Values are JSON scalars; arrays, nested objects, and type coercion are unsupported.
Numbers must use integer JSON notation, without a decimal point or exponent, and
lie between -9007199254740991 and 9007199254740991. Preserve opaque IDs as strings.
Unknown envelope properties, duplicate keys, invalid Unicode, trailing JSON, and
bodies larger than 256 KiB are rejected.

## Lifetime and recovery

Prepared arguments are fixed for that identifier. Polytomic removes them when
execution is claimed and periodically cleans up expired, unexecuted preparations.
Execution receipts and Activity event metadata contain no submitted values.
Polytomic retains a separate encrypted copy of the target and submitted values
for 90 days from preparation. Only Organization administrators can reveal these
details in the audit ledger. MCP receipts do not expose them. This evidence
records your request, not a verified before-and-after record state.
Preparation alone does not create an execution receipt.

If the preparation response is lost, you may prepare again: no destination
mutation occurred. Each preparation creates a distinct execution identifier.

> ⚠️ Preserve the identifier after execution
>
> After submitting an execution, use its original `execution_id` to investigate
> an uncertain outcome. Do not prepare a replacement action to retry it.

Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID` for each HTTP request.
MCP supplies this transport header automatically. `X-Polytomic-Harbor-Session` is
optional for direct REST requests; a supplied session must be active and bound
to your credential and Harbor. Preparation is recorded as `action.prepared`,
with its original actor and execution identifier. Expired, unexecuted
preparations are recorded as `action.preparation_expired`. Execution records its
own actor and attempt separately.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.harbors().actions().prepare(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    PrepareHarborActionRequest
        .builder()
        .connectionId("248df4b7-aa70-47b8-a036-33ac447e668d")
        .operationId("operation_id")
        .schemaId("schema_id")
        .input(
            new HashMap<String, Object>() {{
                put("key", "value");
            }}
        )
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**harborId:** `String` — Unique identifier of the Harbor.
    
</dd>
</dl>

<dl>
<dd>

**polytomicHarborSession:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**polytomicActivityRequestId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**connectionId:** `String` — Explicit destination connection ID from action discovery. Must have this action and its submitted fields enabled in this Harbor.
    
</dd>
</dl>

<dl>
<dd>

**input:** `Map<String, Object>` 
    
</dd>
</dl>

<dl>
<dd>

**lookup:** `Optional<ActionLookup>` 
    
</dd>
</dl>

<dl>
<dd>

**operationId:** `String` — Exact operation_id from action discovery.
    
</dd>
</dl>

<dl>
<dd>

**schemaId:** `String` — Exact schema_id from action discovery.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## ModelSync Targets
<details><summary><code>client.modelSync.targets.getTargetFields(id) -> TargetResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the fields, modes, and properties of a target object on a connection.

Pass the target object identifier to retrieve the fields available for
mapping on that object. These are the destination fields you can reference
when configuring field mappings in a model sync.

> 📘 To list available target objects and their identifiers, use
> [`GET /api/connections/{id}/modelsync/targetobjects`](../../../../../../api-reference/model-sync/targets/list).

Fields returned here reflect the connection's current cached state. If the
upstream object schema has changed, trigger a schema refresh with
[`POST /api/connections/{id}/schemas/refresh`](../../../../../../api-reference/schemas/refresh)
before calling this endpoint.

## Fields for a target that hasn't been created yet

Some connections support creating a new destination object as part of a
model sync — for example, a Facebook Ads custom audience or a LinkedIn Ads
contact list. In that case there is no existing target identifier to pass;
instead, describe the new target with the same properties returned in the
`target_creation` block of
[`GET /api/connections/{id}/modelsync/targetobjects`](../../../../../../api-reference/model-sync/targets/list),
and this endpoint will return the fields the new target will expose.

Exactly one of `target` or `properties` must be supplied. Each input is
sent as a separate `properties[key]=value` query parameter. For a Facebook
Ads connection that requires an `account` and a `name`:

```
GET /api/connections/{id}/modelsync/target/fields
  ?properties[account]=act_1234567
  &properties[name]=My%20new%20audience
```

The response shape is identical to the existing-target form. For backends
where the new target's field set is fixed (most ads platforms), `fields`
contains those fields; for backends where the columns are user-defined
(e.g. a SQL database), `fields` will be empty and the caller defines the
columns at mapping time.

When `properties` is supplied, the `refresh` parameter is ignored — a
not-yet-created target has no cached schema to refresh.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().targets().getTargetFields(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    TargetsGetTargetFieldsRequest
        .builder()
        .target("database.table")
        .refresh(false)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the connection.
    
</dd>
</dl>

<dl>
<dd>

**target:** `Optional<String>` — Identifier of the target object (e.g. schema.table for a database destination, object name for a SaaS destination). Required unless properties is supplied.
    
</dd>
</dl>

<dl>
<dd>

**refresh:** `Optional<Boolean>` — When true, force a cache refresh of the target's schema before returning its fields. Ignored when properties is supplied.
    
</dd>
</dl>

<dl>
<dd>

**properties:** `Optional<Map<String, Optional<List<String>>>>` — Target-creation property values, supplied as properties[key]=value, matching the target_creation.properties returned by GET /api/connections/{id}/modelsync/targetobjects. When supplied, the response describes the not-yet-created target that would result from these inputs, in the same shape as for an existing target. Exactly one of target or properties must be supplied.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.targets.list(id) -> TargetObjectsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists the target objects available on a connection for use as a model sync destination.

If the connection supports creating new destinations, the `target_creation`
object will contain information on what properties are required to create the
target.

Target creation properties are all string values; the `enum` flag indicates if
the property has a fixed set of valid values. When `enum` is `true`, the [Target
Creation Property
Values](../../../../../api-reference/model-sync/targets/get-create-property)
endpoint can be used to retrieve the valid values. Alternatively, pass
`include_target_creation_values=true` to inline the `values` array for each
enum property directly in this response.

## Sync modes

The sync mode determines which records are written to the destination for a
model sync. The `modes` array for a target object defines the `id` along with
what operations the mode supports.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().targets().list(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    TargetsListRequest
        .builder()
        .includeTargetCreationValues(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**includeTargetCreationValues:** `Optional<Boolean>` — When true, inline the valid values for each enum target-creation property in the response. Skips the separate call to retrieve property values.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.targets.getCreateProperty(id, property) -> TargetPropertyValuesEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the valid values for a target-creation property on a connection that supports creating new target objects.

Connections which support creating new sync target objects (destinations) will
return `target_creation` with their [target object list](../../../../../../../api-reference/model-sync/targets/list). This endpoint
will return possible values for properties where `enum` is `true`.

If the connection does not support creating new target objects, an HTTP 404 will
be returned.

The `values` array lists the valid options (and labels) for the property. Each
member of the `values` array has a `label` and `value`. For exaample,

```json
{
  "data": [
    {
      "id": "account",
      "title": "Account ID",
      "enum": true,
      "values": [
        {
          "value": "1234567::urn:li:organization:987654",
          "label": "Polytomic Inc. (1234567)"
        }
      ]
    }
  ]
}
```

The `value` for the selected option should be passed when [creating a
sync](../../../../../../../api-reference/model-sync/create).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().targets().getCreateProperty("248df4b7-aa70-47b8-a036-33ac447e668d", "property");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**property:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## ModelSync ErrorHandling
<details><summary><code>client.modelSync.errorHandling.get(id) -> SyncErrorHandlingEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns the error handling settings for a model sync.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().errorHandling().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the model sync.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.errorHandling.update(id, request) -> SyncErrorHandlingEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates the error handling settings for a model sync.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().errorHandling().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateSyncErrorHandlingRequest
        .builder()
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` — Unique identifier of the model sync.
    
</dd>
</dl>

<dl>
<dd>

**autoRetryRecordErrors:** `Optional<Boolean>` — Whether records that fail are automatically retried on the next run. Omit to leave unchanged.
    
</dd>
</dl>

<dl>
<dd>

**notifyOnRecordErrors:** `Optional<Boolean>` — Whether subscribers are notified when individual records fail, in addition to whole-sync failures. Omit to leave unchanged.
    
</dd>
</dl>

<dl>
<dd>

**subscribers:** `Optional<List<String>>` — Email addresses notified when this sync fails. Replaces the current list; pass an empty list to unsubscribe everyone. Omit to leave the list unchanged.
    
</dd>
</dl>

<dl>
<dd>

**warningNotifications:** `Optional<Boolean>` — Whether subscribers are notified when the sync completes with warnings. Omit to leave unchanged.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## ModelSync Executions
<details><summary><code>client.modelSync.executions.list(syncId) -> ListExecutionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists executions for a model sync.

Results are ordered by start time descending. If more results are available, the
response includes `pagination.next_page_token`; pass that token back unchanged
to continue paging.

The token is opaque. Do not construct or edit it yourself.

For full details about a specific execution — including record counts and error
summaries — use
[`GET /api/syncs/{sync_id}/executions/{id}`](../../../../api-reference/model-sync/executions/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().list(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    ExecutionsListRequest
        .builder()
        .pageToken("AmkYh8v0jR5B3kls2Qcc9y8MjrPmvR4CvaK7H0F4rEwqvg76K==")
        .onlyCompleted(true)
        .ascending(true)
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**pageToken:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**onlyCompleted:** `Optional<Boolean>` 
    
</dd>
</dl>

<dl>
<dd>

**ascending:** `Optional<Boolean>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.get(syncId, id) -> GetExecutionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single model sync execution.

For the log files produced by this execution, use
[`GET /api/syncs/{sync_id}/executions/{id}/{type}`](../../../../../api-reference/model-sync/executions/get-log-urls) to retrieve
signed URLs grouped by log category.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().get("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.cancel(syncId, id) -> CancelSyncExecutionResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Requests cancellation of a model sync execution.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().cancel("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — The ID of the execution to cancel.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.getConsoleLogs(syncId, id) -> ExecutionConsoleLogsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Fetch the latest console log entries for a sync execution. Returns the most recent 50 entries.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().getConsoleLogs(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    "0ecd09c1-b901-4d27-9053-f0367c427254",
    ExecutionsGetConsoleLogsRequest
        .builder()
        .limit(50)
        .after("1744311099250-0")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**limit:** `Optional<Integer>` — Maximum number of entries to return. Values above the logger retention limit are capped to 50.
    
</dd>
</dl>

<dl>
<dd>

**after:** `Optional<String>` — Return only entries newer than this cursor.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.getLogsIndex(syncId, id) -> LogsIndexResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns an index of the record-log types produced by this model sync execution, with the per-type endpoint to retrieve signed URLs for each type's segment files.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().getLogsIndex("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` — Unique identifier of the model sync.
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` — Unique identifier of the execution whose logs are being indexed.
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.getLogUrls(syncId, id, type) -> ExecutionLogsResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns signed URLs for every log file of a given type on a model sync execution.

`{type}` identifies the log category, such as `errors` or `warnings`. The
response contains a signed URL for each log file in that category.

> 🚧 Signed URLs expire after a short period. If a URL has expired, re-request
> it from this endpoint. To fetch a single file's URL directly, use
> [`GET /api/syncs/{sync_id}/executions/{id}/{type}/{filename}`](../../../../../../api-reference/model-sync/executions/get-logs).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().getLogUrls("248df4b7-aa70-47b8-a036-33ac447e668d", "248df4b7-aa70-47b8-a036-33ac447e668d", ExecutionLogType.RECORDS);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**type:** `ExecutionLogType` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.modelSync.executions.getLogs(syncId, id, type, filename)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Redirects to a signed URL for a specific log file produced by a model sync execution.

This endpoint responds with a `302 Found` redirect; the signed URL is returned
in the `Location` header, and the response body is empty. The URL expires
after a short period, so call this endpoint again to obtain a fresh URL if it
expires before you download the file.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.modelSync().executions().getLogs("248df4b7-aa70-47b8-a036-33ac447e668d", "0ecd09c1-b901-4d27-9053-f0367c427254", ExecutionLogType.RECORDS, "file.json");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**syncId:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**type:** `ExecutionLogType` 
    
</dd>
</dl>

<dl>
<dd>

**filename:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Permissions Policies
<details><summary><code>client.permissions.policies.list() -> ListPoliciesResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all policies in the caller's organization.

Each policy binds one or more roles to a set of resources, controlling what
actions members with those roles can perform on those resources.

To inspect a specific policy in detail, use
[`GET /api/permissions/policies/{id}`](../../../api-reference/permissions/policies/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().policies().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.policies.create(request) -> PolicyResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new policy.

A policy binds one or more roles to a set of resources, granting members who
hold those roles the actions defined by them. Roles must already exist before
they are referenced in a policy; create roles using
[`POST /api/permissions/roles`](../../../api-reference/permissions/roles/create).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().policies().create(
    CreatePolicyRequest
        .builder()
        .name("Custom")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**policyActions:** `Optional<List<PolicyAction>>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.policies.get(id) -> PolicyResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single policy by ID, including all action/role bindings it defines.

Returns the full set of action/role bindings defined by the policy, including
the resources it applies to.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().policies().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.policies.update(id, request) -> PolicyResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing policy.

The update is a **full replacement** of the policy's bindings. Any role or
resource binding not included in the request body is removed. To make a
partial change, fetch the current policy with
[`GET /api/permissions/policies/{id}`](../../../../api-reference/permissions/policies/get), modify the relevant bindings,
and send the complete object back.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().policies().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdatePolicyRequest
        .builder()
        .name("Custom")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>

<dl>
<dd>

**policyActions:** `Optional<List<PolicyAction>>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.policies.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a policy.

Deletion is permanent. Any access that was granted solely through this policy
is revoked immediately for all users who depended on it.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().policies().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

## Permissions Roles
<details><summary><code>client.permissions.roles.list() -> RoleListResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Lists all permissions roles available in the caller's organization, including built-in system roles.

System roles such as Admin and Member are always present in every organization
and cannot be modified or deleted. Custom roles appear alongside them and can
be created, updated, or removed as needed.

To inspect or modify a specific role, use
[`GET /api/permissions/roles/{id}`](../../../api-reference/permissions/roles/get).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().roles().list();
```
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.roles.create(request) -> RoleResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Creates a new permissions role.

Provide a `name` for the new role. The role is immediately available for use
in permission policies.

To attach the role to resources, create or update a policy using
[`POST /api/permissions/policies`](../../../api-reference/permissions/policies/create).
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().roles().create(
    CreateRoleRequest
        .builder()
        .name("Custom")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.roles.get(id) -> RoleResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Returns a single permissions role by ID.

Returns the role's name, action set, and whether it is a built-in system role.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().roles().get("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.roles.update(id, request) -> RoleResponseEnvelope</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Updates an existing permissions role's name and action set.

The update is a **full replacement** of the role definition.

> 🚧 Built-in system roles (such as Admin and Member) cannot be updated.
> Attempting to modify a system role returns an error.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().roles().update(
    "248df4b7-aa70-47b8-a036-33ac447e668d",
    UpdateRoleRequest
        .builder()
        .name("Custom")
        .build()
);
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**name:** `String` 
    
</dd>
</dl>

<dl>
<dd>

**organizationId:** `Optional<String>` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>

<details><summary><code>client.permissions.roles.delete(id)</code></summary>
<dl>
<dd>

#### 📝 Description

<dl>
<dd>

<dl>
<dd>

Deletes a permissions role.

> 🚧 Built-in system roles (such as Admin and Member) cannot be deleted.
> Attempting to delete a system role returns an error.

Deleting a role does not automatically remove it from any policies that
reference it. Update those policies separately using
[`PUT /api/permissions/policies/{id}`](../../../../api-reference/permissions/policies/update) to avoid
leaving stale role references.
</dd>
</dl>
</dd>
</dl>

#### 🔌 Usage

<dl>
<dd>

<dl>
<dd>

```java
client.permissions().roles().delete("248df4b7-aa70-47b8-a036-33ac447e668d");
```
</dd>
</dl>
</dd>
</dl>

#### ⚙️ Parameters

<dl>
<dd>

<dl>
<dd>

**id:** `String` 
    
</dd>
</dl>
</dd>
</dl>


</dd>
</dl>
</details>