openapi: "3.2.0"
info:
  title: Bump.sh Portal Api
  description: |
    The Bump.sh portal API is designed to be used by end-users.

    It is a REST API.
  version: "1.0"
servers:
  - url: https://bump.sh/api/portal/v1
    name: Production
paths:
  /search:
    parameters:
      - $ref: "#/components/parameters/PortalUrl"
    get:
      description: |
        Search across all documentation pages in the portal by keyword.
      parameters:
        - in: query
          name: query
          required: true
          description: |
            Search query string. Matches against page titles, content, and metadata.
          schema:
            type: string
        - in: query
          name: url
          description: |
            Filter results by page. Useful to narrow
            down results of a specific documentation page.
          schema:
            $ref: "#/components/schemas/ResourceUrl"
        - in: query
          name: type
          description: |
            Filter results by object type. Useful to narrow down
            results when looking for a specific kind of documentation
            page.
          schema:
            $ref: "#/components/schemas/PageType"
      responses:
        "200":
          $ref: "#/components/responses/SearchResults"
  /list:
    parameters:
      - $ref: "#/components/parameters/PortalUrl"
    get:
      summary: "List child pages"
      description: |
        List all child pages under a given URL in the portal hierarchy.
      parameters:
        - in: query
          name: url
          schema:
            $ref: "#/components/schemas/ResourceUrl"
      responses:
        "200":
          $ref: "#/components/responses/ListingResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  /fetch:
    parameters:
      - $ref: "#/components/parameters/PortalUrl"
    get:
      summary: "Retrieve full content of documentation pages"
      description: |
        Retrieve the full content of one or more documentation pages by their URLs,
        including code examples (calls, requests and responses examples).
      parameters:
        - in: query
          name: url
          required: true
          schema:
            type:
              - string
              - array[string]
            description: |
              Page URL or list of page URLs to retrieve (1 to 10).
            items:
              $ref: "#/components/schemas/ResourceUrl"
            minItems: 1
            maxItems: 10
          examples:
            single: "https://one.url/path"
            array: ["https://one.url", "https://two.url/path"]
      responses:
        "200":
          $ref: "#/components/responses/PagesResponse"
        "404":
          $ref: "#/components/responses/NotFound"
  # /changelog:
  #   parameters:
  #     - $ref: "#/components/parameters/PortalUrl"
  #   get:
  #     description: |
  #       List changes for a given documentation
  #     parameters:
  #       - $ref: "#/components/parameters/Resource"
  #       - in: query
  #         name: start-date
  #         description: |
  #           Filter changes since the given date
  #         schema:
  #           type: string
  #           format: date
  #       - in: query
  #         name: end-date
  #         description: |
  #           Filter changes until the given date
  #         schema:
  #           type: string
  #           format: date

components:
  responses:
    NotFound:
      description: |
        The resource was not found
    SearchResults:
      description: |
        Returns matching pages with their URL, title, type, and a text
        excerpt. Use this to find specific endpoints, or topics when
        the user asks about a particular feature or concept.
      content:
        "application/json":
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/SearchResult"
              metadata:
                $ref: "#/components/schemas/Metadata"

    ListingResponse:
      description: |
        Returns a summary of each child page (URL, title, type, description) without full content.
      content:
        "application/json":
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/Listing"
    PagesResponse:
      description: |
        Returns the complete page content, title, type, and examples (for operation only).
      content:
        "application/json":
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: "#/components/schemas/Page"
          examples:
            DocumentationPageExample:
              summary: "Documentation page example"
              description: "Output of the /fetch operation, when type is 'api'"
              value: |
                {
                  "data": [
                    {
                      "type": "api",
                      "url": "https://developers.bump.sh/doc/workspace/",
                      "title": "Bump.sh Api",
                      "content": "# Bump.sh Api\nOpenAPI file: https://developers.bump.sh/doc/workspace/source.yaml\n## Description... ",
                      "examples": {}
                    }
                  ]

            OperationPageExample:
              summary: "Operation page example"
              description: "Output of the /fetch operation, when type is 'operation'"
              value: |
                {
                  "data": [
                    {
                      "type": "operation",
                      "url": "https://developers.bump.sh/doc/workspace/operation/operation-post-versions",
                      "title": "Create a new version",
                      "content": "# Create a new version\ **POST /versions** \n\nDeploy a new version for a given documentation",
                      "examples": {
                        "calls": [
                          {
                            "title": "curl",
                            "content": "$ curl \n --request 'https://bump.sh/api/v1/versions' \\n --header \"Authorization: Token $ACCESS_TOKEN\"…"
                          }
                        ],
                        "requests": [
                          {
                            "title": "Create a new version on an existing documentation",
                            "content": "{\"definition\":{\"openapi\":\"3.1.0\",\"info\":{\"title\":\"…\"}}}"
                          },
                          {
                            "title": "Create a new documentation inside a hub",
                            "content": "{\"definition\":{\"openapi\":\"3.1.0\",\"info\":{\"title\":\"…\"}},\"hub\":\"my_hub_slug\"}"
                          }
                        ],
                        "responses": [
                          {
                            "title": "generated",
                            "content": "{\"id\":\"2361df99-3467-4c80-a0cc-45c9fe565812\",\"doc_id\":\"3ef8f52f-9056-4113-840e-2f7183b90e06\",\"doc_public_url\":\"https://bump.sh/doc/my-own-documentation\"}",
                            "status": 201
                          },
                          {
                            "title": "generated",
                            "content": "{\"message\":\"You need to upgrade your subscription plan to perform this request.\"}",
                            "status": 400
                          }
                        ]
                      }
                    }
                  ]
                }
  parameters:
    PortalUrl:
      in: header
      name: Portal-Url
      required: true
      schema:
        type: string
        description: |
          A url of public portal:
            - E.g. for a Documentation `https://developers.bump.sh`
            - E.g. for a Hub `https://www.elastic.co/docs/api`
            - E.g. for an Organization `https://apidocs.lastminute.com/`
      examples:
        docUrl: "https://developers.bump.sh/doc/workspace/"
        hubUrl: "https://www.elastic.co/docs/api/"
        orgaUrl: "https://apidocs.lastminute.com/"

  schemas:
    SearchResult:
      allOf:
        - $ref: "#/components/schemas/PageMetadata"
        - type: object
          properties:
            excerpt:
              type: string
              description: "Excerpt of the page matching the search query"
    Listing:
      allOf:
        - $ref: "#/components/schemas/PageMetadata"
        - type: object
          properties:
            description:
              type: string
              description: "Description of the page limited to the first 180 characters"
    PageType:
      # TODO: 'type' to be clarified. Is it the same as the input
      # of the /search operation?
      type: string
      enum:
        - "hub"
        - "api"
        - "guide"
        - "group"
        - "operation"
        - "request"
        - "response"
        - "model"
        - "message"
        - "binding"
        - "property"
    PageMetadata:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/PageType"
        url:
          type: string
          description: "Canonical URL of the page"
        title:
          type: string
    Page:
      allOf:
        - $ref: "#/components/schemas/PageMetadata"
        - type: object
          properties:
            content:
              type: string
              example: |
                # Markdown content

                The content of the page in **markdown format**.
            examples:
              type: object
              description: |
                Examples extracted from the document.
                Valid only when type is 'operation'.
              properties:
                calls:
                  type: array
                  description : |
                    List of all codeSamples examples, including our 'curl' generated example.
                  items:
                    $ref: "#/components/schemas/ResourceExample"
                requests:
                  description : |
                    Take the operation.body (by default application/json, else the first content-type).
                    Returns the list of all request examples (headers and body)
                  type: array
                  items:
                    $ref: "#/components/schemas/ResourceExample"
                responses:
                  type: array
                  description: |
                    For each response, take the response.body (by default application/json, else the first content-type).
                    Returns the list of all response examples (headers and body). Add the response status code as property 'status'.
                  items:
                    allOf:
                      - $ref: "#/components/schemas/ResourceExample"
                      - type: object
                        properties:
                          status:
                            type: integer
                            description: Response status code
                            example: 200
    Metadata:
      type: object
      required:
        - total
      properties:
        total:
          type: integer
          description: Total number available results, ignoring filters.
    ResourceUrl:
      type: string
      description: |
        Use a target page URL returned by either the `GET /search` or
        `GET /list` operations.
    ResourceExample:
      type: object
      properties:
        title:
          type: string
          description: Title of the example
          title: FooExample
        content:
          type: string
          description: Content of the example
          example: |
            "{\"message\":\"Hello, world!\"}"