Netcracker Documents API

openapi: 3.2.0
info:
  title: APIHUB Registry – External Documents 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: Documents
  description: Documents APIs.
paths:
  /api/v2/packages/{packageId}/versions/{version}/documents:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    get:
      tags:
      - Documents
      summary: Get version documents
      description: "Get list of documents in a version. The result depend on the package.kind:\n* For package.kind: package - return the list of version documents.\n* For package.kind: dashboard - return the list of all referenced dashboards and their referenced packages in recursion.\n  The returned list will contain only leaves - referenced packages of the lowest level with their published documents.\n"
      operationId: getPackagesIdVersionsIdDocuments
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/apiTypeQueryParam'
      - name: contractType
        in: query
        description: 'Filter documents by contract type.

          Mutually exclusive with `apiType`: specify at most one of `apiType` / `contractType` (if both are specified then 400 will be returned).

          '
        schema:
          type: string
          enum:
          - ddl
          - mcp
      - name: skipRefs
        in: query
        description: 'If false and package has references, then package references (including references to the deleted package versions) shall be resolved.

          '
        schema:
          type: boolean
          default: false
      - name: textFilter
        in: query
        description: Filter by document title.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: List of documents in a package.
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/PackageVersionFile'
                      - type: object
                        properties:
                          packageRef:
                            description: 'Parent package and version link. Created by the concatenation of the packageId and version name with At sign.

                              '
                            type: string
                            example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                  packages:
                    $ref: '#/components/schemas/PackagesMap'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}/documents/{slug}:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/slug'
    get:
      tags:
      - Documents
      summary: Get document details
      description: Get the published content object's details by ID.
      operationId: getPackagesIdVersionsIdDocumentsSlugV2
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PackageVersionFile'
                - type: object
                  properties:
                    description:
                      description: Document description.
                      type: string
                    info:
                      description: Info object from openapi document
                      type: object
                    externalDocs:
                      description: External documentation object from openapi document
                      type: object
                    operations:
                      description: List of the operations in a file without operation's data.
                      type: array
                      items:
                        oneOf:
                        - $ref: '#/components/schemas/RestOperation'
                        - $ref: '#/components/schemas/GraphQLOperation'
                        - $ref: '#/components/schemas/ProtobufOperation'
                        - $ref: '#/components/schemas/AsyncAPIOperation'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v2/packages/{packageId}/versions/{version}/documents/{slug}/shareability:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/slug'
    patch:
      tags:
      - Documents
      summary: Update document shareability
      description: Update the shareability property of a published document. Only available to package owners and admins.
      operationId: updateDocumentShareability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - status
              properties:
                status:
                  description: The shareability status to set
                  type: string
                  enum:
                  - shareable
                  - non-shareable
                  - unknown
      responses:
        '204':
          description: Shareability updated successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/shareability/bulk-update:
    post:
      tags:
      - Documents
      summary: Bulk update document shareability
      description: 'Upload a shareability report xlsx file to bulk-update shareability statuses for all documents with changed values.

        `document_shareability_management` is required for all packages listed in the report.

        '
      operationId: bulkUpdateDocumentShareability
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: Shareability report xlsx file
      responses:
        '204':
          description: Shareability statuses updated successfully
        '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'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    - $ref: '#/components/parameters/apiType'
    - name: groupName
      in: path
      required: true
      description: Name of the operation group
      schema:
        type: string
    get:
      tags:
      - Documents
      summary: Get documents of operations from operation group.
      description: 'Get list of package version documents of operations from operation group.

        '
      operationId: getPackagesIdVersionsIdTransformationDocumentsV3
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: List of documents in a package.
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      allOf:
                      - $ref: '#/components/schemas/PackageTransformationFile'
                      - type: object
                        properties:
                          packageRef:
                            description: 'Referenced package and version link. Created by the concatenation of the packageId and version name with At sign.\

                              Parameter is required if operation is called for the package with kind = dashboard; otherwise, parameter will not be returned.

                              '
                            type: string
                            example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                  packages:
                    $ref: '#/components/schemas/PackagesMap'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
  /api/v3/packages/{packageId}/versions/{version}/references:
    parameters:
    - $ref: '#/components/parameters/packageId'
    - $ref: '#/components/parameters/version'
    get:
      tags:
      - Documents
      summary: Get version references
      description: 'Get flat list of all version references

        '
      operationId: getPackagesIdVersionsIdReferencesv3
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                description: List of references.
                type: object
                properties:
                  references:
                    type: array
                    items:
                      type: object
                      properties:
                        packageRef:
                          description: 'Referenced package and version link.

                            Created by the concatenation of the packageId and version name with At sign.

                            '
                          type: string
                          example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                        parentPackageRef:
                          description: 'Parent referenced package and version link.

                            Created by the concatenation of the packageId and version name with At sign.

                            '
                          type: string
                          example: QS.CloudQSS.CPQ.Q-TMF@2023.2
                        excluded:
                          description: All excluded refs will be ignored (but will still be visible for package version).
                          type: boolean
                  packages:
                    $ref: '#/components/schemas/PackagesMap'
              examples: {}
        '301':
          description: Moved Permanently
          headers:
            Location:
              schema:
                type: string
              description: Current ednpoint with new packageId of moved package
            X-New-Package-Id:
              schema:
                type: string
              description: New packageId of moved package
        '401':
          description: Unauthorized
          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'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                InternalServerError:
                  $ref: '#/components/examples/InternalServerError'
components:
  parameters:
    slug:
      name: slug
      in: path
      description: File unique string identifier
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9-]
        example: qitmf-v5-11-json
    packageId:
      name: packageId
      in: path
      description: Package unique identifier (full alias)
      required: true
      schema:
        type: string
        example: QS.CloudQSS.CPQ.Q-TMF
    apiType:
      name: apiType
      description: Type of the API.
      in: path
      required: true
      schema:
        type: string
        enum:
        - rest
        - graphql
        - protobuf
        - asyncapi
    apiTypeQueryParam:
      name: apiType
      in: query
      description: 'Filter documents by type of the API.

        Mutually exclusive with `contractType`: specify at most one of `apiType` / `contractType` (if both are specified then 400 will be returned).

        '
      schema:
        type: string
        enum:
        - rest
        - graphql
        - protobuf
        - asyncapi
    version:
      name: version
      in: path
      description: Package version
      required: true
      schema:
        type: string
        example: '2022.3'
    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
  schemas:
    VersionStatusEnum:
      description: Package version status
      type: string
      enum:
      - draft
      - release
      - archived
    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
    SpecificationType:
      title: type
      description: Type of the specification notation.
      type: string
      enum:
      - openapi-3-1
      - openapi-3-0
      - openapi-2-0
      - json-schema
      - markdown
      - graphql-schema
      - graphapi
      - introspection
      - protobuf-3
      - asyncapi-3-0
      - ddl
      - mcp
      - unknown
    ApiType:
      title: apiType
      type: string
      enum:
      - rest
      - graphql
      - protobuf
      - asyncapi
    PackagesMap:
      description: 'A map of referenced package versions to the package version objects.

        The key is `packageId@version@revision` — three `@`-separated segments (note: the `version` field

        of each value is `version@revision`, only two segments).

        '
      type: object
      additionalProperties:
        $ref: '#/components/schemas/PackageVersionRef'
      example:
        QS.CloudQSS.CPQ.Q-TMF@2023.2@3:
          refId: QS.CloudQSS.CPQ.Q-TMF
          kind: package
          name: Quote Management TMF648
          version: 2023.2@3
          status: release
          parentPackages:
          - qubership
          - Qubership JSS
          - Sample Management
          deletedAt: '2023-05-30T17:17:11.755146Z'
          deletedBy: user1221
          notLatestRevision: true
    ProtobufOperation:
      description: Protobuf operation object.
      title: ProtobufOperation
      allOf:
      - $ref: '#/components/schemas/Operation'
      - $ref: '#/components/schemas/ProtobufOperationMeta'
    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
    PackageVersionRef:
      description: Package version reference
      type: object
      title: Referenced package version
      required:
      - refId
      - kind
      - name
      - version
      - status
      properties:
        refId:
          description: Referenced package Id.
          type: string
          example: QS.CloudQSS.CPQ.CORE
        kind:
          description: Package kind
          type: string
          enum:
          - package
          - dashboard
        name:
          description: Name of the referenced package
          type: string
          example: Quote Management TMF648
        version:
          description: Referenced package version number. The <version>@<revision> mask is used to return the revision number.
          type: string
          example: 2022.2@5
        status:
          $ref: '#/components/schemas/VersionStatusEnum'
        parentPackages:
          description: Array of parent package names
          type: array
          items:
            type: string
        deletedAt:
          description: date when package version was deleted package version
          type: string
          format: date-type
          example: '2023-05-30T17:17:11.755146Z'
        deletedBy:
          description: user who deleted package version
          type: string
          example: user1221
        notLatestRevision:
          type: boolean
          default: false
    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
    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
    PackageTransformationFile:
      description: Parameters of published file in package version
      type: object
      title: Package version file
      required:
      - fileId
      - filename
      - slug
      - type
      - format
      - title
      properties:
        fileId:
          type: string
          description: File name.
          example: qitmf-v5.11.json
        filename:
          type: string
          description: File name (slug+extension).
          example: qitmf-v5.11.json
        slug:
          description: Published file slug
          type: string
          pattern: ^[a-z0-9-]
          example: qitmf-v5-11-json
        type:
          $ref: '#/components/schemas/SpecificationType'
        format:
          $ref: '#/components/schemas/DocumentFormat'
        title:
          description: Name/title of the document.
          type: string
          example: Quote Integration TMForum Service
        version:
          description: Document version
          type: string
          example: 1.0.1
        labels:
          description: List of file labels.
          type: array
          items:
            type: string
          example:
          - TMF
        description:
          description: Document description
          type: string
        includedOperationIds:
          description: List of operation IDs included to specified operation group
          type: array
          items:
            type: string
          example:
          - get-quoteManagement-v5-quote
          - post-quoteManagement-v5-quote
        data:
          description: Content of the operation as a JSON object
          type: object
        shareabilityStatus:
          description: Document shareability status
          type: string
          enum:
          - shareable
          - non-shareable
          - unknown
          default: unknown
      

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