Tower Catalogs API

openapi: 3.1.0
info:
  contact:
    email: hello@tower.dev
    name: Tower Computing GmbH
    url: https://tower.dev
  description: REST API to interact with Tower Services.
  termsOfService: https://tower.dev/terms
  title: Tower Accounts Catalogs API
  version: v0.11.16
servers:
- url: https://api.tower.dev/v1
tags:
- name: Catalogs
paths:
  /catalogs:
    get:
      description: Lists all the catalogs associated with your current account.
      operationId: list-catalogs
      parameters:
      - description: The page number to fetch.
        explode: false
        in: query
        name: page
        schema:
          default: 1
          description: The page number to fetch.
          format: int64
          type: integer
      - description: The number of records to fetch on each page.
        explode: false
        in: query
        name: page_size
        schema:
          default: 20
          description: The number of records to fetch on each page.
          format: int64
          type: integer
      - description: The environment to filter by. When omitted, catalogs across all environments are returned.
        explode: false
        in: query
        name: environment
        schema:
          description: The environment to filter by. When omitted, catalogs across all environments are returned.
          type: string
      - description: Whether to fetch all catalogs across all environments or only for the current environment.
        explode: false
        in: query
        name: all
        schema:
          description: Whether to fetch all catalogs across all environments or only for the current environment.
          type: boolean
      - description: Filter catalogs by type, e.g. "tower-catalog". When omitted, all catalog types are returned.
        explode: false
        in: query
        name: type
        schema:
          description: Filter catalogs by type, e.g. "tower-catalog". When omitted, all catalog types are returned.
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCatalogsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:read
      - APIKeyAuth:
        - catalogs:read
      summary: List catalogs
      tags:
      - Catalogs
    post:
      description: Create a new catalog object in the currently authenticated account.
      operationId: create-catalog
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCatalogParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCatalogResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:read
      - APIKeyAuth:
        - catalogs:read
      summary: Create catalog
      tags:
      - Catalogs
  /catalogs/export:
    post:
      description: Lists all the catalogs in your current account and re-encrypt them with the public key you supplied.
      operationId: export-catalogs
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportCatalogsParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportCatalogsResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:export
      - APIKeyAuth:
        - catalogs:export
      summary: Export catalogs
      tags:
      - Catalogs
  /catalogs/{name}:
    delete:
      description: Delete a new catalog object in the currently authenticated account.
      operationId: delete-catalog
      parameters:
      - description: The name of the catalog to update.
        in: path
        name: name
        required: true
        schema:
          description: The name of the catalog to update.
          type: string
      - description: The environment of the catalog to delete.
        explode: false
        in: query
        name: environment
        schema:
          default: default
          description: The environment of the catalog to delete.
          type: string
      responses:
        '204':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCatalogResponse'
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:delete
      - APIKeyAuth:
        - catalogs:delete
      summary: Delete catalog
      tags:
      - Catalogs
    get:
      description: Returns details for a specific catalog, including its property names and previews.
      operationId: describe-catalog
      parameters:
      - description: The name of the catalog.
        in: path
        name: name
        required: true
        schema:
          description: The name of the catalog.
          type: string
      - description: The environment of the catalog.
        explode: false
        in: query
        name: environment
        schema:
          default: default
          description: The environment of the catalog.
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeCatalogResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:read
      - APIKeyAuth:
        - catalogs:read
      summary: Describe catalog
      tags:
      - Catalogs
    put:
      description: Update a new catalog object in the currently authenticated account.
      operationId: update-catalog
      parameters:
      - description: The name of the catalog to update.
        in: path
        name: name
        required: true
        schema:
          description: The name of the catalog to update.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCatalogParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCatalogResponse'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - AccessTokenAuth:
        - catalogs:update
      - APIKeyAuth:
        - catalogs:update
      summary: Update catalog
      tags:
      - Catalogs
  /catalogs/{name}/credentials:
    post:
      description: 'Mints a short-lived OAuth bearer token for browser or SDK access to a managed (tower-catalog) catalog. Defaults to read-only (`mode: "read"`); pass `mode: "read-write"` in the body (requires the catalogs:data:write scope) for a token bound to the read-write principal. Team membership is enforced before vending; the master Polaris credentials never leave Tower.'
      operationId: vend-catalog-credentials
      parameters:
      - description: The name of the catalog.
        in: path
        name: name
        required: true
        schema:
          description: The name of the catalog.
          type: string
      - description: The environment of the catalog.
        explode: false
        in: query
        name: environment
        schema:
          default: default
          description: The environment of the catalog.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VendCatalogCredentialsBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendCatalogCredentialsResponse'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      security:
      - AccessTokenAuth:
        - catalogs:read
      - APIKeyAuth:
        - catalogs:read
      summary: Vend catalog credentials
      tags:
      - Catalogs
components:
  schemas:
    CatalogProperty:
      additionalProperties: false
      properties:
        environment_variable:
          description: The environment variable name this property is injected as at runtime.
          type: string
        name:
          type: string
        preview:
          type: string
      required:
      - name
      - preview
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    Catalog:
      additionalProperties: false
      properties:
        CreatedAt:
          format: date-time
          type: string
        environment:
          type: string
        name:
          type: string
        properties:
          items:
            $ref: '#/components/schemas/CatalogProperty'
          type: array
        slug:
          deprecated: true
          description: This property is deprecated. Use name instead.
          type: string
        type:
          type: string
      required:
      - type
      - name
      - environment
      - properties
      - CreatedAt
      type: object
    Pagination:
      additionalProperties: false
      properties:
        num_pages:
          format: int64
          type: integer
        page:
          format: int64
          type: integer
        page_size:
          format: int64
          type: integer
        total:
          format: int64
          type: integer
      required:
      - page
      - total
      - num_pages
      - page_size
      type: object
    ExportCatalogsParams:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/ExportCatalogsParams.json
          format: uri
          readOnly: true
          type: string
        all:
          default: false
          description: Whether to fetch all catalogs or only the ones in the supplied environment.
          type: boolean
        environment:
          default: default
          description: The environment to filter by.
          type: string
        page:
          default: 1
          description: The page number to fetch.
          format: int64
          type: integer
        page_size:
          default: 20
          description: The number of records to fetch on each page.
          format: int64
          type: integer
        public_key:
          description: The PEM-encoded public key you want to use to encrypt sensitive catalog properties.
          type: string
      required:
      - public_key
      - environment
      - all
      - page
      - page_size
      type: object
    CreateCatalogParams:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/CreateCatalogParams.json
          format: uri
          readOnly: true
          type: string
        environment:
          type: string
        name:
          type: string
        properties:
          items:
            $ref: '#/components/schemas/EncryptedCatalogProperty'
          type: array
        type:
          enum:
          - snowflake-open-catalog
          - apache-polaris
          - cloudflare-r2-catalog
          - lakekeeper
          - tower-catalog
          - s3-tables
          type: string
      required:
      - name
      - type
      - environment
      - properties
      type: object
    ExportedCatalogProperty:
      additionalProperties: false
      properties:
        encrypted_value:
          type: string
        environment_variable:
          description: The environment variable name this property is injected as at runtime.
          type: string
        name:
          type: string
        preview:
          type: string
      required:
      - name
      - encrypted_value
      - preview
      type: object
    ExportedCatalog:
      additionalProperties: false
      properties:
        CreatedAt:
          format: date-time
          type: string
        environment:
          type: string
        name:
          type: string
        properties:
          items:
            $ref: '#/components/schemas/ExportedCatalogProperty'
          type: array
        slug:
          deprecated: true
          description: This property is deprecated. Use name instead.
          type: string
        type:
          type: string
      required:
      - type
      - name
      - environment
      - properties
      - CreatedAt
      type: object
    DeleteCatalogResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/DeleteCatalogResponse.json
          format: uri
          readOnly: true
          type: string
        catalog:
          $ref: '#/components/schemas/Catalog'
      required:
      - catalog
      type: object
    DescribeCatalogResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/DescribeCatalogResponse.json
          format: uri
          readOnly: true
          type: string
        catalog:
          $ref: '#/components/schemas/Catalog'
      required:
      - catalog
      type: object
    UpdateCatalogResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/UpdateCatalogResponse.json
          format: uri
          readOnly: true
          type: string
        catalog:
          $ref: '#/components/schemas/Catalog'
      required:
      - catalog
      type: object
    VendCatalogCredentialsBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/VendCatalogCredentialsBody.json
          format: uri
          readOnly: true
          type: string
        mode:
          default: read
          description: Access level for the vended token. "read" (default) binds the token to the catalog's read-only principal; "read-write" requires the catalogs:data:write scope and binds it to the read-write principal.
          enum:
          - read
          - read-write
          type: string
      type: object
    CatalogCredentials:
      additionalProperties: false
      properties:
        catalog_uri:
          description: The Iceberg REST catalog endpoint.
          type: string
        expires_at:
          description: When the OAuth token expires.
          format: date-time
          type: string
        mode:
          description: Access level the token is bound to.
          type: string
        oauth_token:
          description: Short-lived OAuth bearer token.
          type: string
        warehouse:
          description: The Polaris catalog identifier (REST prefix).
          type: string
      required:
      - catalog_uri
      - warehouse
      - oauth_token
      - expires_at
      - mode
      type: object
    ListCatalogsResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/ListCatalogsResponse.json
          format: uri
          readOnly: true
          type: string
        catalogs:
          items:
            $ref: '#/components/schemas/Catalog'
          type: array
        pages:
          $ref: '#/components/schemas/Pagination'
      required:
      - pages
      - catalogs
      type: object
    VendCatalogCredentialsResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/VendCatalogCredentialsResponse.json
          format: uri
          readOnly: true
          type: string
        credentials:
          $ref: '#/components/schemas/CatalogCredentials'
      required:
      - credentials
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    ExportCatalogsResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/ExportCatalogsResponse.json
          format: uri
          readOnly: true
          type: string
        catalogs:
          items:
            $ref: '#/components/schemas/ExportedCatalog'
          type: array
        pages:
          $ref: '#/components/schemas/Pagination'
      required:
      - pages
      - catalogs
      type: object
    CreateCatalogResponse:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/CreateCatalogResponse.json
          format: uri
          readOnly: true
          type: string
        catalog:
          $ref: '#/components/schemas/Catalog'
      required:
      - catalog
      type: object
    UpdateCatalogParams:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://api.tower.dev/v1/schemas/UpdateCatalogParams.json
          format: uri
          readOnly: true
          type: string
        environment:
          description: New environment for the catalog
          type: string
        properties:
          items:
            $ref: '#/components/schemas/EncryptedCatalogProperty'
          type: array
      required:
      - environment
      - properties
      type: object
    EncryptedCatalogProperty:
      additionalProperties: false
      properties:
        encrypted_value:
          type: string
        name:
          type: string
        preview:
          type: string
      required:
      - name
      - encrypted_value
      - preview
      type: object
  securitySchemes:
    APIKeyAuth:
      description: API key created by a Tower user or Tower service account to authenticate an API request.
      in: header
      name: X-API-Key
      type: apiKey
    AccessTokenAuth:
      description: Access token authentication scheme which uses an access token provided by the Tower API as part of a Tower session (see documentation about creating sessions).
      scheme: Bearer
      type: http