openapi: 3.2.0
info:
  title: APIHUB Registry – External Ephemeral Files API
  description: 'Public-facing API contract for APIHUB. This API is intended for external and integration clients and covers package/catalog operations, publication workflows, search, user/profile actions, and selected administration capabilities secured by APIHUB authentication schemes.

    '
  contact:
    name: Netcracker Opensource Group
    email: opensourcegroup@netcracker.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2026.1'
  x-api-kind: BWC
servers:
- url: https://{apihub}.qubership.org
  description: Primary APIHUB server endpoint (use the apihub variable to select production, development, or staging).
  variables:
    apihub:
      description: APIHUB subdomain/environment selector (apihub=production, dev.apihub=development, staging.apihub=staging).
      enum:
      - apihub
      - dev.apihub
      - staging.apihub
      default: apihub
security:
- BearerAuth: []
- CookieAuth: []
- api-key: []
- PersonalAccessToken: []
tags:
- name: Ephemeral Files
  description: 'APIs for short-lived file downloads. Files are stored temporarily on the server and accessed via signed tokens embedded in producer responses (e.g. AI chat assistant markdown links).

    '
paths:
  /api/v1/ephemeral-files/{fileId}:
    parameters:
    - name: fileId
      in: path
      required: true
      description: Opaque identifier of an ephemeral file.
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Ephemeral Files
      summary: Download an ephemeral file.
      description: 'Downloads a short-lived file stored by the backend. Producers (such as the AI chat assistant) embed a signed download URL into their response; other subsystems can reuse the same mechanism for exports, reports, and similar artefacts.

        The endpoint is served without session authentication; instead, access is authorized via a short-lived signed token passed in the `token` query parameter. The token lifetime is a server-side setting and is not published to the client.

        '
      operationId: downloadEphemeralFile
      security: []
      parameters:
      - name: token
        in: query
        required: true
        description: Short-lived signed access token scoped to this file. Opaque to the client — issued by the server as part of the download URL and simply echoed back.
        schema:
          type: string
      responses:
        '200':
          description: File contents
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            Content-Disposition:
              schema:
                type: string
                description: Suggested file name for saving the attachment.
                example: attachment; filename="report.csv"
            Content-Type:
              schema:
                type: string
                description: Original MIME type of the file if known, otherwise `application/octet-stream`.
        '401':
          description: Token missing, malformed or signature invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                EphemeralFileTokenMissing:
                  $ref: '#/components/examples/EphemeralFileTokenMissing'
                EphemeralFileTokenInvalid:
                  $ref: '#/components/examples/EphemeralFileTokenInvalid'
        '404':
          description: File not found or already cleaned up.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                EphemeralFileNotFound:
                  $ref: '#/components/examples/EphemeralFileNotFound'
        '410':
          description: 'Token expired. The browser will surface this as a failed download; the client does not need to handle it specially.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                EphemeralFileTokenExpired:
                  $ref: '#/components/examples/EphemeralFileTokenExpired'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
components:
  examples:
    EphemeralFileTokenMissing:
      description: Download token query parameter missing.
      value:
        status: 401
        code: APIHUB-EF-3003
        message: Missing token query parameter
    EphemeralFileTokenInvalid:
      description: Download token invalid or not valid for the requested file.
      value:
        status: 401
        code: APIHUB-EF-3002
        message: Invalid download token
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    EphemeralFileNotFound:
      description: Ephemeral file not found or already cleaned up.
      value:
        status: 404
        code: APIHUB-EF-3001
        message: ephemeral file with fileId = $fileId not found
    EphemeralFileTokenExpired:
      description: Signed download token expired.
      value:
        status: 410
        code: APIHUB-EF-4101
        message: download token expired, please request the file again
  schemas:
    ErrorResponse:
      description: Standard error response returned for failed requests. Includes HTTP status, internal error code, human-readable message, optional message parameters, and optional debug details (non-production only).
      type: object
      properties:
        status:
          description: HTTP status code as an integer; expected to match the actual HTTP response status.
          type: number
        code:
          description: Internal string error code. Mandatory in response.
          type: string
        message:
          description: Human-readable error message describing what went wrong; intended for diagnostics and safe client display.
          type: string
        params:
          type: object
          description: Optional key/value parameters used to format or contextualize the error message (for example, identifiers or field names).
          example:
            id: 12345
            type: string
        debug:
          description: Optional debug details (for example, stack traces). Returned only in development/test environments when verbose logging is enabled; do not rely on this field in production because it may contain sensitive data.
          type: string
      required:
      - status
      - code
      - message
  securitySchemes:
    BearerAuth:
      type: http
      description: 'Bearer token authentication (JWT). Default security scheme for API usage. Provide Authorization: Bearer <token>.'
      scheme: bearer
      bearerFormat: JWT
    CookieAuth:
      type: apiKey
      in: cookie
      name: apihub-access-token
      description: Authentication via the `apihub-access-token` cookie.
    api-key:
      type: apiKey
      description: API key authentication. Send the key in the api-key header.
      name: api-key
      in: header
    BasicAuth:
      type: http
      description: Login/password authentication.
      scheme: basic
    PersonalAccessToken:
      type: apiKey
      description: Personal access token authentication. Send the token in the X-Personal-Access-Token header; use for user-issued/script access.
      name: X-Personal-Access-Token
      in: header
    RefreshTokenAuth:
      type: apiKey
      in: cookie
      name: apihub-refresh-token
      description: Authentication via refresh token cookie
externalDocs:
  description: Find out more about this project and repository documentation
  url: https://github.com/Netcracker/qubership-apihub