Qubership APIHUB Registry API

openapi: 3.0.3
info:
  title: APIHUB Registry – External 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
externalDocs:
  description: Find out more about this project and repository documentation
  url: https://github.com/Netcracker/qubership-apihub
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: Auth
    description: APIs for auth integrations.
  - name: Packages
    description: APIs for the package management.
  - name: Publish
    description: Publish version API
  - name: Versions
    description: Published package versions API.
  - name: Export
    description: Export API documentation.
  - name: Users
    description: APIs for the user operations.
  - name: Search
    description: Search functions.
  - name: Admin
    description: APIs for technical administration.
  - name: Integrations
    description: APIs for git integrations.
  - name: Roles
    description: APIs for role management.
  - name: Operations
    description: Operations APIs.
  - name: Contracts
    description: DDL and MCP contract APIs.
  - name: Documents
    description: Documents APIs.
  - name: Changes
    description: Changes APIs.
  - name: TryIt
    description: API for 'try it' functionality
  - name: Operation groups
    description: Operation groups
  - name: User profile
    description: APIs for user's personal settings.
  - name: Custom
    description: Custom APIs.
  - name: Internal Documents
    description: APIs for internal documents management.
  - name: AI Chat
    description: |
      APIs for AI chat assistant.
      Each user has their own chat list; chats are persisted on the server with a configurable TTL and pinning support.
      Conversations support streaming responses (SSE) and automatic context compaction (old messages are re-packed into a summary when the conversation approaches the model's context window, so that older facts are preserved instead of being silently dropped by the LLM).
  - 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/system/info":
    get:
      tags:
        - Custom
      summary: Get system info.
      description: Get system info.
      operationId: getInfo
      parameters: []
      responses:
        "200":
          description: Successful execution
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemInfo"
              examples:
                SystemInfo:
                  $ref: "#/components/examples/SystemInfo"
        "500":
          $ref: "#/components/examples/InternalServerError"
  "/api/v1/system/configuration":
    get:
      tags:
        - Auth
      summary: System configuration
      deprecated: true
      description: Global parameters of system configuration.
      operationId: getSystemConfiguration
      security: [{}]
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - autoRedirect
                properties:
                  ssoIntegrationEnabled:
                    type: boolean
                  autoRedirect:
                    type: boolean
                  defaultWorkspaceId:
                    description: Id of the workspace, which is used by default while working with the system.
                    type: string
                    example: WSPACE1
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v2/system/configuration":
    get:
      tags:
        - Auth
      summary: System configuration
      description: Global parameters of system configuration.
      operationId: getSystemConfigurationV2
      security: [{}]
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - authConfig
                properties:
                  defaultWorkspaceId:
                    description: Id of the workspace, which is used by default while working with the system.
                    type: string
                    example: WSPACE1
                  authConfig:
                    type: object
                    required:
                      - identityProviders
                    properties:
                      identityProviders:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          required:
                            - id
                            - type
                            - displayName
                            - imageSvg
                            - loginStartEndpoint
                          properties:
                            id:
                              type: string
                            type:
                              type: string
                              enum: [internal, external]
                            displayName:
                              type: string
                            imageSvg:
                              type: string
                            loginStartEndpoint:
                              type: string
                            refreshTokenEndpoint:
                              type: string
                      autoLogin:
                        type: boolean
                  extensions:
                    description: List of enabled extension services for apihub
                    type: array
                    items:
                      description: Extension item
                      type: object
                      properties:
                        name:
                          description: Unique name of the extension service
                          type: string
                          example: linter
                        baseUrl:
                          description: URL of the extension service
                          type: string
                          example: http://example.com
                        pathPrefix:
                          description: path for routing
                          type: string
                          example: api-linter
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  /api/v1/logout:
    post:
      tags:
        - Auth
      summary: User logout
      description: Logs out the authenticated user and invalidates all active sessions.
      operationId: logoutUser
      security:
        - BearerAuth: []
        - CookieAuth: []
      responses:
        "204":
          description: No content
          content: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: "#/components/examples/Unauthorized"
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v1/export":
    post:
      tags:
        - Export
      summary: Async export of version, document or operations group
      description: |
        Start export of package version, one document or operations group. Use ```GET /api/v1/export/{exportId}/status``` to get status of export and exported file itself.\
        Export of document is currently available for documents with type openapi-3-1, openapi-3-0, or openapi-2-0 and is intended to retrieve content with some transformations. For other document types, use GET /api/v2/packages/{packageId}/versions/{version}/files/{slug} to obtain the original document content.\
        Export of operations group is currently available for groups with apiType = REST, GraphQL or AsyncAPI.
      operationId: postExport
      requestBody:
        description: |
          Defines an entity that shall be exported and export settings.\
          The following entities can be exported:
            - **version** - export of all documents from the version.
            - **OpnAPI document** - export of one specific document with type openapi-3-1, openapi-3-0, or openapi-2-0.
            - **REST operations group** - export of operations group. Only operations group with apiType = REST can be exported.
            - **GraphQL operations group** - export of operations group. Only operations group with apiType = GraphQL can be exported.
            - **AsyncAPI operations group** - export of operations group. Only operations group with apiType = AsyncAPI can be exported.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/ExportVersion"
                - $ref: "#/components/schemas/ExportRestDocument"
                - $ref: "#/components/schemas/ExportRestOperationsGroup"
                - $ref: "#/components/schemas/ExportGraphqlOperationsGroup"
                - $ref: "#/components/schemas/ExportAsyncapiOperationsGroup"
              discriminator:
                propertyName: exportedEntity
      responses:
        "202":
          description: Export process started
          content:
            application/json:
              schema:
                type: object
                properties:
                  exportId:
                    type: string
                    description: Export process Id
                    format: uuid
                    example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                IncorrectInputParams:
                  $ref: "#/components/examples/IncorrectInputParameters"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples: {}
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples: {}
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                PackageNotFound:
                  $ref: "#/components/examples/PackageNotFound"
                VersionNotFound:
                  $ref: "#/components/examples/VersionNotFound"
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                InternalServerError:
                  $ref: "#/components/examples/InternalServerError"
  "/api/v1/export/{exportId}/status":
    parameters:
      - name: exportId
        description: Export process id.
        in: path
        required: true
        schema:
          type: string
          format: uuid
          example: 9c8e9045-dd9c-4946-b9e4-e05e3f41c4cc
    get:
      tags:
        - Export
      summary: Get status of async export
      description: |
        Get status of async export operation (POST /api/v1/export). If file for export is ready, then it will be returned. The resulting file is stored temporarily; once deleted, it needs to be re-calculated.
      operationId: getExportIdStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    description: |
                      Export process status.\
                      "none" status means - not started.
                    type: string
                    enum:
                      - running
                      - error
                      - none
                  message:
                    description: The message for **error** status.
                    type: string
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: |
                  File to download.
          headers:
            Content-Disposition:
              schema:
                type: string
                description: |
                  File name for exported entity.
                    - if version was exported: <packageId>_<version>.<extension>
                    - if document was exported: <packageId>_<version>_<file name>.<extension>
                    - if operations group was exported: <packageId>_<version>_<group name>.<extension>
                example: attachment; filename="PCKG1.zip"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncorrectInputParams:
                  $ref: '#/components/examples/IncorrectInputParameters'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  $ref: "#/components/examples/Unauthorized"
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                PackageNotFound:
                  $ref: '#/components/examples/PackageNotFound'
                VersionNotFound:
                  $ref: '#/components/examples/VersionNotFound'
                FileNotFound:
                  $ref: '#/components/examples/FileNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v4/activity:
    get:
      tags:
        - Packages
      summary: Get activity history
      description: |
        Get activity history. Return the last N events in descending date order.
      operationId: getActivityV4
      parameters:
        - name: onlyFavorite
          description: |
            * If true, then only events from packages that are favorites for the current user shall be returned (including all child groups/packages/dashboards for favorite groups/workspaces)
            * If false, events for all packages shall be returned.
          in: query
          schema:
            type: boolean
            default: false
        - name: onlyShared
          in: query
          description: filter only shared packages
          schema:
            type: boolean
            default: false
        - name: kind
          in: query
          description: |
            Filter by package kind.
            The list of values is acceptable. In this case, the following pattern will be used: ```?kind=group,package,dashboard```.
          schema:
            type: array
            items:
              type: string
              enum:
                - workspace
                - group
                - package
                - dashboard
            example: [group, package, dashboard]
        - name: types
          description: |
            Filter for events by group types:
            * package_members - grant_role, update_role, delete_role.
            * package_security - generate_api_key, revoke_api_key.
            * new_version - publish_new_version.
            * package_version - patch_version_meta, delete_version, publish_new_revision, delete_revision.
            * package_management - create_package, delete_package, patch_package_meta.
            * operations_group - create_manual_group, delete_manual_group, update_operations_group_parameters
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - package_members
                - package_security
                - new_version
                - package_version
                - package_management
                - operations_group
        - name: textFilter
          in: query
          description: Filter by userName/packageName
          schema:
            type: string
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/page"
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      required:
                        - date
                        - principal
                        - packageId
                        - packageName
                        - kind
                        - params
                      properties:
                        date:
                          description: Date when event was generated
                          type: string
                          format: date-time
                        principal:
                          $ref: "#/components/schemas/ActivityHistoryPrincipal"
                        packageId:
                          description: Package unique string identifier (full alias)
                          type: string
                        packageName:
                          description: Package name
                          type: string
                        kind:
                          description: Package kind
                          type: string
                          enum:
                            - workspace
                            - group
                            - package
                            - dashboard
                        eventType:
                          description: Activity event type
                          type: string
                          enum:
                            - generate_api_key
                            - revoke_api_key
                            - create_package
                            - delete_package
                            - grant_role
                            - delete_role
                            - update_role
                            - publish_new_version
                            - delete_version
                            - delete_revision
                            - publish_new_revision
                            - patch_version_meta
                            - patch_package_meta
                            - create_manual_group
                            - delete_manual_group
                            - update_operations_group_parameters
                            - update_document_shareability
                        params:
                          type: object
                          description: Events specific params
                          oneOf:
                            - type: object
                              title: ParamsForGrantAndDeleteRole
                              description: params for grant_role and delete_role events
                              required:
                                - memberId
                                - memberName
                                - roles
                              properties:
                                memberId:
                                  description: Login of the member
                                  type: string
                                  example: user1221
                                memberName:
                                  description: User which was added/deleted to/from package with some role(s)
                                  type: string
                                  example: John Doe
                                roles:
                                  type: array
                                  items:
                                    $ref: "#/components/schemas/Role"
                            - type: object
                              title: ParamsForUpdateRole
                              description: params for update_role event
                              required:
                                - memberId
                                - memberName
                              properties:
                                memberId:
                                  description: Login of the member
                                  type: string
                                  example: user1221
                                memberName:
                                  description: User which was added/deleted to/from package with some role(s)
                                  type: string
                                  example: John Doe
                            - type: object
                              title: ParamsForPublishAndDeleteVersion
                              description: params for publish_new_version and delete_version events
                              required:
                                - version
                                - status
                              properties:
                                version:
                                  description: Package version name.
                                  type: string
                                  example: "22.3"
                                status:
                                  $ref: "#/components/schemas/VersionStatusEnum"
                            - type: object
                              title: ParamsForPublishNewRevision
                              description: params for publish_new_revision event
                              required:
                                - version
                                - revision
                                - status
                              properties:
                                version:
                                  description: Package version name.
                                  type: string
                                  example: "22.3"
                                revision:
                                  description: Number of the revision.
                                  type: integer
                                  format: int32
                                  example: 3
                                status:
                                  $ref: "#/components/schemas/VersionStatusEnum"
                            - type: object
                              title: ParamsForUpdateVersionMeta
                              description: params for patch_version_meta event
                              required:
                                - version
                                - versionMeta
                              properties:
                                version:
                                  description: Package version name.
                                  type: string
                                  example: "22.3"
                                versionMeta:
                                  description: List of parameters that was updated in version
                                  type: array
                                  items:
                                    type: string
                                    enum:
                                      - status
                                      - label
                            - type: object
                              title: ParamsForPatchPackageMeta
                              description: params for patch_package_meta event
                              required:
                                - packageMeta
                              properties:
                                packageMeta:
                                  description: List of parameters that was updated in package
                                  type: array
                                  items:
                                    type: string
                                    enum:
                                      - name
                                      - description
                                      - serviceName
                                      - defaultRole
                            - type: object
                              title: ParamsForPostDeleteManualGroups
                              description: |
                                params for the following events:
                                * create_manual_group
                                * deleted_manual_group
                              required:
                                - version
                                - groupName
                                - apiType
                              properties:
                                version:
                                  description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                  type: string
                                  example: "22.3@2"
                                notLatestRevision:
                                  type: boolean
                                  default: false
                                  description: If parameter is not returned, then it is latest revision.
                                groupName:
                                  description: Manual group name
                                  type: string
                                apiType:
                                  type: string
                                  enum:
                                    - rest
                                    - graphql
                                    - protobuf
                                    - asyncapi
                            - type: object
                              title: ParamsForPatchOperationsGroup
                              description: |
                                params for the update_operations_group_parameters event
                              required:
                                - version
                                - groupName
                                - groupsParams
                                - isPrefixGroup
                                - apiType
                              properties:
                                version:
                                  description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                  type: string
                                  example: "22.3@2"
                                apiType:
                                  type: string
                                  enum:
                                    - rest
                                    - graphql
                                    - asyncapi
                                notLatestRevision:
                                  description: If parameter is not returned, then it is latest revision.
                                  type: boolean
                                  default: false
                                groupName:
                                  description: Manual group name
                                  type: string
                                groupsParams:
                                  description: List of parameters that was updated in group
                                  type: array
                                  items:
                                    type: string
                                    enum:
                                      - name
                                      - description
                                      - template
                                      - operations
                                isPrefixGroup:
                                  type: boolean
                                  description: true - if the group created automatically via restGroupingPrefix.
                            - type: object
                              title: ParamsForDeleteRevision
                              description: |
                                params for delete_revision event
                              required:
                                - version
                                - status
                              properties:
                                version:
                                  description: Package version name with revision. The <version>@<revision> format is used.
                                  type: string
                                  example: "4@2"
                                status:
                                  $ref: "#/components/schemas/VersionStatusEnum"
                            - type: object
                              title: ParamsForUpdateDocumentShareability
                              description: params for update_document_shareability event
                              required:
                                - version
                                - documentDisplayName
                                - shareabilityStatus
                              properties:
                                version:
                                  description: Package version name. The <version>@<revision> mask is used to return the revision number.
                                  type: string
                                  example: "22.3@2"
                                notLatestRevision:
                                  type: boolean
                                  default: false
                                  description: If parameter is not returned, then it is latest revision.
                                documentDisplayName:
                                  description: Title + version of the document whose shareability was updated
                                  type: string
                                  example: "API Specification 1.0.0"
                                shareabilityStatus:
                                  description: New shareability status
                                  type: string
                                  enum:
                                    - shareable
                                    - non-sharea

# --- truncated at 32 KB (524 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/netcracker/refs/heads/main/openapi/netcracker-qubership-apihub-registry-openapi.yml