openapi: 3.0.3
info:
  title: Apache Iceberg REST Catalog 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
externalDocs:
  description: Apache Iceberg REST Catalog Specification
  url: https://iceberg.apache.org/rest-catalog-spec/
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
tags:
  - name: Configuration
    description: Catalog configuration and discovery
  - name: OAuth2
    description: OAuth2 token management
  - name: Namespaces
    description: Namespace (database/schema) management
  - name: Tables
    description: Table creation, listing, loading, and management
  - name: Views
    description: View lifecycle management
  - name: Commits
    description: Transaction commits and metadata updates
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'

  /v1/oauth/tokens:
    post:
      operationId: getToken
      summary: Get OAuth2 Token
      description: Exchange credentials for an OAuth2 access token for catalog access.
      tags:
        - OAuth2
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                    - urn:ietf:params:oauth:grant-type:token-exchange
                client_id:
                  type: string
                client_secret:
                  type: string
                scope:
                  type: string
      responses:
        '200':
          description: OAuth2 token response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'

  /v1/namespaces:
    get:
      operationId: listNamespaces
      summary: List Namespaces
      description: List all namespaces. A namespace is a container for tables, analogous to a database or schema.
      tags:
        - Namespaces
      parameters:
        - name: parent
          in: query
          description: Parent namespace (for nested namespaces)
          required: false
          schema:
            type: string
        - name: pageToken
          in: query
          required: false
          schema:
            type: string
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of namespaces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNamespacesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createNamespace
      summary: Create Namespace
      description: Create a new namespace with optional properties.
      tags:
        - Namespaces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespaceRequest'
      responses:
        '200':
          description: Namespace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNamespaceResponse'
        '409':
          $ref: '#/components/responses/Conflict'

  /v1/namespaces/{namespace}:
    get:
      operationId: loadNamespaceMetadata
      summary: Get Namespace Metadata
      description: Load metadata properties for a namespace.
      tags:
        - Namespaces
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      responses:
        '200':
          description: Namespace metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetNamespaceResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: dropNamespace
      summary: Drop Namespace
      description: Drop a namespace. The namespace must be empty.
      tags:
        - Namespaces
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      responses:
        '204':
          description: Namespace dropped
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/namespaces/{namespace}/properties:
    post:
      operationId: updateNamespaceProperties
      summary: Update Namespace Properties
      description: Set or remove namespace properties.
      tags:
        - Namespaces
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
      responses:
        '200':
          description: Properties updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateNamespacePropertiesResponse'

  /v1/namespaces/{namespace}/tables:
    get:
      operationId: listTables
      summary: List Tables
      description: List all tables in a namespace.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - name: pageToken
          in: query
          required: false
          schema:
            type: string
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: List of tables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
    post:
      operationId: createTable
      summary: Create Table
      description: Create a new Iceberg table in the given namespace.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
      responses:
        '200':
          description: Table created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadTableResult'
        '409':
          $ref: '#/components/responses/Conflict'

  /v1/namespaces/{namespace}/tables/{table}:
    get:
      operationId: loadTable
      summary: Load Table
      description: Load a table from the catalog, returning metadata and a token for updates.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - $ref: '#/components/parameters/TableParam'
        - name: snapshots
          in: query
          description: Which snapshots to return (all, refs, or none)
          required: false
          schema:
            type: string
            enum:
              - all
              - refs
      responses:
        '200':
          description: Table metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadTableResult'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: commitTable
      summary: Commit Table Update
      description: Commit a set of table requirement assertions and metadata updates atomically.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - $ref: '#/components/parameters/TableParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitTableRequest'
      responses:
        '200':
          description: Commit applied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommitTableResponse'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: dropTable
      summary: Drop Table
      description: Drop a table from the catalog. Optionally purge the data files.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - $ref: '#/components/parameters/TableParam'
        - name: purgeRequested
          in: query
          description: Whether to purge table data files
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '204':
          description: Table dropped
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/namespaces/{namespace}/tables/{table}/metrics:
    post:
      operationId: reportMetrics
      summary: Report Table Metrics
      description: Send scan metrics and commit metrics to the catalog for observability.
      tags:
        - Tables
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - $ref: '#/components/parameters/TableParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReportMetricsRequest'
      responses:
        '204':
          description: Metrics reported

  /v1/namespaces/{namespace}/views:
    get:
      operationId: listViews
      summary: List Views
      description: List all views in a namespace.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      responses:
        '200':
          description: List of views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTablesResponse'
    post:
      operationId: createView
      summary: Create View
      description: Create a new Iceberg view in the namespace.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateViewRequest'
      responses:
        '200':
          description: View created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadViewResult'

  /v1/namespaces/{namespace}/views/{view}:
    get:
      operationId: loadView
      summary: Load View
      description: Load a view from the catalog.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - name: view
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: View metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadViewResult'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: dropView
      summary: Drop View
      description: Drop a view from the catalog.
      tags:
        - Views
      parameters:
        - $ref: '#/components/parameters/NamespaceParam'
        - name: view
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: View dropped

  /v1/transactions/commit:
    post:
      operationId: commitTransaction
      summary: Commit Multi-Table Transaction
      description: Atomically commit updates to multiple tables in a single transaction.
      tags:
        - Commits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommitTransactionRequest'
      responses:
        '204':
          description: Transaction committed
        '409':
          $ref: '#/components/responses/Conflict'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth/tokens
          scopes:
            catalog: Access catalog operations

  parameters:
    NamespaceParam:
      name: namespace
      in: path
      required: true
      description: Namespace identifier (can be multi-level with ASCII unit separator)
      schema:
        type: string
    TableParam:
      name: table
      in: path
      required: true
      description: Table name
      schema:
        type: string

  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'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
    Conflict:
      description: Commit conflict or resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'

  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

    OAuthTokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        scope:
          type: string

    ListNamespacesResponse:
      type: object
      properties:
        namespaces:
          type: array
          items:
            type: array
            items:
              type: string
        next-page-token:
          type: string

    CreateNamespaceRequest:
      type: object
      required:
        - namespace
      properties:
        namespace:
          type: array
          items:
            type: string
          description: Namespace identifier parts (e.g., ["mydb"] or ["catalog", "schema"])
        properties:
          type: object
          additionalProperties:
            type: string

    CreateNamespaceResponse:
      type: object
      properties:
        namespace:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties:
            type: string

    GetNamespaceResponse:
      type: object
      properties:
        namespace:
          type: array
          items:
            type: string
        properties:
          type: object
          additionalProperties:
            type: string

    UpdateNamespacePropertiesRequest:
      type: object
      properties:
        removals:
          type: array
          items:
            type: string
        updates:
          type: object
          additionalProperties:
            type: string

    UpdateNamespacePropertiesResponse:
      type: object
      properties:
        updated:
          type: array
          items:
            type: string
        removed:
          type: array
          items:
            type: string
        missing:
          type: array
          items:
            type: string

    ListTablesResponse:
      type: object
      properties:
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/TableIdentifier'
        next-page-token:
          type: string

    TableIdentifier:
      type: object
      properties:
        namespace:
          type: array
          items:
            type: string
        name:
          type: string

    CreateTableRequest:
      type: object
      required:
        - name
        - schema
      properties:
        name:
          type: string
        location:
          type: string
        schema:
          $ref: '#/components/schemas/Schema'
        partition-spec:
          $ref: '#/components/schemas/PartitionSpec'
        write-order:
          $ref: '#/components/schemas/SortOrder'
        stage-create:
          type: boolean
        properties:
          type: object
          additionalProperties:
            type: string

    LoadTableResult:
      type: object
      properties:
        metadata-location:
          type: string
        metadata:
          $ref: '#/components/schemas/TableMetadata'
        config:
          type: object
          additionalProperties:
            type: string

    CommitTableRequest:
      type: object
      required:
        - requirements
        - updates
      properties:
        identifier:
          $ref: '#/components/schemas/TableIdentifier'
        requirements:
          type: array
          items:
            type: object
        updates:
          type: array
          items:
            type: object

    CommitTableResponse:
      type: object
      properties:
        metadata-location:
          type: string
        metadata:
          $ref: '#/components/schemas/TableMetadata'

    CommitTransactionRequest:
      type: object
      required:
        - table-changes
      properties:
        table-changes:
          type: array
          items:
            $ref: '#/components/schemas/CommitTableRequest'

    ReportMetricsRequest:
      type: object
      properties:
        report-type:
          type: string
          enum:
            - scan-report
            - commit-report
        metrics:
          type: object

    Schema:
      type: object
      properties:
        schema-id:
          type: integer
        fields:
          type: array
          items:
            $ref: '#/components/schemas/StructField'

    StructField:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
        required:
          type: boolean
        doc:
          type: string

    PartitionSpec:
      type: object
      properties:
        spec-id:
          type: integer
        fields:
          type: array
          items:
            type: object

    SortOrder:
      type: object
      properties:
        order-id:
          type: integer
        fields:
          type: array
          items:
            type: object

    TableMetadata:
      type: object
      properties:
        format-version:
          type: integer
        table-uuid:
          type: string
        location:
          type: string
        last-updated-ms:
          type: integer
          format: int64
        current-schema-id:
          type: integer
        schemas:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
        default-spec-id:
          type: integer
        partition-specs:
          type: array
          items:
            $ref: '#/components/schemas/PartitionSpec'
        current-snapshot-id:
          type: integer
          format: int64
        snapshots:
          type: array
          items:
            $ref: '#/components/schemas/Snapshot'
        properties:
          type: object
          additionalProperties:
            type: string

    Snapshot:
      type: object
      properties:
        snapshot-id:
          type: integer
          format: int64
        parent-snapshot-id:
          type: integer
          format: int64
        sequence-number:
          type: integer
          format: int64
        timestamp-ms:
          type: integer
          format: int64
        manifest-list:
          type: string
        summary:
          type: object
          properties:
            operation:
              type: string
              enum:
                - append
                - replace
                - overwrite
                - delete

    CreateViewRequest:
      type: object
      required:
        - name
        - schema
        - view-version
      properties:
        name:
          type: string
        location:
          type: string
        schema:
          $ref: '#/components/schemas/Schema'
        view-version:
          type: object
        properties:
          type: object
          additionalProperties:
            type: string

    LoadViewResult:
      type: object
      properties:
        metadata-location:
          type: string
        metadata:
          type: object

security:
  - BearerAuth: []
  - OAuth2:
      - catalog