---
title: "Describe Harbor Action"
method: GET
path: "/api/harbors/{harbor_id}/actions/describe"
tags: ["Harbors"]
---

# Describe Harbor Action

`GET /api/harbors/{harbor_id}/actions/describe`

## Request

- Base URL: `https://app.polytomic.com`
- URL: `https://app.polytomic.com/api/harbors/{harbor_id}/actions/describe`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

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`.

## Path parameters

- `harbor_id` string, uuid, required: Unique identifier of the Harbor

## Query parameters

- `connection_id` string, uuid, required: Connection ID of the action
- `schema_id` string, required: Schema ID of the action
- `operation_id` string, required: Operation ID of the action

## Headers

- `X-Polytomic-Version` string
- `X-Polytomic-Harbor-Session` string: Harbor session token; when supplied, the session must be active and bound to this credential and Harbor.
- `X-Polytomic-Activity-Request-ID` string: New nonzero UUID for each request, required for scoped credentials; a reused value is rejected.

## Response `200`

OK

- HarborActionDescribeEnvelope
  - `data` HarborActionCapability
    - `description` string: Description of the operation
    - `effect` string: Whether the operation only reads records (read_only) or changes them (mutating)
    - `idempotency` SchemaOperationIdempotency, nullable
      - `retention_ns` integer
      - `scope` string: Where idempotency keys must be unique
    - `input_fields` HarborActionField[], nullable: Fields the operation accepts as input
      - `definition` 'binary' | 'boolean' | 'date' | 'datetime' | 'datetime_tz' | 'time' | 'number' | 'string' | 'smallint' | 'int' | 'bigint' | 'single' | 'double': Detailed field type: a type name such as "bigint", or an array naming a complex type followed by its details, such as ["decimal", {"precision": 10, "scale": 2}] or ["array", "string"].
      - `description` string: Description of the field
      - `id` string: Field ID
      - `max_bytes` integer: Maximum length of a string value in bytes
      - `name` string: Display name of the field
      - `non_blank` boolean: Whether a string value must contain a non-whitespace character
      - `nullable` boolean: Whether the field accepts null
      - `pattern` string: Regular expression a string value must match
      - `required` boolean: Whether input must include the field
      - `type` 'unknown' | 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'object' | 'binary'
      - `values` CompletionValue[]: Known values for the field; not enforced on input
        - `depends_on` object: Field IDs and values that must all match for this option to apply
        - `label` string, nullable: Display label of the option
        - `path` string, nullable: Dot-separated position of the option in a hierarchy
        - `value` unknown
    - `lookup_fields` HarborActionField[], nullable: Fields that can identify the record to act on
      - `definition` 'binary' | 'boolean' | 'date' | 'datetime' | 'datetime_tz' | 'time' | 'number' | 'string' | 'smallint' | 'int' | 'bigint' | 'single' | 'double': Detailed field type: a type name such as "bigint", or an array naming a complex type followed by its details, such as ["decimal", {"precision": 10, "scale": 2}] or ["array", "string"].
      - `description` string: Description of the field
      - `id` string: Field ID
      - `max_bytes` integer: Maximum length of a string value in bytes
      - `name` string: Display name of the field
      - `non_blank` boolean: Whether a string value must contain a non-whitespace character
      - `nullable` boolean: Whether the field accepts null
      - `pattern` string: Regular expression a string value must match
      - `required` boolean: Whether input must include the field
      - `type` 'unknown' | 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'object' | 'binary'
      - `values` CompletionValue[]: Known values for the field; not enforced on input
        - `depends_on` object: Field IDs and values that must all match for this option to apply
        - `label` string, nullable: Display label of the option
        - `path` string, nullable: Dot-separated position of the option in a hierarchy
        - `value` unknown
    - `name` string: Display name of the operation
    - `operation_id` string: Operation ID
    - `output_fields` HarborActionField[], nullable: Fields the operation returns
      - `definition` 'binary' | 'boolean' | 'date' | 'datetime' | 'datetime_tz' | 'time' | 'number' | 'string' | 'smallint' | 'int' | 'bigint' | 'single' | 'double': Detailed field type: a type name such as "bigint", or an array naming a complex type followed by its details, such as ["decimal", {"precision": 10, "scale": 2}] or ["array", "string"].
      - `description` string: Description of the field
      - `id` string: Field ID
      - `max_bytes` integer: Maximum length of a string value in bytes
      - `name` string: Display name of the field
      - `non_blank` boolean: Whether a string value must contain a non-whitespace character
      - `nullable` boolean: Whether the field accepts null
      - `pattern` string: Regular expression a string value must match
      - `required` boolean: Whether input must include the field
      - `type` 'unknown' | 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'object' | 'binary'
      - `values` CompletionValue[]: Known values for the field; not enforced on input
        - `depends_on` object: Field IDs and values that must all match for this option to apply
        - `label` string, nullable: Display label of the option
        - `path` string, nullable: Dot-separated position of the option in a hierarchy
        - `value` unknown
    - `schema_id` string: Schema ID

## Changes

- **2026-10-26** `88f76140d899`: 2 breaking, 2 warning, 1 info
  - the response property `data/allOf[#/components/schemas/HarborActionCapability]/idempotency` became nullable for the status `200`
  - the `data/allOf[#/components/schemas/HarborActionCapability]/idempotency` response's property type changed from `object` to no type for status `200`
  - removed the optional property `data/allOf[#/components/schemas/HarborActionCapability]/idempotency/retention_ns` from the response with the `200` status
  - removed the optional property `data/allOf[#/components/schemas/HarborActionCapability]/idempotency/scope` from the response with the `200` status
  - …1 more
- **2026-10-22** `d80b0fdea14e`: 1 breaking, 9 warning, 1 info
  - the `data` response's property type changed from `object` to no type for status `200`
  - removed the optional property `data/description` from the response with the `200` status
  - removed the optional property `data/effect` from the response with the `200` status
  - removed the optional property `data/idempotency` from the response with the `200` status
  - …7 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/harbors/:harbor_id/actions/describe/get.md)

---

[API](https://skmtc.dev/polytomic/apis/polytomic-api.md) - [All operations](https://skmtc.dev/polytomic/apis/polytomic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/polytomic/apis/polytomic-api/revisions/3c88180d2470?raw)