API ReferenceDocumentation
Documentation

AI Services and Artifact Registry API Reference

OpenAPI specifications for the AI Services Installation API, Inference API, and Artifact Registry API.

This page provides the OpenAPI specifications for the following independently versioned APIs:

  • AI Services Installation API — Endpoints for programmatically installing, listing, and uninstalling Scientific AI Workflows. Served behind the /ai-platform/v1 route prefix.
  • AI Services Inference API — Endpoints for running synchronous (online) and asynchronous (offline) inferences on installed Scientific AI Workflows. Served behind the /ai-platform/v1 route prefix.
  • Artifact Registry API — Endpoints for managing the artifact registry, versions, and review workflows. Served behind the /sphere route prefix.
📘

NOTE

For more information about how to use these APIs, see the version-specific user guides:

AI Services Installation API

openapi: 3.0.3
info:
  title: TetraScience AI Services Installation API (v1.0.x)
  version: 1.0.2
  description: 'API for installing, listing, and uninstalling AI workflows for your organization.


    ## Authentication

    - All endpoints require a ts-auth-token header.

    - Installation endpoints require one of the following roles: orgAdmin, tenantAdmin, or machineLearningEngineer.


    ## Base URL

    All endpoints are served behind /ai-platform/v1.'
servers:
- url: https://gateway.tetrascience.com/ai-platform/v1
  description: TetraScience AWS API Gateway (US MT)
tags:
- name: AI Workflow Installation
  description: 'Install, list, and remove AI workflows for your organization.

    Use these endpoints to manage which AI workflows are available in your TetraSphere environment.

    '
paths:
  /install:
    post:
      tags:
      - AI Workflow Installation
      summary: Install an AI workflow
      description: 'Installs an AI workflow and makes it available to your organization.

        Use force=true to reinstall an AI workflow that is already installed.

        '
      operationId: installAiWorkflow
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - name: force
        in: query
        required: false
        schema:
          type: boolean
        description: When true, reinstalls the AI workflow even if it is already installed. Defaults to false.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - slug
              - type
              - version
              properties:
                slug:
                  type: string
                  minLength: 3
                  maxLength: 100
                  description: The unique identifier for the AI workflow (for example, cell-analysis).
                  example: cell-analysis
                type:
                  type: string
                  description: The type of artifact to install. Currently only ai-workflow is supported.
                  example: ai-workflow
                version:
                  type: string
                  description: The version to install. Must include a leading v (for example, v1.0.0).
                  pattern: ^v\d+\.\d+\.\d+(-[a-zA-Z0-9_.-]+)?$
                  example: v1.0.0
                namespace:
                  type: string
                  description: Artifact namespace. Use common for shared artifacts. Defaults to common if omitted.
                  default: common
                  example: common
                description:
                  type: string
                  description: A text description of the AI workflow.
                  example: Cell analysis AI workflow
                config:
                  type: object
                  description: Optional configuration overrides for the AI workflow.
            examples:
              install-workflow:
                summary: Install a shared AI workflow
                value:
                  slug: cell-analysis
                  type: ai-workflow
                  version: v1.0.0
                  namespace: common
                  description: Cell analysis AI workflow
      responses:
        '201':
          description: AI workflow installed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  installationRequestId:
                    type: string
                    description: Unique identifier for this installation request. Use this ID to track the installation status.
                    example: req-abc123
                  slug:
                    type: string
                    example: cell-analysis
                  version:
                    type: string
                    example: v1.0.0
                  namespace:
                    type: string
                    example: common
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: The AI workflow is already installed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 409
                message: Installation 'cell-analysis' already exists
                error: Conflict
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags:
      - AI Workflow Installation
      summary: List AI workflow installations
      description: Returns all AI workflow installations for your organization, optionally filtered by status.
      operationId: listAiWorkflowInstallations
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - name: type
        in: query
        required: true
        schema:
          type: string
        description: The type of artifact to list. Currently only ai-workflow is supported.
        example: ai-workflow
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - processing
          - completed
          - failed
        description: Filter results by installation status.
      responses:
        '200':
          description: Installations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  installations:
                    type: array
                    items:
                      $ref: '#/components/schemas/InstallationRecord'
                  count:
                    type: integer
                    description: Total number of installations returned.
                    example: 3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /install/{slug}:
    get:
      tags:
      - AI Workflow Installation
      summary: Get an AI workflow installation
      description: 'Returns details for a specific AI workflow installation.

        When version is omitted, returns the latest installed version.

        '
      operationId: getAiWorkflowInstallation
      security:
      - tsAuthToken: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the AI workflow (for example, cell-analysis).
        example: cell-analysis
      - $ref: '#/components/parameters/OrgSlugHeader'
      - name: type
        in: query
        required: true
        schema:
          type: string
        description: The type of artifact. Currently only ai-workflow is supported.
        example: ai-workflow
      - $ref: '#/components/parameters/NamespaceQuery'
      - name: version
        in: query
        required: false
        schema:
          type: string
        description: Return a specific installed version. Must include a leading v (for example, v1.0.0). When omitted, returns
          the latest installed version.
        example: v1.0.0
      responses:
        '200':
          description: Installation retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallationRecord'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags:
      - AI Workflow Installation
      summary: Uninstall an AI workflow
      description: 'Removes the specified AI workflow version from your organization.

        When version is omitted, removes the latest installed version.

        '
      operationId: uninstallAiWorkflow
      security:
      - tsAuthToken: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
        description: The unique identifier for the AI workflow (for example, cell-analysis).
        example: cell-analysis
      - $ref: '#/components/parameters/OrgSlugHeader'
      - name: type
        in: query
        required: true
        schema:
          type: string
        description: The type of artifact. Currently only ai-workflow is supported.
        example: ai-workflow
      - $ref: '#/components/parameters/NamespaceQuery'
      - name: version
        in: query
        required: false
        schema:
          type: string
        description: The version to remove. Must include a leading v (for example, v1.0.0). When omitted, removes the latest
          installed version.
        example: v1.0.0
      responses:
        '200':
          description: AI workflow uninstalled successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Access revoked successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  securitySchemes:
    tsAuthToken:
      type: apiKey
      in: header
      name: ts-auth-token
      description: TetraScience authentication token. Include this header in all API requests. To obtain a token, see the
        Authentication guide.
  parameters:
    OrgSlugHeader:
      name: x-org-slug
      in: header
      required: true
      description: Your organization's unique identifier (for example, acme-corp). Find this in the TDP URL or organization
        settings.
      schema:
        type: string
      example: acme-corp
    NamespaceQuery:
      name: namespace
      in: query
      required: false
      description: Artifact namespace. Use common for shared artifacts. When omitted, returns artifacts from all namespaces
        allowed for the organization.
      schema:
        type: string
      example: common
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: '''x-org-slug'' header is required'
            error: Bad Request
    Unauthorized:
      description: Authentication failed or credentials were not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 401
            message: ts-auth-token header is required
            error: Unauthorized
    Forbidden:
      description: Authenticated caller lacks the required policy for the organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 403
            message: 'Insufficient permissions: requires one of [orgAdmin, tenantAdmin, machineLearningEngineer] for org ''acme-corp'''
            error: Forbidden
    NotFound:
      description: Requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: Artifact with key cell-analysis not found in organization acme-corp
            error: Not Found
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 500
            message: Internal server error
            error: Internal Server Error
  schemas:
    InstallationRecord:
      type: object
      description: Details of an installed AI workflow, including its current status and configuration.
      properties:
        slug:
          type: string
          description: The unique identifier for the AI workflow.
          example: cell-analysis
        type:
          type: string
          description: The type of artifact.
          example: ai-workflow
        version:
          type: string
          description: The installed version.
          example: v1.0.0
        namespace:
          type: string
          description: The artifact namespace.
          example: common
        description:
          type: string
          description: A text description of the AI workflow.
          example: Cell analysis AI workflow
        organization:
          type: string
          description: The organization that owns this installation.
          example: acme-corp
        status:
          type: string
          enum:
          - processing
          - completed
          - failed
          description: 'The current installation status. processing: installation is in progress. completed: installation
            finished successfully. failed: installation encountered an error.'
          example: completed
        config:
          type: object
          description: Configuration overrides applied to this installation.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the installation was created.
          example: '2024-01-15T10:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the installation was last updated.
          example: '2024-01-15T10:35:00Z'
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        error:
          type: string
          example: Bad Request

AI Services Inference API

openapi: 3.0.3
info:
  title: TetraScience AI Services Inference API (v1.0.x)
  version: 1.0.2
  description: API for running inferences on installed Scientific AI Workflows through TetraScience AI Services (v1.0.x).
    Supports both synchronous (online) and asynchronous (offline) inference requests.
servers:
- url: https://gateway.tetrascience.com/ai-platform/v1
  description: TetraScience API (US MT)
paths:
  /inference:
    post:
      summary: Submit an asynchronous (offline) inference request
      description: 'Submit an asynchronous, file-based inference request with support for partial file staging success.

        Returns immediately with a request ID and status URL for tracking progress.


        Use this offline endpoint when:

        - Processing large files or datasets

        - Running batch inference jobs

        - Tasks expected to take more than 60 seconds

        - Files are already uploaded to the platform


        **Enhanced Partial Success Support:**

        - Critical files (roles: primary, required, input, main, essential) must succeed for inference to proceed

        - Optional files (roles: metadata, auxiliary, reference, supplementary, optional) can fail without blocking inference

        - Response includes detailed staging summary when partial success occurs


        **File Criticality Rules:**

        - Files with dependencies are considered critical

        - Lower processing order files (processed first) are more critical

        - Role-based classification with configurable rules per use case

        '
      security:
      - bearerAuth: []
      - internalApiKey: []
      parameters:
      - name: x-org-slug
        in: header
        required: true
        schema:
          type: string
        description: Organization slug identifier
        example: acme-corp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - aiWorkflow
              - inputFiles
              properties:
                aiWorkflow:
                  type: string
                  description: The AI workflow identifier for the inference request, you can get a list of available AI workflows
                    using the GET `/v1/install` endpoint
                  example: cell-analysis
                inputFiles:
                  type: array
                  description: List of input files for inference processing
                  minItems: 1
                  items:
                    type: object
                    required:
                    - fileUuid
                    - role
                    - processingOrder
                    properties:
                      fileUuid:
                        type: string
                        description: UUID of the file to process
                        example: 550e8400-e29b-41d4-a716-446655440000
                      role:
                        type: string
                        description: Role of the file in processing
                        enum:
                        - file
                        - instructions
                        - parameters
                        default: file
                        example: file
                      processingOrder:
                        type: integer
                        description: Order in which file should be processed
                        minimum: 1
                        default: 1
                        example: 1
                      dependencies:
                        type: array
                        description: List of file UUIDs this file depends on
                        items:
                          type: string
                        default: []
                        example: []
            examples:
              basic-inference:
                summary: Basic inference request
                value:
                  aiWorkflow: cell-analysis
                  inputFiles:
                  - fileUuid: 550e8400-e29b-41d4-a716-446655440000
                    role: file
                    processingOrder: 1
                    dependencies: []
              multi-file-inference:
                summary: Multi-file inference with dependencies
                value:
                  aiWorkflow: lead-clone-selection:v2.1.0
                  inputFiles:
                  - fileUuid: 550e8400-e29b-41d4-a716-446655440001
                    role: file
                    processingOrder: 1
                    dependencies: []
                  - fileUuid: 550e8400-e29b-41d4-a716-446655440002
                    role: instructions
                    processingOrder: 2
                    dependencies:
                    - 550e8400-e29b-41d4-a716-446655440001
                  - fileUuid: 550e8400-e29b-41d4-a716-446655440003
                    role: parameters
                    processingOrder: 3
                    dependencies: []
      responses:
        '202':
          description: Inference request submitted successfully (Accepted)
          content:
            application/json:
              schema:
                type: object
                required:
                - requestId
                - statusUrl
                properties:
                  requestId:
                    type: string
                    description: Unique identifier for the inference request
                    example: req-20250929-abc123def456
                  statusUrl:
                    type: string
                    description: URL to check the status of the inference request
                    example: /v1/inference/req-20250929-abc123def456
                  partialSuccess:
                    type: boolean
                    description: Indicates if some files failed to stage but inference can still proceed
                    example: true
                  stagingSummary:
                    type: object
                    description: Detailed breakdown of file staging results (only present for partial success)
                    properties:
                      totalFiles:
                        type: integer
                        description: Total number of files in the request
                        example: 3
                      successfulFiles:
                        type: integer
                        description: Number of files successfully staged
                        example: 2
                      failedFiles:
                        type: integer
                        description: Number of files that failed to stage
                        example: 1
                      criticalFailures:
                        type: integer
                        description: Number of critical files that failed (would block inference)
                        example: 0
                      optionalFailures:
                        type: integer
                        description: Number of optional files that failed (don't block inference)
                        example: 1
                      warnings:
                        type: array
                        description: Warning messages about failed optional files
                        items:
                          type: string
                        example:
                        - 'Optional file failed to stage: metadata.json (Access denied)'
              examples:
                successful-staging:
                  summary: All files staged successfully
                  value:
                    requestId: req-20250929-abc123def456
                    statusUrl: /v1/inference/req-20250929-abc123def456
                partial-success:
                  summary: Partial staging success with optional file failure
                  value:
                    requestId: req-20250929-abc123def456
                    statusUrl: /v1/inference/req-20250929-abc123def456
                    partialSuccess: true
                    stagingSummary:
                      totalFiles: 3
                      successfulFiles: 2
                      failedFiles: 1
                      criticalFailures: 0
                      optionalFailures: 1
                      warnings:
                      - 'Optional file failed to stage: metadata.json (Access denied)'
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 400
                  details:
                    type: object
                    description: Additional error details
              examples:
                invalid-ai-workflow:
                  summary: Invalid or missing AI workflow
                  value:
                    error: 'AI workflow not found: invalid-ai-workflow'
                    code: 400
                    details:
                      field: aiWorkflow
                      value: invalid-ai-workflow
                no-async-support:
                  summary: AI workflow doesn't support async inference
                  value:
                    error: AI workflow 'sync-only-model:v1.0.0' is not compatible with async inference requests
                    code: 400
                    details:
                      aiWorkflow: sync-only-model:v1.0.0
                      asyncCompatible: false
                no-files:
                  summary: No valid files provided
                  value:
                    error: No valid files found for inference request
                    code: 400
                    details:
                      providedFiles: 2
                      validFiles: 0
                      fileErrors:
                      - 'File not found: 550e8400-e29b-41d4-a716-446655440000'
                      - 'File is empty (0 bytes): 550e8400-e29b-41d4-a716-446655440001'
                critical-files-failed:
                  summary: Critical files failed to stage
                  value:
                    error: 'Critical files failed to stage, cannot proceed with inference: Critical file failed to stage:
                      primary-data.csv (Access denied)'
                    code: 400
                    details:
                      criticalFailures: 1
                      totalFiles: 3
                      failedFiles:
                      - primary-data.csv
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid or missing authentication token
                  code:
                    type: integer
                    example: 401
        '403':
          description: Access denied - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 403
              examples:
                ai-workflow-access-denied:
                  summary: No access to AI workflow
                  value:
                    error: Organization 'acme-corp' does not have access to AI workflow 'restricted-model:v1.0.0'
                    code: 403
                file-access-denied:
                  summary: File doesn't belong to organization
                  value:
                    error: File 550e8400-e29b-41d4-a716-446655440000 does not belong to organization acme-corp
                    code: 403
                ai-workflow-disabled:
                  summary: AI workflow is disabled or deprecated
                  value:
                    error: AI workflow 'deprecated-model:v0.9.0' is deprecated and cannot be used
                    code: 403
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 404
              examples:
                ai-workflow-not-found:
                  summary: AI workflow not found in registry
                  value:
                    error: 'AI workflow not found: non-existent-model:v1.0.0'
                    code: 404
                files-not-found:
                  summary: Files not found in FileInfo service
                  value:
                    error: 'File validation failed: File not found: 550e8400-e29b-41d4-a716-446655440000'
                    code: 404
        '409':
          description: Conflict - request cannot be processed due to current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 409
              examples:
                ai-workflow-inactive:
                  summary: AI workflow is not active
                  value:
                    error: AI workflow 'maintenance-model:v1.0.0' is disabled and cannot be used
                    code: 409
        '422':
          description: Unprocessable entity - request format is valid but content is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 422
              examples:
                invalid-file-format:
                  summary: Invalid file format or structure
                  value:
                    error: 'File validation failed: File is empty (0 bytes): empty-file.csv'
                    code: 422
                invalid-ai-workflow-format:
                  summary: Invalid AI workflow name format
                  value:
                    error: 'Invalid AI workflow name format: invalid@name#format'
                    code: 422
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 500
              examples:
                staging-error:
                  summary: File staging infrastructure error
                  value:
                    error: 'Enhanced file staging failed: S3 service unavailable'
                    code: 500
                queue-error:
                  summary: Message queue service error
                  value:
                    error: 'Failed to queue inference request: SQS service unavailable'
                    code: 500
                database-error:
                  summary: Database service error
                  value:
                    error: 'Failed to create inference request: DynamoDB service unavailable'
                    code: 500
                fileinfo-service-error:
                  summary: FileInfo service unavailable
                  value:
                    error: FileInfo Service is not available
                    code: 500
        '503':
          description: Service unavailable - required services are down
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 503
              examples:
                fileinfo-timeout:
                  summary: FileInfo service timeout
                  value:
                    error: FileInfo Service request timed out
                    code: 503
                external-dependency:
                  summary: External service dependency unavailable
                  value:
                    error: Required external service is temporarily unavailable
                    code: 503
  /inference/{inferenceId}/status:
    get:
      summary: Get inference request status
      description: 'Retrieve the current status and details of an inference request.

        Includes file-level details and partial success information when applicable.

        '
      security:
      - bearerAuth: []
      - internalApiKey: []
      parameters:
      - name: x-org-slug
        in: header
        required: true
        schema:
          type: string
        description: Organization slug identifier
        example: acme-corp
      - name: inferenceId
        in: path
        required: true
        schema:
          type: string
        description: The inference request ID
        example: req-20250929-abc123def456
      - name: includeFiles
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include detailed file information in the response
      responses:
        '200':
          description: Inference request status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - requestId
                - status
                - aiWorkflow
                - organization
                - createdAt
                - updatedAt
                properties:
                  requestId:
                    type: string
                    example: req-20250929-abc123def456
                  dbxRunId:
                    type: number
                    example: 123456789100001
                  status:
                    type: string
                    enum:
                    - pending
                    - processing
                    - completed
                    - failed
                    example: processing
                  aiWorkflow:
                    type: string
                    example: cell-analysis
                  organization:
                    type: string
                    example: acme-corp
                  user:
                    type: string
                    example: user123
                  createdAt:
                    type: string
                    format: date-time
                    example: '2025-09-29T10:30:00Z'
                  updatedAt:
                    type: string
                    format: date-time
                    example: '2025-09-29T10:35:00Z'
                  completedAt:
                    type: string
                    format: date-time
                    description: When the inference completed (only for completed/failed status)
                    example: '2025-09-29T10:45:00Z'
                  inputFiles:
                    type: array
                    description: Original input file specifications
                    items:
                      type: object
                      properties:
                        fileUuid:
                          type: string
                        role:
                          type: string
                        processingOrder:
                          type: integer
                        dependencies:
                          type: array
                          items:
                            type: string
                  stagingLocation:
                    type: object
                    description: S3 staging location information
                    properties:
                      bucket:
                        type: string
                        example: inference-staging-bucket
                      prefix:
                        type: string
                        example: tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/
                      fullPath:
                        type: string
                        example: s3://inference-staging-bucket/tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/
                  outputLocation:
                    type: object
                    description: S3 output location information
                    properties:
                      bucket:
                        type: string
                        example: inference-output-bucket
                      prefix:
                        type: string
                        example: tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/
                      fullPath:
                        type: string
                        example: s3://inference-output-bucket/tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/
                  manifestPath:
                    type: string
                    description: S3 path to the processing manifest
                    example: s3://inference-staging-bucket/tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/manifest.csv
                  errorMessage:
                    type: string
                    description: Error message if inference failed
                    example: 'APEX processing failed: Model inference timeout'
                  partialSuccess:
                    type: boolean
                    description: Whether this request had partial staging success
                    example: true
                  stagingSummary:
                    type: object
                    description: Summary of file staging results (if partial success occurred)
                    properties:
                      totalFiles:
                        type: integer
                        example: 3
                      successfulFiles:
                        type: integer
                        example: 2
                      failedFiles:
                        type: integer
                        example: 1
                      criticalFailures:
                        type: integer
                        example: 0
                      optionalFailures:
                        type: integer
                        example: 1
                  files:
                    type: array
                    description: Detailed file information (only if includeFiles=true)
                    items:
                      type: object
                      properties:
                        fileUuid:
                          type: string
                          example: 550e8400-e29b-41d4-a716-446655440000
                        fileName:
                          type: string
                          example: primary-data.csv
                        fileSize:
                          type: integer
                          example: 1048576
                        status:
                          type: string
                          enum:
                          - pending
                          - staged
                          - processing
                          - completed
                          - failed
                          example: completed
                        role:
                          type: string
                          example: primary
                        stagingPath:
                          type: string
                          example: s3://staging-bucket/path/to/staged-file.csv
                        outputPath:
                          type: string
                          example: s3://output-bucket/path/to/result-file.csv
                        result:
                          type: string
                          description: Pre-signed URL to download the result file
                          example: https://s3.amazonaws.com/output-bucket/path/to/result?X-Amz-Signature=...
                        errorMessage:
                          type: string
                          description: Error message if file processing failed
              examples:
                processing-request:
                  summary: Request currently processing
                  value:
                    requestId: req-20250929-abc123def456
                    status: processing
                    aiWorkflow: cell-analysis
                    organization: acme-corp
                    user: user123
                    createdAt: '2025-09-29T10:30:00Z'
                    updatedAt: '2025-09-29T10:35:00Z'
                    inputFiles:
                    - fileUuid: 550e8400-e29b-41d4-a716-446655440000
                      role: primary
                      processingOrder: 1
                      dependencies: []
                    stagingLocation:
                      bucket: inference-staging-bucket
                      prefix: tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/
                      fullPath: s3://inference-staging-bucket/tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/
                    outputLocation:
                      bucket: inference-output-bucket
                      prefix: tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/
                      fullPath: s3://inference-output-bucket/tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/
                    manifestPath: s3://inference-staging-bucket/tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/manifest.csv
                completed-with-partial-success:
                  summary: Completed request with partial staging success
                  value:
                    requestId: req-20250929-abc123def456
                    status: completed
                    aiWorkflow: cell-analysis
                    organization: acme-corp
                    user: user123
                    createdAt: '2025-09-29T10:30:00Z'
                    updatedAt: '2025-09-29T10:45:00Z'
                    completedAt: '2025-09-29T10:45:00Z'
                    partialSuccess: true
                    stagingSummary:
                      totalFiles: 3
                      successfulFiles: 2
                      failedFiles: 1
                      criticalFailures: 0
                      optionalFailures: 1
                    inputFiles:
                    - fileUuid: 550e8400-e29b-41d4-a716-446655440000
                      role: primary
                      processingOrder: 1
                      dependencies: []
                    - fileUuid: 550e8400-e29b-41d4-a716-446655440001
                      role: metadata
                      processingOrder: 2
                      dependencies: []
                failed-request:
                  summary: Failed inference request
                  value:
                    requestId: req-20250929-abc123def456
                    status: failed
                    aiWorkflow: cell-analysis
                    organization: acme-corp
                    user: user123
                    createdAt: '2025-09-29T10:30:00Z'
                    updatedAt: '2025-09-29T10:37:00Z'
                    completedAt: '2025-09-29T10:37:00Z'
                    errorMessage: 'APEX processing failed: Model inference timeout after 300 seconds'
        '404':
          description: Inference request not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Inference request not found: req-20250929-nonexistent'
                  code:
                    type: integer
                    example: 404
        '403':
          description: Access denied - request belongs to different organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Access denied: Inference request belongs to different organization'
                  code:
                    type: integer
                    example: 403
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Failed to get inference request: Database connection failed'
                  code:
                    type: integer
                    example: 500
  /inference/online:
    post:
      summary: Submit a synchronous inference request
      description: 'Performs real-time ML inference and returns results immediately via streaming or buffered response.

        **Only available for AI workflows with Model Serving Endpoint capability.**


        **When to use Sync vs Async:**

        - Use **sync (online)** for: Real-time predictions, chat/conversation, low-latency requirements (<60s)

        - Use **async (offline)** for: Batch processing, large files, long-running inference (>60s)


        **Response Modes:**

        - **Streaming** (`stream: true`): Results streamed as Server-Sent Events (SSE)

        - **Buffered** (`stream: false`): Complete response returned at once (default)


        **Input Flexibility:**

        The `inferenceInput` field supports multiple formats:

        - Tabular data: `data` (array of arrays) or `dataframe_records` (array of objects)

        - Images: `images` array with base64-encoded data

        - Chat messages: `messages` array with role/content structure

        - Custom formats: Any structure supported by the model serving endpoint

        '
      security:
      - bearerAuth: []
      - internalApiKey: []
      parameters:
      - name: x-org-slug
        in: header
        required: true
        schema:
          type: string
        description: Organization slug identifier
        example: acme-corp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - aiWorkflow
              - inferenceInput
              properties:
                aiWorkflow:
                  type: string
                  description: The AI workflow identifier
                  example: cell-analysis
                version:
                  type: string
                  description: Specific version of the AI workflow (optional, uses latest if not specified)
                  example: v1.0.0
                inferenceOptions:
                  type: object
                  description: Configuration options for the inference request
                  properties:
                    stream:
                      type: boolean
                      description: Enable streaming response mode (SSE)
                      default: false
                    metrics:
                      type: boolean
                      description: Enable metrics collection for this request
                      default: false
                    timeout:
                      type: integer
                      description: Request timeout in milliseconds (1000-60000)
                      minimum: 1000
                      maximum: 60000
                      default: 60000
                      example: 60000
                inferenceInput:
                  type: object
                  description: 'Flexible input data structure. Format depends on the model serving endpoint requirements.

                    Common formats include tabular data, images, or chat messages.

                    '
                  oneOf:
                  - type: object
                    description: Tabular data format (array of arrays)
                    properties:
                      data:
                        type: array
                        items:
                          type: array
                  - type: object
                    description: Tabular data format (array of records)
                    properties:
                      dataframe_records:
                        type: array
                        items:
                          type: object
                  - type: object
                    description: Image data format
                    properties:
                      images:
                        type: array
                        items:
                          type: object
                          properties:
                            b64:
                              type: string
                              description: Base64-encoded image data
                  - type: object
                    description: Chat/conversation format
                    properties:
                      messages:
                        type: array
                        items:
                          type: object
                          properties:
                            role:
                              type: string
                              enum:
                              - user
                              - assistant
                              - system
                            content:
                              type: string
            examples:
              tabular-data-buffered:
                summary: Tabular data inference (buffered)
                value:
                  aiWorkflow: lead-clone-selection:v2.1.0
                  inferenceInput:
                    dataframe_records:
                    - feature1: 1.5
                      feature2: category_a
                      feature3: 42
                    - feature1: 2.3
                      feature2: category_b
                      feature3: 37
                  inferenceOptions:
                    stream: false
                    metrics: true
                    timeout: 30000
              tabular-data-streaming:
                summary: Tabular data inference (streaming)
                value:
                  aiWorkflow: lead-clone-selection:v2.1.0
                  inferenceInput:
                    data:
                    - - 1.5
                      - category_a
                      - 42
                    - - 2.3
                      - category_b
                      - 37
                  inferenceOptions:
                    stream: true
                    timeout: 30000
              chat-conversation:
                summary: Chat-based inference
                value:
                  aiWorkflow: coding-assistant:v1.0.0
                  inferenceInput:
                    messages:
                    - role: user
                      content: Write a Python function to calculate factorial
                  inferenceOptions:
                    stream: true
                    timeout: 30000
              image-inference:
                summary: Image-based inference
                value:
                  aiWorkflow: cell-image-analysis:v1.5.0
                  inferenceInput:
                    images:
                    - b64: iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==
                  inferenceOptions:
                    stream: false
                    metrics: true
      responses:
        '200':
          description: Inference completed successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - requestId
                - status
                - timestamp
                properties:
                  requestId:
                    type: string
                    description: Unique identifier for this online inference request
                    example: sync_123e4567-e89b-12d3-a456-426614174000
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    description: Status of the inference request
                    example: success
                  inferenceOutput:
                    description: Model output (format varies by model and can be any type)
                  metrics:
                    type: object
                    description: Optional metrics about the inference execution
                    properties:
                      runDuration:
                        type: number
                        description: Total request duration in milliseconds
                      executionDuration:
                        type: number
                        description: Execution duration in milliseconds
                  timestamp:
                    type: string
                    format: date-time
                    description: ISO 8601 timestamp of the response
                  errorMessage:
                    type: string
                    description: Error message if status is "failed"
              examples:
                tabular-predictions:
                  summary: Tabular data predictions
                  value:
                    requestId: sync_123e4567-e89b-12d3-a456-426614174000
                    status: success
                    inferenceOutput:
                      predictions:
                      - 0.85
                      - 0.72
                    metrics:
                      runDuration: 245
                      executionDuration: 245
                    timestamp: '2025-09-29T10:30:00Z'
                chat-response:
                  summary: Chat conversation response
                  value:
                    requestId: sync_223e4567-e89b-12d3-a456-426614174001
                    status: success
                    inferenceOutput:
                      predictions:
                      - role: assistant
                        content: "Here's a Python function to calculate factorial:\n\n```python\ndef factorial(n):\n    if\
                          \ n <= 1:\n        return 1\n    return n * factorial(n - 1)\n```"
                    metrics:
                      runDuration: 1823
                      executionDuration: 1823
                    timestamp: '2025-09-29T10:30:05Z'
            text/event-stream:
              schema:
                type: string
                format: binary
                description: 'Server-Sent Events (SSE) stream with real-time inference results.

                  Each event contains a data field with partial or complete predictions.


                  **Event Format:**

                  ```

                  data: {"chunk": "partial result", "done": false}


                  data: [DONE]

                  ```


                  Note: The requestId is not included in streaming events but is stored server-side.

                  '
        '400':
          description: Bad request - validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 400
              examples:
                invalid-ai-workflow:
                  summary: AI workflow not found
                  value:
                    error: 'AI workflow not found: invalid-workflow'
                    code: 400
                no-online-support:
                  summary: AI workflow doesn't support online inference
                  value:
                    error: AI workflow 'file-based-only:v1.0.0' does not have a model serving endpoint configured
                    code: 400
                invalid-input:
                  summary: Invalid inference input
                  value:
                    error: 'Invalid inferenceInput format: expected ''dataframe_records'' or ''data'' field'
                    code: 400
                invalid-timeout:
                  summary: Invalid timeout value
                  value:
                    error: Timeout must be between 1000ms and 60000ms
                    code: 400
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid or missing authentication token
                  code:
                    type: integer
                    example: 401
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 403
              examples:
                no-access:
                  summary: No access to AI workflow
                  value:
                    error: Organization 'acme-corp' does not have access to AI workflow 'restricted-model:v1.0.0'
                    code: 403
                insufficient-permissions:
                  summary: Insufficient role permissions
                  value:
                    error: 'User does not have required role. Required: orgAdmin, mlEngineer, scientist, or scientificDataEngineer'
                    code: 403
        '404':
          description: AI workflow not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'AI workflow not found: non-existent:v1.0.0'
                  code:
                    type: integer
                    example: 404
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 422
              examples:
                invalid-input-format:
                  summary: Invalid input data format
                  value:
                    error: 'Model serving endpoint returned validation error: Input data must contain numeric features'
                    code: 422
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 500
              examples:
                model-serving-error:
                  summary: Model serving endpoint error
                  value:
                    error: 'Model serving endpoint failed: Internal server error'
                    code: 500
                timeout:
                  summary: Inference timeout
                  value:
                    error: Inference request timed out after 30000ms
                    code: 500
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: integer
                    example: 503
              examples:
                model-serving-unavailable:
                  summary: Model serving endpoint unavailable
                  value:
                    error: Model serving endpoint is temporarily unavailable
                    code: 503
  /inference/online/{requestId}/metrics:
    get:
      summary: Get metrics for a synchronous inference request
      description: 'Retrieves metrics and status information for a completed synchronous inference request.

        Metrics are stored for tracking and debugging purposes.

        '
      security:
      - bearerAuth: []
      - internalApiKey: []
      parameters:
      - name: x-org-slug
        in: header
        required: true
        schema:
          type: string
        description: Organization slug identifier
        example: acme-corp
      - name: requestId
        in: path
        required: true
        schema:
          type: string
        description: The online inference request ID
        example: sync_123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Metrics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  requestId:
                    type: string
                    example: sync_123e4567-e89b-12d3-a456-426614174000
                  aiWorkflow:
                    type: string
                    example: cell-analysis
                  organization:
                    type: string
                    example: acme-corp
                  status:
                    type: string
                    enum:
                    - success
                    - failed
                    - timeout
                    example: success
                  processingTime:
                    type: number
                    description: Time taken to process the request (milliseconds)
                    example: 1245
                  timestamp:
                    type: string
                    format: date-time
                    example: '2025-09-29T10:30:00Z'
                  inputSize:
                    type: integer
                    description: Size of input data in bytes
                    example: 2048
                  errorMessage:
                    type: string
                    description: Error message if inference failed
              examples:
                successful-inference:
                  summary: Successful inference metrics
                  value:
                    requestId: sync_123e4567-e89b-12d3-a456-426614174000
                    aiWorkflow: lead-clone-selection:v2.1.0
                    organization: acme-corp
                    status: success
                    processingTime: 1245
                    timestamp: '2025-09-29T10:30:00Z'
                    inputSize: 2048
                failed-inference:
                  summary: Failed inference metrics
                  value:
                    requestId: sync_223e4567-e89b-12d3-a456-426614174001
                    aiWorkflow: cell-analysis
                    organization: acme-corp
                    status: failed
                    processingTime: 892
                    timestamp: '2025-09-29T10:35:00Z'
                    inputSize: 1024
                    errorMessage: 'Model serving endpoint returned 500: Internal server error'
        '403':
          description: Access denied - request belongs to different organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Access denied: Inference request belongs to different organization'
                  code:
                    type: integer
                    example: 403
        '404':
          description: Metrics not found for this request ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Metrics not found for request: sync_nonexistent-uuid'
                  code:
                    type: integer
                    example: 404
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: 'Failed to retrieve metrics: Database connection failed'
                  code:
                    type: integer
                    example: 500
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    internalApiKey:
      type: apiKey
      in: header
      name: ts-internal-api-key
      description: Internal API key for service-to-service authentication

Artifact Registry API

openapi: 3.0.3
info:
  title: TetraScience TetraSphere Artifact Registry API (v1.0.x)
  version: 1.0.2
  description: 'API for managing TetraSphere artifact registry, versions, and review workflows.


    Use this API to list registered AI workflow and TetraSphere application artifacts,

    retrieve artifact version details, and manage the review workflow (approve or cancel versions).


    ## Authentication

    - All endpoints require a `ts-auth-token` header.

    - Review workflow endpoints additionally require one of the following roles: `orgAdmin`, `tenantAdmin`, or `machineLearningEngineer`.


    ## Visibility

    - Non-admin users can view only artifacts whose current version is `Approved`.

    - Version history and release notes are omitted from non-admin responses.


    ## Review workflow

    - Set `reviewStatus` to `Approved` to activate an artifact version.

    - Set `reviewStatus` to `Cancelled` to cancel an artifact version.

    '
servers:
- url: https://gateway.tetrascience.com/sphere
  description: TetraScience AWS API Gateway (US MT)
tags:
- name: Artifact Registry
  description: 'Retrieve artifacts and their versions from the TetraSphere registry.

    Non-admin users can view only artifacts with an approved current version.

    '
- name: Review Workflow
  description: 'Approve or cancel artifact versions. Requires the orgAdmin, tenantAdmin,

    or machineLearningEngineer role.

    '
- name: Artifact Logs
  description: Retrieve audit log entries for review-status changes and publish actions.
- name: Operations
  description: Service health and connectivity checks.
paths:
  /registry:
    get:
      tags:
      - Artifact Registry
      summary: List artifacts for an organization
      description: 'Returns artifacts registered for the organization in `x-org-slug`.


        Admin users receive all artifact versions and review fields.

        Non-admin users receive only artifacts whose current version is `Approved`; version history and

        release notes are omitted from non-admin responses.

        '
      operationId: listArtifacts
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - name: placement
        in: query
        required: false
        description: Filter artifacts by their UI placement. Use tile for main dashboard tiles or subNav for navigation sub-items.
        schema:
          $ref: '#/components/schemas/PlacementType'
      - name: artifactType
        in: query
        required: false
        description: Filter artifacts by type (for example, ai-workflow or tetrasphere-app).
        schema:
          $ref: '#/components/schemas/ArtifactType'
      - name: namespace
        in: query
        required: false
        description: Filter artifacts by namespace. Use common for shared artifacts. When omitted, returns artifacts from
          all namespaces.
        schema:
          type: string
          example: common
      responses:
        '200':
          description: Artifacts retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ArtifactResponse'
              examples:
                artifact-list:
                  summary: Artifact list
                  value:
                  - artifactKey: ai-platform
                    name: AI Platform
                    placement: tile
                    artifactType: tetrasphere-app
                    namespace: common
                    currentVersion:
                      version: v1.2.0
                      reviewStatus: Approved
                    newestVersion:
                      version: v1.3.0
                      reviewStatus: Approved
                    inReviewVersion: null
                    allOtherVersions:
                    - version: v1.1.0
                      reviewStatus: Cancelled
                    allVersions:
                    - version: v1.1.0
                      reviewStatus: Cancelled
                    - version: v1.2.0
                      reviewStatus: Approved
                    - version: v1.3.0
                      reviewStatus: Approved
                    children: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /registry/artifact-types:
    get:
      tags:
      - Artifact Registry
      summary: List supported artifact types
      operationId: getSupportedArtifactTypes
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      responses:
        '200':
          description: Supported artifact types retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupportedArtifactTypesResponse'
              example:
                artifactTypes:
                - ai-workflow
                - tetrasphere-app
                description: List of supported artifact types
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /registry/artifacts/review-status:
    put:
      tags:
      - Review Workflow
      summary: Approve or cancel an artifact version
      description: 'Updates an artifact version review status to `Approved` or `Cancelled` and records a log entry.

        '
      operationId: setArtifactVersionReviewStatus
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetReviewStatusRequest'
            examples:
              approve-version:
                summary: Approve an artifact version
                value:
                  artifactKey: cell-analysis
                  version: v1.0.0
                  reviewStatus: Approved
                  artifactType: ai-workflow
                  namespace: common
                  reason: Scientific review completed
              cancel-version:
                summary: Cancel an artifact version
                value:
                  artifactKey: cell-analysis
                  version: v1.1.0
                  reviewStatus: Cancelled
                  artifactType: ai-workflow
                  namespace: common
                  reason: Validation failed
      responses:
        '200':
          description: Review status updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetReviewStatusResponse'
              examples:
                approved:
                  summary: Version approved
                  value:
                    success: true
                    reviewStatus: Approved
                    message: Artifact version v1.0.0 status changed to Approved
                cancelled:
                  summary: Version cancelled
                  value:
                    success: true
                    reviewStatus: Cancelled
                    message: Artifact version v1.1.0 status changed to Cancelled
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /registry/artifacts/ai-platform:
    get:
      tags:
      - Artifact Registry
      summary: Get the ai-platform artifact
      description: 'Retrieves the ai-platform TetraSphere application artifact.


        This is a convenience endpoint equivalent to

        GET /registry/artifacts/tetrasphere-app/ai-platform.

        '
      operationId: getAiPlatformArtifact
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - $ref: '#/components/parameters/VersionQuery'
      - $ref: '#/components/parameters/ChildArtifactTypeQuery'
      responses:
        '200':
          description: Artifact retrieved successfully.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ArtifactResponse'
                - $ref: '#/components/schemas/ArtifactVersionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /registry/artifacts/{artifactType}/{artifactKey}:
    get:
      tags:
      - Artifact Registry
      summary: Get artifact details or a specific artifact version
      description: 'Retrieves a single artifact by type and key. Without `version`, the response includes artifact-level

        details, current/newest version references, all versions, and direct child artifacts.


        When `version` is provided, the response is version-specific and includes the requested version''s

        review status, description, and release notes.


        Non-admin users can retrieve only approved versions. Release notes and version history are

        omitted from non-admin artifact responses.

        '
      operationId: getArtifact
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - $ref: '#/components/parameters/ArtifactTypePath'
      - $ref: '#/components/parameters/ArtifactKeyPath'
      - $ref: '#/components/parameters/VersionQuery'
      - $ref: '#/components/parameters/ChildArtifactTypeQuery'
      - $ref: '#/components/parameters/NamespaceQuery'
      responses:
        '200':
          description: Artifact or artifact version retrieved successfully.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ArtifactResponse'
                - $ref: '#/components/schemas/ArtifactVersionResponse'
              examples:
                artifact:
                  summary: Artifact response
                  value:
                    artifactKey: cell-analysis
                    name: Cell Analysis
                    placement: tile
                    artifactType: ai-workflow
                    artifactSubType: cv
                    namespace: common
                    currentVersion:
                      version: v1.0.0
                      reviewStatus: Approved
                    newestVersion:
                      version: v1.1.0
                      reviewStatus: Cancelled
                    inReviewVersion: null
                    allOtherVersions: []
                    allVersions:
                    - version: v1.0.0
                      reviewStatus: Approved
                    - version: v1.1.0
                      reviewStatus: Cancelled
                    children: []
                    description: Cell image analysis workflow
                    releaseNotes: Initial approved release
                version:
                  summary: Version response
                  value:
                    artifactKey: cell-analysis
                    name: Cell Analysis
                    placement: tile
                    artifactType: ai-workflow
                    artifactSubType: cv
                    namespace: common
                    version: v1.0.0
                    reviewStatus: Approved
                    description: Cell image analysis workflow
                    releaseNotes: Initial approved release
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /registry/artifacts/{artifactType}/{artifactKey}/audit-logs:
    get:
      tags:
      - Artifact Logs
      summary: Get artifact logs
      description: Returns log entries for review-status and publish actions for an artifact.
      operationId: getArtifactLogs
      security:
      - tsAuthToken: []
      parameters:
      - $ref: '#/components/parameters/OrgSlugHeader'
      - $ref: '#/components/parameters/ArtifactTypePath'
      - $ref: '#/components/parameters/ArtifactKeyPath'
      - $ref: '#/components/parameters/NamespaceQuery'
      responses:
        '200':
          description: Artifact logs retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetArtifactLogsResponse'
              example:
                success: true
                message: Retrieved 2 log(s) for artifact cell-analysis
                auditLogs:
                - type: Audit
                  orgSlug: acme-corp
                  artifactKey: cell-analysis
                  artifactType: ai-workflow
                  actor: user-123
                  version: v1.0.0
                  versionSort: '000010000100001'
                  action: REVIEW_STATUS_CHANGED
                  from:
                    reviewStatus: Cancelled
                  to:
                    reviewStatus: Approved
                  reason: Scientific review completed
                  at: '2026-05-05T12:30:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /registry/health:
    get:
      tags:
      - Operations
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is healthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: ok
                timestamp: '2026-05-05T12:30:00.000Z'
                message: TetraSphere service is healthy
                version: v1.1.2-pre3
                hash: 2a94b5b
components:
  securitySchemes:
    tsAuthToken:
      type: apiKey
      in: header
      name: ts-auth-token
      description: TetraScience authentication token. Include this header in all API requests. To obtain a token, see the
        Authentication guide.
  parameters:
    OrgSlugHeader:
      name: x-org-slug
      in: header
      required: true
      description: Your organization's unique identifier (for example, acme-corp). Find this in the TDP URL or organization
        settings.
      schema:
        type: string
      example: acme-corp
    ArtifactTypePath:
      name: artifactType
      in: path
      required: true
      description: The type of artifact to retrieve.
      schema:
        $ref: '#/components/schemas/ArtifactType'
      example: ai-workflow
    ArtifactKeyPath:
      name: artifactKey
      in: path
      required: true
      description: The unique key that identifies an artifact within its type (for example, cell-analysis).
      schema:
        type: string
        pattern: ^[a-zA-Z0-9_-]+$
      example: cell-analysis
    VersionQuery:
      name: version
      in: query
      required: false
      description: Return a specific version instead of the full artifact. Must include a leading v (for example, v1.0.0).
        When omitted, the response includes the full artifact with all versions.
      schema:
        type: string
        pattern: ^v\d+\.\d+\.\d+(-[a-zA-Z0-9_.-]+)?$
      example: v1.0.0
    ChildArtifactTypeQuery:
      name: childArtifactType
      in: query
      required: false
      description: Filters the children array to include only children of this type (for example, ai-workflow).
      schema:
        type: string
      example: ai-workflow
    NamespaceQuery:
      name: namespace
      in: query
      required: false
      description: Artifact namespace. Use common for shared artifacts. When omitted, returns artifacts from all namespaces
        allowed for the organization.
      schema:
        type: string
      example: common
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            message: '''x-org-slug'' header is required'
            error: Bad Request
    Unauthorized:
      description: Authentication failed or credentials were not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 401
            message: ts-auth-token header is required
            error: Unauthorized
    Forbidden:
      description: Authenticated caller lacks the required policy for the organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 403
            message: 'Insufficient permissions: requires one of [orgAdmin, tenantAdmin, machineLearningEngineer] for org ''acme-corp'''
            error: Forbidden
    NotFound:
      description: Requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            message: Artifact with key cell-analysis not found in organization acme-corp
            error: Not Found
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 500
            message: Internal server error
            error: Internal Server Error
  schemas:
    ArtifactType:
      type: string
      description: 'The type of artifact registered in TetraSphere. ai-workflow: an AI/ML workflow artifact. tetrasphere-app:
        a TetraSphere application artifact.'
      enum:
      - ai-workflow
      - tetrasphere-app
    PlacementType:
      type: string
      description: 'Controls where the artifact appears in the TetraSphere UI. tile: displayed as a tile on the main dashboard.
        subNav: displayed as a sub-item in the navigation menu.'
      enum:
      - tile
      - subNav
    ReviewStatus:
      type: string
      description: 'The review state of an artifact version. Approved: version is active and visible to all users. Cancelled:
        version has been rejected or withdrawn.'
      enum:
      - Approved
      - Cancelled
    SemverWithV:
      type: string
      description: Semantic version string with a leading v (for example, v1.0.0 or v2.1.0-beta.1).
      pattern: ^v\d+\.\d+\.\d+(-[a-zA-Z0-9_.-]+)?$
      example: v1.0.0
    ArtifactVersionInfo:
      type: object
      required:
      - version
      - reviewStatus
      properties:
        version:
          $ref: '#/components/schemas/SemverWithV'
        reviewStatus:
          $ref: '#/components/schemas/ReviewStatus'
    ArtifactResponse:
      type: object
      description: Full artifact details including all version history and child artifacts. Admin-only fields (version history,
        release notes) are omitted for non-admin users.
      required:
      - artifactKey
      - name
      - placement
      - artifactType
      - namespace
      - currentVersion
      - newestVersion
      - allOtherVersions
      - allVersions
      properties:
        artifactKey:
          type: string
          description: The unique key that identifies this artifact.
          example: cell-analysis
        name:
          type: string
          description: Human-readable display name for the artifact.
          example: Cell Analysis
        placement:
          $ref: '#/components/schemas/PlacementType'
        parent_sub_menu:
          type: string
          description: The parent navigation group for sub-navigation artifacts. Applies only when placement is subNav.
          example: Workflows
        artifactType:
          $ref: '#/components/schemas/ArtifactType'
        artifactSubType:
          type: string
          description: Sub-classification of the artifact (for example, cv for grouping ai-workflows related to computer vision).
          example: cv
        namespace:
          type: string
          description: The namespace this artifact belongs to.
          example: common
        currentVersion:
          nullable: true
          description: The currently active (approved) version of the artifact, or null if no version is approved.
          allOf:
          - $ref: '#/components/schemas/ArtifactVersionInfo'
        newestVersion:
          description: The most recently published version, regardless of review status.
          $ref: '#/components/schemas/ArtifactVersionInfo'
        inReviewVersion:
          nullable: true
          description: The version currently awaiting review, or null if no version is pending.
          allOf:
          - $ref: '#/components/schemas/ArtifactVersionInfo'
        allOtherVersions:
          type: array
          description: All versions except currentVersion and newestVersion.
          items:
            $ref: '#/components/schemas/ArtifactVersionInfo'
        allVersions:
          type: array
          description: Complete version history for the artifact.
          items:
            $ref: '#/components/schemas/ArtifactVersionInfo'
        children:
          type: array
          description: Child artifacts registered under this parent artifact.
          items:
            $ref: '#/components/schemas/ArtifactResponse'
        description:
          type: string
          description: A text description of the artifact.
          example: Cell image analysis workflow
        releaseNotes:
          type: string
          description: Release notes for the current version. Omitted for non-admin users.
          example: Initial approved release
    ArtifactVersionResponse:
      type: object
      description: Details for a single artifact version, returned when the version query parameter is provided.
      required:
      - artifactKey
      - name
      - placement
      - artifactType
      - namespace
      - version
      - reviewStatus
      properties:
        artifactKey:
          type: string
          description: The unique key that identifies this artifact.
          example: cell-analysis
        name:
          type: string
          description: Human-readable display name for the artifact.
          example: Cell Analysis
        placement:
          $ref: '#/components/schemas/PlacementType'
        artifactType:
          $ref: '#/components/schemas/ArtifactType'
        artifactSubType:
          type: string
          description: Sub-classification of the artifact (for example, cv for computer vision workflows).
          example: cv
        parent_sub_menu:
          type: string
          description: The parent navigation group for sub-navigation artifacts. Applies only when placement is subNav.
          example: Workflows
        namespace:
          type: string
          description: The namespace this artifact belongs to.
          example: common
        version:
          $ref: '#/components/schemas/SemverWithV'
        reviewStatus:
          $ref: '#/components/schemas/ReviewStatus'
        description:
          type: string
          example: Cell image analysis workflow
        releaseNotes:
          type: string
          example: Initial approved release
    SupportedArtifactTypesResponse:
      type: object
      required:
      - artifactTypes
      - description
      properties:
        artifactTypes:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactType'
        description:
          type: string
    SetReviewStatusRequest:
      type: object
      description: Request body for approving or cancelling an artifact version.
      required:
      - artifactKey
      - version
      - reviewStatus
      - artifactType
      properties:
        artifactKey:
          type: string
          description: The unique key of the artifact to update.
          example: cell-analysis
        version:
          $ref: '#/components/schemas/SemverWithV'
        reviewStatus:
          $ref: '#/components/schemas/ReviewStatus'
        artifactType:
          $ref: '#/components/schemas/ArtifactType'
        namespace:
          type: string
          description: The namespace of the artifact. Defaults to common if omitted.
          example: common
        reason:
          type: string
          description: A free-text reason for the status change. Recorded in the audit log.
          example: Scientific review completed
    SetReviewStatusResponse:
      type: object
      required:
      - success
      - reviewStatus
      - message
      properties:
        success:
          type: boolean
        reviewStatus:
          $ref: '#/components/schemas/ReviewStatus'
        message:
          type: string
    ArtifactLogEntry:
      type: object
      properties:
        type:
          type: string
          example: Audit
        orgSlug:
          type: string
          example: acme-corp
        artifactKey:
          type: string
          example: cell-analysis
        artifactType:
          $ref: '#/components/schemas/ArtifactType'
        actor:
          type: string
          description: The identifier of the user who performed the action.
          example: user-123
        version:
          type: string
          example: v1.0.0
        versionSort:
          type: string
          description: Zero-padded sort key used for version ordering. You can ignore this field in most integrations.
          example: '000010000100001'
        action:
          type: string
          description: 'The type of action recorded. PUBLISH: a new version was published. REVIEW_STATUS_CHANGED: a review
            status was updated.'
          enum:
          - PUBLISH
          - REVIEW_STATUS_CHANGED
        from:
          nullable: true
          type: object
          additionalProperties: true
        to:
          type: object
          additionalProperties: true
        reason:
          type: string
        at:
          type: string
          format: date-time
    GetArtifactLogsResponse:
      type: object
      required:
      - success
      - auditLogs
      - message
      properties:
        success:
          type: boolean
        auditLogs:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactLogEntry'
        message:
          type: string
    HealthResponse:
      type: object
      required:
      - status
      - timestamp
      - message
      - version
      - hash
      properties:
        status:
          type: string
          enum:
          - ok
        timestamp:
          type: string
          format: date-time
        message:
          type: string
        version:
          type: string
          example: v1.1.2-pre3
        hash:
          type: string
          example: 2a94b5b
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        error:
          type: string
          example: Bad Request

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.

Updated 29 days ago

Did this page help you?