openapi: 3.0.3
info:
  title: Hex Cells Semantic (projects|models) API
  version: 1.0.0
  description: API specification for the Hex External API
  license:
    name: UNLICENSED
  contact: {}
servers:
- url: https://app.hex.tech/api
security:
- bearerAuth: []
tags:
- name: Semantic (projects|models)
paths:
  /v1/semantic-(projects|models)/{semanticProjectId}/ingest:
    post:
      operationId: IngestSemanticProject
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticProjectsSyncResponsePayload'
        '400':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/TsoaErrorResponsePayload'
                - properties:
                    problems:
                      items:
                        $ref: '#/components/schemas/HexSLProblemWithDisplay'
                      type: array
                  type: object
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '415':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '502':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      description: 'Ingest a semantic project from a zip file.


        This API endpoint is subject to a maximum of 3 requests per minute.'
      parameters:
      - in: path
        name: semanticProjectId
        required: true
        schema:
          $ref: '#/components/schemas/SemanticProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                verbose:
                  type: boolean
                  description: Whether to respond with detail on which components of the semantic layer were successfully synced
                  default: true
                debug:
                  type: boolean
                  description: Whether to include additional debug information
                  default: false
                dryRun:
                  type: boolean
                  description: If enabled, the sync will not actually write to the database
              type: object
      tags:
      - Semantic (projects|models)
  /v1/semantic-(projects|models)/{semanticProjectId}:
    patch:
      operationId: UpdateSemanticProject
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSemanticProjectResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Omit_TsoaErrorResponsePayload.details_'
                - properties:
                    details:
                      items:
                        $ref: '#/components/schemas/UpdateStatusErrorDetail'
                      type: array
                  type: object
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '404':
          description: ''
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Omit_TsoaErrorResponsePayload.details_'
                - properties:
                    details:
                      items:
                        $ref: '#/components/schemas/UpdateStatusErrorDetail'
                      type: array
                  type: object
      description: 'Use this endpoint to add or remove a status (including endorsements) from datasets and views within a semantic project


        This endpoint uses atomic semantics - if any update in the batch fails validation,

        the entire request fails and no changes are applied.'
      parameters:
      - in: path
        name: semanticProjectId
        required: true
        schema:
          $ref: '#/components/schemas/SemanticProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSemanticProjectRequest'
      tags:
      - Semantic (projects|models)
components:
  schemas:
    MetricflowModelSchemas:
      $ref: '#/components/schemas/Record_string.Record_string.HexSLTypes.DataType__'
    UpdateSemanticProjectResponse:
      description: Response body for successful status updates
      properties:
        updated:
          properties:
            views:
              items:
                properties:
                  status:
                    type: string
                    nullable: true
                  name:
                    type: string
                required:
                - status
                - name
                type: object
              type: array
            datasets:
              items:
                properties:
                  status:
                    type: string
                    nullable: true
                  name:
                    type: string
                required:
                - status
                - name
                type: object
              type: array
          required:
          - views
          - datasets
          type: object
      required:
      - updated
      type: object
      additionalProperties: false
    HexSLTypes.PublicProblem:
      description: A problem encountered during the import of a public HexSL project.
      properties:
        severity:
          $ref: '#/components/schemas/ProblemSeverity'
        message:
          $ref: '#/components/schemas/ProblemMessage'
        cause_paths:
          items:
            $ref: '#/components/schemas/ProblemKeyPath'
          type: array
        impact_paths:
          items:
            $ref: '#/components/schemas/ProblemKeyPath'
          type: array
        validated_by_json_schema:
          type: boolean
      required:
      - severity
      - message
      - cause_paths
      - impact_paths
      type: object
      additionalProperties: false
    Pick_TsoaErrorResponsePayload.Exclude_keyofTsoaErrorResponsePayload.details__:
      properties:
        reason:
          type: string
        traceId:
          $ref: '#/components/schemas/TraceId'
      required:
      - reason
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    UpdateStatusErrorDetail:
      description: Details about a failed update
      properties:
        name:
          type: string
          description: The name of the dataset or view
        type:
          type: string
          enum:
          - DATASET
          - VIEW
          description: The type of object
        reason:
          type: string
          enum:
          - not_found
          - invalid_status
          description: The reason for the failure
        value:
          type: string
          description: The invalid value (for invalid_status errors)
      required:
      - name
      - type
      - reason
      type: object
      additionalProperties: false
    TsoaErrorResponsePayload:
      properties:
        details:
          type: string
        traceId:
          $ref: '#/components/schemas/TraceId'
        reason:
          type: string
      required:
      - reason
      type: object
    SemanticProjectsSyncResponsePayload:
      properties:
        traceId:
          type: string
        contents:
          items:
            type: string
          type: array
        warnings:
          items:
            type: string
          type: array
        skipped:
          properties: {}
          additionalProperties: {}
          type: object
        problems:
          items:
            $ref: '#/components/schemas/HexSLProblemWithDisplay'
          type: array
        debug:
          properties:
            metricflowModelSchemas:
              $ref: '#/components/schemas/MetricflowModelSchemas'
          type: object
      required:
      - traceId
      - contents
      type: object
      additionalProperties: false
    HexSLProblemWithDisplay:
      allOf:
      - $ref: '#/components/schemas/HexSLTypes.PublicProblem'
      - properties:
          display:
            type: string
        required:
        - display
        type: object
    ProblemSeverity:
      type: string
      enum:
      - fatal
      - error
      - warning
    ProblemKeyPath:
      items:
        anyOf:
        - type: string
        - type: number
          format: double
      type: array
    Record_string.Record_string.HexSLTypes.DataType__:
      properties: {}
      type: object
      description: Construct a type with a set of properties K of type T
    SemanticProjectId:
      type: string
      format: uuid
      description: 'Unique ID for a Hex semantic project. This can be found from the semantic

        projects admin panel (in Settings).'
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    TraceId:
      type: string
      description: A unique identifier for this API request. The Hex Support team may request this value when debugging an issue.
    Omit_TsoaErrorResponsePayload.details_:
      $ref: '#/components/schemas/Pick_TsoaErrorResponsePayload.Exclude_keyofTsoaErrorResponsePayload.details__'
      description: Construct a type with the properties of T except for those in type K.
    SemanticObjectUpdate:
      description: 'A single update for a semantic object (dataset or view)

        Currently, only status updates are supported.'
      properties:
        type:
          type: string
          enum:
          - DATASET
          - VIEW
          description: The type of object to update
        name:
          type: string
          description: The name of the dataset or view
        status:
          type: string
          nullable: true
          description: The status name to apply, or null to remove the current status
      required:
      - type
      - name
      - status
      type: object
      additionalProperties: false
    UpdateSemanticProjectRequest:
      description: 'Request body for updating semantic datasets and views

        Currently, only status updates are supported.'
      properties:
        updates:
          items:
            $ref: '#/components/schemas/SemanticObjectUpdate'
          type: array
          description: Array of updates to apply
      required:
      - updates
      type: object
      additionalProperties: false
    ProblemMessage:
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer