openapi: 3.0.3
info:
  title: Apache Iceberg REST Catalog Commits Configuration API
  description: The Apache Iceberg REST Catalog API is an open standard (OpenAPI spec) for interacting with Apache Iceberg table catalogs. It provides a common HTTP interface for catalog operations including namespace management, table lifecycle, view management, and metadata operations. Multiple catalog implementations support this specification including Apache Polaris, Project Nessie, AWS Glue, and Google BigLake.
  version: 0.0.1
  contact:
    name: Apache Iceberg Community
    url: https://iceberg.apache.org/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{catalog-host}
  description: Iceberg REST Catalog endpoint
  variables:
    catalog-host:
      default: localhost:8181
      description: Hostname and port of the Iceberg REST catalog service
security:
- BearerAuth: []
- OAuth2:
  - catalog
tags:
- name: Configuration
  description: Catalog configuration and discovery
paths:
  /v1/config:
    get:
      operationId: getConfig
      summary: Get Catalog Configuration
      description: Returns configuration properties for the catalog and default table properties, plus catalog-level overrides. Used during client initialization to discover catalog configuration.
      tags:
      - Configuration
      parameters:
      - name: warehouse
        in: query
        description: Warehouse identifier for multi-tenant catalogs
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Catalog configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    IcebergErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: integer
    CatalogConfig:
      type: object
      properties:
        defaults:
          type: object
          additionalProperties:
            type: string
          description: Default configuration for tables
        overrides:
          type: object
          additionalProperties:
            type: string
          description: Catalog-level overrides
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth/tokens
          scopes:
            catalog: Access catalog operations
externalDocs:
  description: Apache Iceberg REST Catalog Specification
  url: https://iceberg.apache.org/rest-catalog-spec/