Aleph Alpha Stages API

openapi: 3.2.0
info:
  title: PhariaData Stages API
  description: The PhariaData API provides a comprehensive suite of endpoints to manage data workflows within the Pharia Data Platform.  This API enables users to organize, store, retrieve, and manipulate datasets across repositories with efficiency and  control. Key functionalities include the creation and management of datasets, stages, and repositories, as well as  streamlined access to data through downloads and real-time data streaming.
  contact:
    name: PhariaData API Support
    url: https://aleph-alpha.atlassian.net/servicedesk/customer/portals
    email: pharia-data@aleph-alpha.com
  license:
    name: Open Aleph License
  version: 1.0.0
servers:
- url: '{host}/v1/studio/data'
  variables:
    host:
      default: https://api.pharia.example.com
security:
- Bearer: []
tags:
- name: Stages
  description: Stages serve as the data platform's entry point for data collection, where source files are securely stored, enabling subsequent transformations and dataset generation. Files can be uploaded directly into stages via the HTTP API or through connectors, which support automated and continuous synchronization with your source systems. Stages provide secure, persistent storage and act as an interface for importing and exporting data files within the platform. To improve data discoverability, comprehension, and quality for end users, the data platform offers datasets as the recommended abstraction for organizing and sharing data.
paths:
  /stages:
    get:
      tags:
      - Stages
      summary: Retrieve a list of stages
      description: Retrieves a paginated list of stages in the data platform. Optionally, filters can be applied based on stage name.
      parameters:
      - name: page
        in: query
        description: The page number to retrieve in the paginated response (starting from 0).
        schema:
          type: integer
          example: 0
      - name: size
        in: query
        description: The number of stages to include in each page of results.
        schema:
          type: integer
          example: 10
      - name: name
        in: query
        description: An optional filter to retrieve stages that match the specified name.
        schema:
          type: string
          example: My Stage
      - name: withSearchStore
        in: query
        description: Filter stages that have or don't have a search store configured.
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageListWithPagination'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
    post:
      tags:
      - Stages
      summary: Create a new stage
      description: 'Creates a new stage in the data platform with the specified name. This stage can be used to store source files for further data processing.


        **Access Policy:** By default, stages are created as private (owner-only access). Admin users can optionally create public stages by setting `accessPolicy: "public"`. Public stages grant read-only access to all authenticated users, while write access remains with the owner. Non-admin users attempting to create public stages will receive a 403 Forbidden error.'
      requestBody:
        description: The details required to create a new stage, including the name of the stage. This field is mandatory.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StageCreate'
            example:
              name: MyPublicCollection
              triggers:
              - transformationName: DocumentToText
                destinationType: DataPlatform:Repository:CREATE
                connectorType: DataPlatform:SearchStore:CREATE
                name: PDFTriggerMyStage
              retentionPolicy:
                retentionPeriod: 30
              accessPolicy: public
              searchStore:
                chunkingStrategy:
                  maxChunkSizeTokens: 500
                  chunkOverlapTokens: 250
                embeddingStrategy:
                  type: vllm
                  config:
                    model: qwen3-embedding-8b
                metadata:
                  topic: movies
                metadataSchema:
                  topic: string
                  approved: boolean
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageCreatedResponse'
              example:
                stageId: fd8b3886-c8c0-4728-8b66-7922703b1ef5
                name: MyPublicCollection
                createdAt: '2026-02-16T13:03:48Z'
                updatedAt: '2026-02-16T13:03:48Z'
                triggers:
                - transformationName: DocumentToText
                  destinationType: DataPlatform:Repository
                  connectorType: DataPlatform:SearchStore
                  name: PDFTriggerMyStage
                  repositoryId: 815f77f9-6a68-4c42-86a4-9bd603395a49
                retentionPolicy:
                  retentionPeriod: 30
                searchStore:
                  id: 41804fe6-34b2-4db6-a4b1-dcd50fa7cf6a
                  chunkingStrategy:
                    maxChunkSizeTokens: 500
                    chunkOverlapTokens: 250
                  embeddingStrategy:
                    type: vllm
                    config:
                      model: qwen3-embedding-8b
                  metadata:
                    topic: movies
                  metadataSchema:
                    topic: string
                    approved: boolean
                accessPolicy: public
                filesCount: 0
                ownerId: '316056799180494087'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '403':
          description: Forbidden - Non-admin user attempted to create a public stage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
  /stages/{stageID}:
    get:
      tags:
      - Stages
      summary: Retrieve stage details by ID
      description: Retrieves detailed information about a specific stage identified by the provided stage ID, including its name, creation date, and last updated date.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage to be deleted.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stage'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
    delete:
      tags:
      - Stages
      summary: Delete a specific stage
      description: Permanently deletes the stage identified by the specified stage ID. This action cannot be undone and will remove all associated data with the stage.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage to be deleted.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      responses:
        '204':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
    patch:
      tags:
      - Stages
      summary: Update Stage Configuration
      description: Updates a stage's configuration including triggers, access policy, and retention policy. This is a partial update operation where only the provided fields will be updated. If triggers are provided, they will completely replace the existing triggers configuration. for updating access policy users must be either admin or owner of the stage.
      parameters:
      - name: stageID
        in: path
        description: Unique identifier of the stage to update
        required: true
        schema:
          type: string
          format: uuid
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      requestBody:
        description: Stage update configuration. All fields are optional - only provided fields will be updated.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StageUpdate'
            examples:
              setRetention30Days:
                summary: Set retention to 30 days
                value:
                  retentionPolicy:
                    retentionPeriod: 30
              clearRetentionWithNull:
                summary: Clear retention (unrestricted) using null
                value:
                  retentionPolicy: null
              clearRetentionWithEmptyObject:
                summary: Clear retention (unrestricted) using empty object
                value:
                  retentionPolicy: {}
              clearRetentionWithZero:
                summary: Clear retention (unrestricted) using retentionPeriod = 0
                value:
                  retentionPolicy:
                    retentionPeriod: 0
              noChangeOmittedField:
                summary: No change (omit retentionPolicy)
                value:
                  accessPolicy: private
      responses:
        '200':
          description: Stage updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stage'
        '400':
          description: Bad Request - Invalid stage ID format or malformed request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '403':
          description: Forbidden - Insufficient permissions to update this stage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found - Stage with the specified ID does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '422':
          description: Unprocessable Entity - Invalid transformation names or unsupported destination types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred while updating the stage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
  /stages/{stageID}/runs:
    get:
      tags:
      - Stages
      summary: Retrieve a list of runs for a stage
      description: Retrieves a paginated list of runs associated with the specified stage.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage to retrieve runs for.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: page
        in: query
        description: The page number to retrieve in the paginated response (starting from 0).
        schema:
          type: integer
          example: 0
      - name: size
        in: query
        description: The number of runs to include in each page of results.
        schema:
          type: integer
          example: 10
      - name: status
        in: query
        description: The status of the runs to filter by.
        schema:
          type: string
          example: completed
      - name: transformationID
        in: query
        description: The ID of the transformation to filter by.
        schema:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunListWithPagination'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
      security:
      - Bearer: []
  /stages/{stageID}/runs/events:
    get:
      tags:
      - Stages
      summary: Stream real-time run updates for a stage
      description: 'Opens a Server-Sent Events (SSE) connection that streams live run updates for a specific stage.


        **SSE Events:**

        - `connected`: Connection established

        - `runs:new`: New runs appeared on the current page

        - `runs:updated`: Existing runs changed status

        - `runs:removed`: Runs fell off the current page window (e.g. pushed out by newer runs)

        - `done`: All currently visible runs reached a terminal state

        - `error`: Stream error occurred


        The stream closes automatically when all runs reach a terminal state or when the client disconnects.'
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage to stream runs for.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: page
        in: query
        description: The page number to retrieve in the paginated response (starting from 0).
        schema:
          type: integer
          example: 0
      - name: size
        in: query
        description: The number of runs to include in each page of results.
        schema:
          type: integer
          example: 10
      - name: status
        in: query
        description: The status of the runs to filter by.
        schema:
          type: string
          example: completed
      - name: transformationID
        in: query
        description: The ID of the transformation to filter by.
        schema:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: OK
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-Sent Events stream with real-time run updates
                example: 'event: connected

                  data: {"message":"Connected to runs stream","stageId":"..."}


                  event: runs:new

                  data: {"runs":[...],"count":1,"total":5}


                  event: runs:updated

                  data: {"runs":[...],"count":1,"total":5}


                  event: runs:removed

                  data: {"runIds":["..."],"count":1,"total":4}


                  : keepalive at 2026-01-01T00:00:00Z


                  event: done

                  data: {"message":"All runs have reached a terminal state"}

                  '
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
      security:
      - Bearer: []
  /stages/{stageID}/files:
    get:
      tags:
      - Stages
      summary: Retrieve a list of files in a stage
      description: Retrieves a paginated list of files stored in the specified stage. Filters can be applied based on file name and creation dates to refine the results.
      parameters:
      - name: page
        in: query
        description: The page number to retrieve in the paginated response (starting from 0).
        schema:
          type: integer
          example: 0
      - name: size
        in: query
        description: The number of files to include in each page of results.
        schema:
          type: integer
          example: 10
      - name: stageID
        in: path
        description: The unique identifier of the stage from which to list the files.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: name
        in: query
        description: An optional filter to retrieve files that match the specified name.
        schema:
          type: string
          example: my_file.txt
      - name: createdAfter
        in: query
        description: An optional filter to retrieve files created after the specified date (in ISO 8601 format).
        schema:
          type: string
          example: '2024-01-01'
      - name: createdBefore
        in: query
        description: An optional filter to retrieve files created before the specified date (in ISO 8601 format).
        schema:
          type: string
          example: '2024-12-31'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListWithPagination'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
    post:
      tags:
      - Stages
      summary: Create a new file in a stage
      description: Uploads a new file to the specified stage. The file's content and optional metadata (such as the file name) can be provided in the request body. When uploading a text or Markdown file to a stage with triggers, keep in mind that the file must be in UTF-8 encoding, with a LF line feed character.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage where the file will be uploaded.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - sourceData
              properties:
                sourceData:
                  type: string
                  description: The binary content of the file being uploaded.
                  format: binary
                name:
                  type: string
                  description: The name to assign to the uploaded file (optional).
                  example: my_file.txt
                ingestionContext:
                  $ref: '#/components/schemas/IngestionContext'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '413':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
  /stages/{stageID}/files/{fileID}:
    get:
      tags:
      - Stages
      summary: Retrieve the content of a specific file
      description: Fetches the content of a file identified by its unique file ID within the specified stage. This operation returns the raw data of the file.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage where the file is stored.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: fileID
        in: path
        description: The unique identifier of the file whose content is being retrieved.
        required: true
        schema:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
    put:
      tags:
      - Stages
      summary: Update an existing file in a stage
      description: Uploads a new version of the specified file identified by its unique file ID in the given stage. You can provide updated content and an optional new name for the file. Will be generated a new version of a file.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage containing the file to be updated.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: fileID
        in: path
        description: The unique identifier of the file to be updated.
        required: true
        schema:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - sourceData
              properties:
                sourceData:
                  type: string
                  description: The binary content of the file being uploaded as an update.
                  format: binary
                name:
                  type: string
                  description: An optional new name to assign to the file (if you want to rename it).
                  example: updated_file.txt
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '500':
          description: INTERNAL SERVER ERROR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
    delete:
      tags:
      - Stages
      summary: Permanently delete a specific file
      description: Deletes the file identified by its unique file ID from the specified stage. This action cannot be undone, and all associated data with the file will be permanently removed.
      parameters:
      - name: stageID
        in: path
        description: The unique identifier of the stage from which the file will be deleted.
        required: true
        schema:
          type: string
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: fileID
        in: path
        description: The unique identifier of the file to be deleted.
        required: true
        schema:
          type: string
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '204':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponseDataset'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
  /stages/{stageID}/files/{fileID}/presigned-url:
    get:
      tags:
      - Stages
      summary: Get a presigned URL for a file
      description: Generate a presigned URL for secure, time-limited access to a file. The URL can be used to download the file directly from the storage provider without requiring authentication.
      parameters:
      - name: stageID
        in: path
        description: The ID of the stage containing the file.
        required: true
        schema:
          type: string
          format: uuid
          example: cb26237c-3beb-40f3-8e13-77d862f722b5
      - name: fileID
        in: path
        description: The ID of the file to get the presigned URL for.
        required: true
        schema:
          type: string
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      - name: ttl
        in: query
        description: The time to live of the presigned URL in seconds. Default is 1800 seconds (30 minutes), maximum is 3600 seconds (1 hour).
        required: false
        schema:
          type: integer
          minimum: 60
          maximum: 3600
          default: 1800
          example: 1800
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedURL'
              examples:
                success:
                  summary: Successful presigned URL generation
                  value:
                    success: true
                    presignedUrl: https://storage.example.com/presigned-url?signature=abc123&expires=1640995200
                    ttlSeconds: 1800
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
              examples:
                invalid_ttl:
                  summary: Invalid TTL parameter
                  value:
                    error: Bad Request
                    message: TTL must be between 60 and 3600 seconds
                    statusCode: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
              examples:
                file_not_found:
                  summary: File not found
                  value:
                    error: Not Found
                    message: File with ID 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found in stage cb26237c-3beb-40f3-8e13-77d862f722b5
                    statusCode: 404
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleFailedResponse'
              examples:
                storage_error:
                  summary: Storage service error
                  value:
                    error: Internal Server Error
                    message: Failed to generate presigned URL
                    statusCode: 500
components:
  schemas:
    Stage:
      type: object
      properties:
        name:
        

# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aleph-alpha/refs/heads/main/openapi/aleph-alpha-stages-api-openapi.yml