openapi: 3.1.0
info:
  title: Snowplow Console API
  description: >-
    The Snowplow Console API provides programmatic management of the Snowplow
    behavioral data platform. Covers data structures (JSON schemas), data products
    (tracking plans), event specifications, and credentials management. All
    endpoints are scoped to an organization and require JWT bearer authentication
    obtained via the Credentials API.
  version: '1.0'
  contact:
    name: Snowplow Support
    url: https://snowplow.io/support
  termsOfService: https://snowplow.io/terms-of-service
externalDocs:
  description: Snowplow Console API Documentation (Swagger UI)
  url: https://console.snowplowanalytics.com/api/msc/v1/docs/
servers:
  - url: https://console.snowplowanalytics.com/api/msc/v1
    description: Snowplow Console API
tags:
  - name: Authentication
    description: >-
      Credentials API for obtaining JWT access tokens from API key credentials.
  - name: Data Structures
    description: >-
      Manage JSON Schema data structures (event schemas) in Snowplow. Data
      structures define the shape of events tracked in your pipeline. Supports
      versioning, validation, and deployment to dev/prod registries.
  - name: Data Products
    description: >-
      Manage data products (tracking plans) which organize event specifications
      and define the behavioral data strategy for a product or feature.
  - name: Event Specifications
    description: >-
      Event specifications define individual events within a data product,
      including their schema, triggers, and application context.
security:
  - bearerAuth: []
paths:
  /organizations/{organizationId}/credentials/v3/token:
    post:
      operationId: getAccessToken
      summary: Get Access Token
      description: >-
        Exchange API key credentials for a JWT access token. The returned token
        is used to authenticate all other Console API requests. Requires both
        X-API-Key-ID and X-API-Key headers.
      tags:
        - Authentication
      security: []
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: JWT access token returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid API key credentials
  /organizations/{organizationId}/data-structures/v1:
    get:
      operationId: listDataStructures
      summary: List Data Structures
      description: >-
        Retrieve a list of all data structures (JSON schemas) in the organization.
        Supports optional filtering by vendor and schema name.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - name: vendor
          in: query
          description: Filter by schema vendor namespace
          schema:
            type: string
        - name: name
          in: query
          description: Filter by schema name
          schema:
            type: string
      responses:
        '200':
          description: List of data structures returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataStructure'
        '401':
          description: Unauthorized - invalid or expired token
        '403':
          description: Forbidden - insufficient permissions
  /organizations/{organizationId}/data-structures/v1/{dataStructureHash}:
    get:
      operationId: getDataStructure
      summary: Get Data Structure
      description: >-
        Retrieve a specific data structure by its SHA-256 hash identifier,
        including all versions and metadata.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataStructureHash'
      responses:
        '200':
          description: Data structure retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataStructure'
        '401':
          description: Unauthorized
        '404':
          description: Data structure not found
  /organizations/{organizationId}/data-structures/v1/{dataStructureHash}/versions/{versionNumber}:
    get:
      operationId: getDataStructureVersion
      summary: Get Data Structure Version
      description: >-
        Fetch a specific version of a data structure including the full JSON
        schema for that version number.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataStructureHash'
        - name: versionNumber
          in: path
          required: true
          description: The version number (e.g., 1-0-0)
          schema:
            type: string
      responses:
        '200':
          description: Data structure version retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataStructureVersion'
        '401':
          description: Unauthorized
        '404':
          description: Version not found
  /organizations/{organizationId}/data-structures/v1/validation-requests:
    post:
      operationId: validateDataStructure
      summary: Validate Data Structure
      description: >-
        Validate that a schema is in proper JSON format and complies with
        warehouse (Redshift, Snowflake, BigQuery, Databricks) requirements
        before deployment.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidationRequest'
      responses:
        '200':
          description: Validation result returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '400':
          description: Invalid schema format
        '401':
          description: Unauthorized
  /organizations/{organizationId}/data-structures/v1/{dataStructureHash}/deployments:
    get:
      operationId: getDataStructureDeployments
      summary: Get Data Structure Deployments
      description: >-
        View the deployment history for a data structure across VALIDATED,
        DEV, and PROD environments.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataStructureHash'
      responses:
        '200':
          description: Deployment history retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Deployment'
        '401':
          description: Unauthorized
        '404':
          description: Data structure not found
  /organizations/{organizationId}/data-structures/v1/deployment-requests:
    post:
      operationId: deployDataStructure
      summary: Deploy Data Structure
      description: >-
        Deploy a data structure to a registry environment. Environments progress
        from VALIDATED → DEV → PROD. Each deployment makes the schema available
        to Snowplow pipelines in that environment.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeploymentRequest'
      responses:
        '200':
          description: Deployment request submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          description: Invalid deployment request
        '401':
          description: Unauthorized
        '409':
          description: Schema version already deployed to this environment
  /organizations/{organizationId}/data-structures/v1/{dataStructureHash}/meta:
    put:
      operationId: updateDataStructureMeta
      summary: Update Data Structure Metadata
      description: >-
        Update the metadata and customData properties for a data structure,
        such as description, owner, and custom fields.
      tags:
        - Data Structures
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataStructureHash'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataStructureMetaUpdate'
      responses:
        '200':
          description: Metadata updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataStructure'
        '400':
          description: Invalid metadata
        '401':
          description: Unauthorized
        '404':
          description: Data structure not found
  /organizations/{organizationId}/data-products/v2:
    get:
      operationId: listDataProducts
      summary: List Data Products
      description: >-
        Retrieve a comprehensive list of all data products (tracking plans)
        in the organization, including their associated event specifications.
      tags:
        - Data Products
      parameters:
        - $ref: '#/components/parameters/organizationId'
      responses:
        '200':
          description: List of data products returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DataProduct'
        '401':
          description: Unauthorized
    post:
      operationId: createDataProduct
      summary: Create Data Product
      description: >-
        Create a new data product (tracking plan) with a name and optional
        description and domain metadata.
      tags:
        - Data Products
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataProductCreate'
      responses:
        '201':
          description: Data product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
  /organizations/{organizationId}/data-products/v2/{dataProductId}:
    get:
      operationId: getDataProduct
      summary: Get Data Product
      description: >-
        Retrieve details for a specific data product including all associated
        event specifications.
      tags:
        - Data Products
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataProductId'
      responses:
        '200':
          description: Data product retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
        '401':
          description: Unauthorized
        '404':
          description: Data product not found
    post:
      operationId: updateDataProduct
      summary: Update Data Product
      description: >-
        Update an existing data product. Requires a status field in the request body.
      tags:
        - Data Products
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataProductId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataProductUpdate'
      responses:
        '200':
          description: Data product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataProduct'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '404':
          description: Data product not found
  /organizations/{organizationId}/data-products/v2/{dataProductId}/history:
    get:
      operationId: getDataProductHistory
      summary: Get Data Product History
      description: >-
        Fetch the change log for a data product with filtering options by date
        range and change type.
      tags:
        - Data Products
      parameters:
        - $ref: '#/components/parameters/organizationId'
        - $ref: '#/components/parameters/dataProductId'
      responses:
        '200':
          description: Change history retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryEntry'
        '401':
          description: Unauthorized
        '404':
          description: Data product not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the Credentials API (/credentials/v3/token)
  parameters:
    organizationId:
      name: organizationId
      in: path
      required: true
      description: The Snowplow organization UUID
      schema:
        type: string
        format: uuid
    dataStructureHash:
      name: dataStructureHash
      in: path
      required: true
      description: The SHA-256 hash identifier of the data structure
      schema:
        type: string
    dataProductId:
      name: dataProductId
      in: path
      required: true
      description: The unique identifier of the data product
      schema:
        type: string
        format: uuid
  schemas:
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT access token for authenticating Console API requests
        expiresAt:
          type: string
          format: date-time
          description: Token expiration timestamp
    DataStructure:
      type: object
      properties:
        hash:
          type: string
          description: SHA-256 hash identifier of the data structure
        vendor:
          type: string
          description: The vendor namespace for the schema (e.g., com.example)
        name:
          type: string
          description: The schema name
        format:
          type: string
          enum: [jsonschema]
          description: The schema format
        latestVersion:
          type: string
          description: The latest version number (e.g., 1-0-2)
        deployments:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'
        meta:
          type: object
          properties:
            description:
              type: string
            owner:
              type: string
            customData:
              type: object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DataStructureVersion:
      type: object
      properties:
        hash:
          type: string
        version:
          type: string
          description: Version number in format major-minor-patch (e.g., 1-0-0)
        schema:
          type: object
          description: The full JSON Schema definition for this version
        deployedEnvironments:
          type: array
          items:
            type: string
            enum: [VALIDATED, DEV, PROD]
    ValidationRequest:
      type: object
      required:
        - meta
        - data
      properties:
        meta:
          type: object
          properties:
            vendor:
              type: string
            name:
              type: string
            format:
              type: string
            version:
              type: string
        data:
          type: object
          description: The JSON Schema to validate
    ValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              location:
                type: string
    Deployment:
      type: object
      properties:
        version:
          type: string
        environment:
          type: string
          enum: [VALIDATED, DEV, PROD]
        deployedAt:
          type: string
          format: date-time
        deployedBy:
          type: string
    DeploymentRequest:
      type: object
      required:
        - dataStructureHash
        - version
        - target
      properties:
        dataStructureHash:
          type: string
        version:
          type: string
        target:
          type: string
          enum: [VALIDATED, DEV, PROD]
    DataStructureMetaUpdate:
      type: object
      properties:
        description:
          type: string
        owner:
          type: string
        customData:
          type: object
    DataProduct:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [active, draft, deprecated]
        domain:
          type: string
        eventSpecificationCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    DataProductCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        domain:
          type: string
    DataProductUpdate:
      type: object
      required:
        - status
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [active, draft, deprecated]
    HistoryEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        user:
          type: string
        changeType:
          type: string
        description:
          type: string