openapi: 3.2.0
info:
  title: APIHUB Registry – External Search 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: Search
  description: Search functions.
paths:
  /api/v3/search/{searchLevel}:
    parameters:
    - name: searchLevel
      in: path
      required: true
      description: 'Level of object for search.

        '
      schema:
        type: string
        enum:
        - operations
        - documents
        - packages
    post:
      deprecated: true
      x-deprecation-reason: POST /api/v4/search/{searchLevel} shall be used instead.
      x-nc-api-audience: noBWC
      tags:
      - Search
      summary: Global search
      description: Global search by text or custom parameters
      operationId: postSearch
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      requestBody:
        description: Filters for search
        content:
          application/json:
            schema:
              type: object
              required:
              - searchString
              title: searchCommonParams
              description: Common parameters for Global search
              properties:
                searchString:
                  description: Search by common text fields (summary, description, title, etc.).
                  type: string
                  example: Billing account
                packageIds:
                  description: 'List of Package Id(s).

                    * If user specified Workspace(s), then Workspace Id(s) must be transmitted.

                    * If user specified Workspace(s) and Group(s), then Group Id(s) must be transmitted.

                    * If user specified Workspace(s), Group(s) and Package(s) or Workspace(s) and Package(s), then Package Id(s) must be transmitted.

                    '
                  type: array
                  items:
                    type: string
                  example:
                  - QS.CloudQSS.CPQ.Q-TMF
                  - QS.CloudQSS.CPQ.CORE
                versions:
                  description: Package version names.
                  type: array
                  items:
                    type: string
                  example:
                  - '2022.2'
                  - '2022.3'
                statuses:
                  description: List of package version statuses
                  type: array
                  items:
                    $ref: '#/components/schemas/VersionStatusEnum'
                creationDateInterval:
                  description: 'Search interval for the package version publication date.

                    Both dates are included.

                    '
                  type: object
                  properties:
                    startDate:
                      description: Start date of the search.
                      type: string
                      format: date
                      default: '1970-01-01'
                    endDate:
                      description: End date of the search.
                      type: string
                      format: date
                      default: '2050-12-31'
                operationParams:
                  type: object
                  title: ApiSpecificParams
                  description: Search parameters specific for particular API type.
                  required:
                  - apiType
                  oneOf:
                  - type: object
                    description: 'Search parameters specific for REST API.

                      These params shall be used only if apiType in search request equals to REST API.

                      '
                    title: SearchRestParams
                    properties:
                      apiType:
                        description: Type of the API
                        type: string
                        enum:
                        - rest
                      scope:
                        description: Search scope for operation
                        type: array
                        items:
                          type: string
                          enum:
                          - request
                          - response
                      detailedScope:
                        description: Detailed search scope for operation
                        type: array
                        items:
                          type: string
                          enum:
                          - properties
                          - annotation
                          - examples
                      methods:
                        description: Operation method
                        type: array
                        items:
                          type: string
                          enum:
                          - post
                          - get
                          - put
                          - patch
                          - delete
                          - head
                          - options
                          - connect
                          - trace
                        example:
                        - post
                        - get
                  - type: object
                    description: 'Search parameters specific for GraphQL.

                      These params shall be used only if apiType in search request equals to GraphQL.

                      '
                    title: SearchGQLParams
                    properties:
                      apiType:
                        description: Type of the API
                        type: string
                        enum:
                        - graphql
                      scope:
                        type: array
                        items:
                          type: string
                          enum:
                          - argument
                          - property
                          - annotation
                      operationTypes:
                        type: array
                        items:
                          type: string
                          enum:
                          - query
                          - mutation
                          - subscription
            examples: {}
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: Results of the global search list
                type: object
                properties:
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultOperation'
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultDocument'
                  packages:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultPackage'
              examples: {}
        '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: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v4/search/{searchLevel}:
    parameters:
    - name: searchLevel
      in: path
      required: true
      description: 'Level of object for search.

        '
      schema:
        type: string
        enum:
        - operations
        - documents
        - packages
        - ddl
        - mcp
    post:
      x-nc-api-audience: noBWC
      tags:
      - Search
      summary: Global search v4
      description: Global search by text or custom parameters
      operationId: postSearchV4
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      requestBody:
        description: Filters for search
        content:
          application/json:
            schema:
              type: object
              required:
              - searchString
              - workspace
              - status
              title: searchCommonParamsV4
              description: 'Common parameters for Global search v4.

                `apiType` is required when `searchLevel = operations`; it is ignored for `ddl` and `mcp` search levels.

                '
              properties:
                searchString:
                  description: Search text
                  type: string
                  example: Billing account
                apiType:
                  description: Type of the API to search for. Required when `searchLevel = operations`.
                  type: string
                  enum:
                  - rest
                  - graphql
                  - asyncapi
                  - protobuf
                workspace:
                  description: Top-level workspace ID (no dots).
                  type: string
                  example: QS
                status:
                  description: Package version status.
                  allOf:
                  - $ref: '#/components/schemas/VersionStatusEnum'
                packageIds:
                  description: 'List of Package Id(s). Must belong to the specified workspace.

                    '
                  type: array
                  items:
                    type: string
                  example:
                  - QS.CloudQSS.CPQ.Q-TMF
                  - QS.CloudQSS.CPQ.CORE
                versions:
                  description: Package version names.
                  type: array
                  items:
                    type: string
                  example:
                  - '2022.2'
                  - '2022.3'
                creationDateInterval:
                  description: 'Search interval for the package version publication date.

                    Both dates are included.

                    '
                  type: object
                  properties:
                    startDate:
                      description: Start date of the search.
                      type: string
                      format: date
                      default: '1970-01-01'
                    endDate:
                      description: End date of the search.
                      type: string
                      format: date
                      default: '2050-12-31'
            examples: {}
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: Results of the global search list
                type: object
                properties:
                  operations:
                    description: Returned when `searchLevel = operations`.
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultOperation'
                  ddlContracts:
                    description: Returned when `searchLevel = ddl`.
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultDDLContract'
                  mcpContracts:
                    description: Returned when `searchLevel = mcp`.
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultMCPContract'
                  documents:
                    description: Returned when `searchLevel = documents`.
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultDocument'
                  packages:
                    description: Returned when `searchLevel = packages`.
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResultPackage'
              examples: {}
        '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: {}
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
components:
  schemas:
    VersionStatusEnum:
      description: Package version status
      type: string
      enum:
      - draft
      - release
      - archived
    SearchResultDDLContract:
      description: Global search result for a DDL table or view contract; returned when `searchLevel = ddl`.
      title: SearchResultDDLContract
      type: object
      required:
      - packageId
      - name
      - parentPackages
      - version
      - status
      - tableId
      - kind
      properties:
        packageId:
          description: Package unique string identifier (full alias)
          type: string
          example: QS.CloudQSS.CPQ.Q-TMF
        name:
          description: Package name
          type: string
          example: Quote TMF Service
        parentPackages:
          description: Array of parent package names
          type: array
          items:
            type: string
        version:
          description: Package version name
          type: string
          example: 2022.2@5
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        tableId:
          description: DDL table/view logical identifier.
          type: string
          example: public.users
        kind:
          $ref: '#/components/schemas/DdlContractKind'
        schemaName:
          description: SQL schema name.
          type: string
          example: public
        tableName:
          description: Unqualified table or view name.
          type: string
          example: users
    SearchResultMCPContract:
      description: Global search result for an MCP contract entity; returned when `searchLevel = mcp`.
      title: SearchResultMCPContract
      type: object
      required:
      - packageId
      - name
      - parentPackages
      - version
      - status
      - entityId
      - kind
      - mcpEndpoint
      properties:
        packageId:
          description: Package unique string identifier (full alias)
          type: string
          example: QS.CloudQSS.CPQ.Q-TMF
        name:
          description: Package name
          type: string
          example: Quote TMF Service
        parentPackages:
          description: Array of parent package names
          type: array
          items:
            type: string
        version:
          description: Package version name
          type: string
          example: 2022.2@5
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        entityId:
          description: MCP contract logical identifier.
          type: string
          example: https___api_example_com_mcp.tool.get_forecast
        kind:
          $ref: '#/components/schemas/McpContractKind'
        entityName:
          description: MCP entity name.
          type: string
          example: get_forecast
        mcpEndpoint:
          description: MCP endpoint URL.
          type: string
          example: https://api.example.com/mcp
    DdlContractKind:
      title: DDL contract kind
      description: DDL contract entity kind.
      type: string
      enum:
      - table
      - view
    Operation:
      description: Operation object
      title: Operation
      type: object
      required:
      - operationId
      - documentId
      - title
      - apiType
      - apiAudience
      - apiKind
      - versionInternalDocumentId
      properties:
        operationId:
          description: 'Operation unique identifier (slug). Not the same as operationId tag from the OpenAPI file.

            For AsyncAPI 3.0: operationId = normalized_operation_id + "-" + normalized_message_id,

            where operation_id is the key in the root operations map and message_id is the key in the channel''s messages map.

            '
          type: string
          example: get-quoteManagement-v5-quote
        documentId:
          description: Unique string identifier of the document from which the operation is originated
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
        title:
          description: 'Operation summary/title.

            For AsyncAPI 3.0: message.title. If the message has no title, the messageId (key in the channel''s messages map) is used.

            '
          type: string
        apiType:
          $ref: '#/components/schemas/ApiType'
        externalMetadata:
          description: External operation metadata.
          type: object
        deprecated:
          description: 'Operation deprecate flag.

            For AsyncAPI 3.0: derived from x-deprecated extension on Message Object (message-deprecated)

            or Channel Object (channel-deprecated). Native deprecated: true/false exists only for Schema Object in AsyncAPI 3.0.

            '
          type: boolean
          default: false
        apiAudience:
          description: 'Operation''s target audience.

            * internal - APIs are available for integration within product application.

            * external - APIs exposed outside the boundary of product application: solution delivery integrations, 3rd party integrations, customer integrations.

            * unknown - If any value other than internal or external is used, the API is considered as unknown.

            For AsyncAPI 3.0: derived from x-api-audience extension. Channel-level is the default;

            operation-level overrides when present. If neither defines the extension, the audience is external.

            '
          type: string
          enum:
          - internal
          - external
          - unknown
        apiKind:
          description: 'Operation API kind.

            * bwc - API with backward compatibility support (a.k.a. public).

            * no-bwc - API without backward compatibility support (a.k.a. internal).

            * experimental - APIs for feature testing. Usage is not recommended.

            For AsyncAPI 3.0: derived from x-api-kind extension. Channel-level is the default;

            operation-level overrides when present. If neither defines the extension, API Kind is bwc.

            '
          type: string
          enum:
          - bwc
          - no-bwc
          - experimental
          default: bwc
        tags:
          description: 'List of operation tags.

            * in rest, tag is OpenAPI tag.

            * in graphql, tag is root schema type - query, mutation, subscription.

            * in protobuf, tag is service of method.

            '
          type: array
          items:
            type: string
          example:
          - RestControllerV5
        versionInternalDocumentId:
          description: 'Unique string identifier of the preprocessed (validated, references resolved) internal document, where the operation is present. Corresponds to `id` field for the document in `version-internal-documents.json`

            '
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-ref-resolved-json
    ApiType:
      title: apiType
      type: string
      enum:
      - rest
      - graphql
      - protobuf
      - asyncapi
    ProtobufOperation:
      description: Protobuf operation object.
      title: ProtobufOperation
      allOf:
      - $ref: '#/components/schemas/Operation'
      - $ref: '#/components/schemas/ProtobufOperationMeta'
    SearchResultDocument:
      description: Global search result for documents; must be returned when searchLevel = document
      title: SearchResultDocument
      type: object
      required:
      - packageId
      - name
      - parentPackages
      - version
      - status
      - files
      - slug
      - type
      - title
      properties:
        packageId:
          description: Package unique string identifier (full alias)
          type: string
          example: QS.CloudQSS.CPQ.Q-TMF
        name:
          description: Package name
          type: string
          example: Quote TMF Service
        parentPackages:
          description: Array of parent package names
          type: array
          items:
            type: string
        version:
          description: Package version name.
          type: string
          example: 2022.2@5
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        slug:
          description: Published document slug
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
        type:
          description: Type of the specification notation.
          type: string
          enum:
          - openapi-3-1
          - openapi-3-0
          - openapi-2-0
          - json-schema
          - markdown
          - unknown
        title:
          description: Name/title of the document.
          type: string
          example: Quote Integration TMForum Service
        labels:
          description: List of documents labels.
          type: array
          items:
            type: string
          example:
          - TMF
        createdAt:
          description: Date of the package version publication
          type: string
          format: date-time
        content:
          type: string
          description: 'String with search term occurrences in the document.

            If document content does not contain search term, then return N first characters.

            If document is empty, then this property will be empty.

            '
    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
    RestOperationMeta:
      description: Specific parameters for REST operation.
      title: RestOperationMeta
      required:
      - path
      - method
      type: object
      properties:
        path:
          description: Operation endpoint path.
          type: string
          example: /quoteManagement/v5/quote
        method:
          description: Operation method.
          type: string
          enum:
          - post
          - get
          - put
          - patch
          - delete
          - head
          - options
          - connect
          - trace
        title:
          description: Operation summary/title.
          type: string
        customTags:
          description: Custom tags.
          type: object
    SearchResultPackage:
      title: SearchResultPackage
      description: 'Global search result for packages with kind = package; must be returned when searchLevel = package

        * If search term matches the package id/name/description/service name, return the latest published version only.

        * If search term matches the version name/label, return that version.

        '
      type: object
      required:
      - packageId
      - name
      - parentPackages
      - createdAt
      - version
      - revision
      - status
      properties:
        packageId:
          description: Package unique string identifier (full alias)
          type: string
          example: QS.CloudQSS.CPQ.Q-TMF
        name:
          description: Package name
          type: string
          example: Quote TMF Service
        description:
          description: Package description
          type: string
        serviceName:
          description: Service name that package belongs to. Should be equal to service deployment name in kubernetes.
          type: string
        parentPackages:
          description: Array of parent package names
          type: array
          items:
            type: string
        version:
          description: Package version name.
          type: string
          example: 2022.2@5
        latestRevision:
          description: 'true if revision is the latest one.

            '
          type: boolean
          default: false
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        createdAt:
          description: Date of the package version publication
          type: string
          format: date-time
        labels:
          description: List of package version labels
          type: array
          items:
            type: string
    GraphQLOperation:
      description: GraphQL operation object.
      title: GraphQLOperation
      allOf:
      - $ref: '#/components/schemas/Operation'
      - $ref: '#/components/schemas/GraphQLOperationMeta'
    ProtobufOperationMeta:
      description: Specific parameters for Protobuf operation.
      title: GraphQLOperationMeta
      required:
      - type
      - method
      type: object
      properties:
        type:
          description: Operation type
          type: string
          enum:
          - unary
          - serverStreaming
          - clientStreaming
          - bidirectionalStreaming
        method:
          description: Protobuf method name.
          type: string
          example: ListActionLogItems
        title:
          description: Operation title (same as method name but with adding spaces between capital letters)
          type: string
          example: List Action Log Items
        customTags:
          description: Custom tags.
          type: object
    AsyncAPIOperationMeta:
      description: 'Specific parameters for AsyncAPI 3.0 operation.

        An APIHUB Operation for AsyncAPI is the triple (channel, operation, message).

        '
      title: AsyncAPIOperationMeta
      required:
      - action
      - channel
      - protocol
      - asyncOperationId
      - messageId
      type: object
      properties:
        action:
          description: 'AsyncAPI operation action: send or receive.'
          type: string
          enum:
          - send
          - receive
        channel:
          description: 'AsyncAPI channel identifier.

            Uses channel.title if available; otherwise uses channelId (key in the document''s root channels map).

            '
          type: string
          example: User Signup Channel
        protocol:
          description: 'Communication protocol derived from the channel''s first server.

            Expected values: kafka, amqp. Any other protocol value from the spec is displayed as-is.

            If the channel has no server references or the protocol cannot be resolved, the value is "Unknown".

            '
          type: string
          example: kafka
        asyncOperationId:
          description: 'AsyncAPI operationId as defined in the AsyncAPI specification.

            The key in the root operations map that identifies the operation.

            '
          type: string
          example: onUserSignUp
        messageId:
          description: 'AsyncAPI messageId as defined in the AsyncAPI specification.

            The key in the channel''s messages map that identifies the message.

            '
          type: string
          example: userSignedUp
        customTags:
          description: Custom tags.
          type: object
    SearchResultOperation:
      description: 'Global search result for API operations; must be returned when searchLevel = operation

        '
      title: SearchResultOperation
      allOf:
      - oneOf:
        - $ref: '#/components/schemas/RestOperation'
        - $ref: '#/components/schemas/GraphQLOperation'
        - $ref: '#/components/schemas/ProtobufOperation'
        - $ref: '#/components/schemas/AsyncAPIOperation'
      - type: object
        required:
        - packageId
        - name
        - parentPackages
        - version
        - status
        properties:
          packageId:
            description: Package unique string identifier (full alias)
            type: string
            example: QS.CloudQSS.CPQ.Q-TMF
          name:
            description: Package name
            type: string
            example: Quote TMF Service
          parentPackages:
            description: Array of parent package names
            type: array
            items:
              type: string
          version:
            description: Package version name
            type: string
            example: 2022.2@5
          status:
            $ref: '#/components/schemas/VersionStatusEnum'
    GraphQLOperationMeta:
      description: Specific parameters for GraphQL operation.
      title: GraphQLOperationMeta
      required:
      - type
      - method
      type: object
      properties:
        type:
          description: Operation type
          type: string
          enum:
          - query
          - mutation
          - subscription
        method:
          description: GraphQL operation method.
          type: string
          example: getPaymentMethodSpecificationCore
        title:
          description: Operation summary/title.
          type: string
        customTags:
          description: Custom tags.
          type: object
    McpContractKind:
      title: MCP contract kind
      description: MCP discovery contract entity kind.
      type: string
      enum:
      - init
      - tool
      - prompt
      - resource
    RestOperation:
      description: REST operation object.
      title: RestOperation
      allOf:
      - $ref: '#/components/schemas/Operation'
      - $ref: '#/components/schemas/RestOperationMeta'
    AsyncAPIOperation:
      description: AsyncAPI operation object.
      title: AsyncAPIOperation
      allOf:
      - $ref: '#/components/schemas/Operation'
      - $ref: '#/components/schemas/AsyncAPIOperationMeta'
  examples:
    InternalServerError:
      description: 'Example: default internal server error response'
      value:
        status: 500
        code: APIHUB-8000
        reason: InternalServerError
        message: InternalServerError
    IncorrectInputParameters:
      description: Incorrect input parameters
      value:
        status: 400
        code: APIHUB-COMMON-4001
        message: Incorrect input parameters
  parameters:
    page:
      name: page
      in: query
      description: Page number
      schema:
        type: number
        default: 0
    limit:
      name: limit
      in: query
      description: Requested number of resources to be provided in response.
      schema:
        type: number
        default: 100
        maximum: 100
        minimum: 1
  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