DeveloperHub Version API

openapi: 3.2.0
info:
  title: Version API
  description: API to manage your %product% resources programmatically. Using these APIs, you are able to manage pages, integrate with CI/CD, and retrieve resources among other operations.
  contact: {}
  version: 1.1.0
servers:
- url: https://api.developerhub.io/api/v1
  variables: {}
security:
- Api-Key: []
tags:
- name: Version
  description: Operations for listing, updating, cloning, and reporting on project versions.
paths:
  /version:
    get:
      tags:
      - Version
      summary: Lists all project versions
      description: 'Lists all project versions that are accessible through the API Key. This will only list non-deleted versions. Rate limit: 60 in 60 minutes.'
      operationId: list_versions
      parameters: []
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Version'
                description: OK
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /version/{id}:
    put:
      tags:
      - Version
      summary: Update a version
      description: 'Updates a version. Enables you to publish or unpublish a version. Rate limit: 3600 in 1 hour.'
      operationId: update_version
      parameters:
      - name: id
        in: path
        description: Version ID
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Version object
              properties:
                name:
                  type: string
                  description: Name of the version
                  example: v1.0
                slug:
                  type: string
                  description: Slug in the URL
                  example: v1.0
                published:
                  type: boolean
                  description: True if it can be viewed by readers
                  example: true
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '415':
          description: Unsupported content-type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedContentType'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /version/{id}/clone:
    post:
      tags:
      - Version
      summary: Clone a version
      description: 'Copies a version into a new one: every documentation and page (published content and drafts), plus the version''s API references, are duplicated and internal links are re-pointed at the copies. The clone is created unpublished and becomes the first version in the project; publish it with a follow-up version update. Rate limit: 60 in 60 minutes.'
      operationId: clone_version
      parameters:
      - name: id
        in: path
        description: ID of the version to clone
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: Name of the new version
                  example: v2.0
                slug:
                  type: string
                  description: Slug in the URL. Derived from the name when omitted. Alphanumeric characters and dashes only.
                  example: v2-0
      responses:
        '201':
          description: Created
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Version'
        '400':
          description: General Exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '415':
          description: Unsupported content-type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedContentType'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /version/{id}/report:
    get:
      tags:
      - Version
      summary: Get version content report
      description: 'Reports every page in the version with its creation and last-update details. Rate limit: 60 in 60 minutes.'
      operationId: get_version_report
      parameters:
      - name: id
        in: path
        description: Version ID
        required: true
        schema:
          type: integer
      - name: created_by_email
        in: query
        description: Only include pages created by the user with this email address
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VersionReportPage'
                description: OK
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
  /version/{id}/broken-links:
    get:
      tags:
      - Version
      summary: Get broken links report
      description: 'Lists every broken or risky link found across the version''s pages, each with its issue type, severity, and a human-readable explanation. Rate limit: 60 in 60 minutes.'
      operationId: get_version_broken_links
      parameters:
      - name: id
        in: path
        description: Version ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BrokenLink'
                description: OK
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDenied'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
      deprecated: false
components:
  schemas:
    Error:
      title: Error
      type: object
      properties:
        message:
          type: string
          description: Message of the error
          example: No file provided.
        httpCode:
          type: number
          description: HTTP code returned
          example: 400
        code:
          type: number
          description: Internal error code
          example: 400
    VersionReportUser:
      title: Version Report User
      type: object
      properties:
        id:
          type:
          - integer
          - 'null'
          description: User ID. Null if unknown
          example: 3609
        email:
          type:
          - string
          - 'null'
          description: User e-mail address. Null if unknown
          example: peter@example.com
        name:
          type:
          - string
          - 'null'
          description: User name. Null if unknown
          example: Peter Griffin
      description: User attribution in a version report
    Version:
      title: Version
      required:
      - id
      - published
      - name
      - created
      - updated
      - slug
      - ordr
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 4
        published:
          type: boolean
          description: True if it can be viewed by readers
          example: true
        name:
          type: string
          description: Name of the version
          example: v1.0
        created:
          type: string
          description: Date of creation
          example: 2019-03-20T19:02:14+0000
        updated:
          type: string
          description: Date of last update
          example: 2019-03-20T19:02:14+0000
        slug:
          type: string
          description: Slug in the URL
          example: developerhub.io-api
        ordr:
          type: integer
          description: Numerical order in the project
          example: 4
      description: Version object
    AccessDenied:
      title: AccessDenied
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Message of the error
              example: Access Denied
            httpCode:
              type: number
              description: HTTP code returned
              example: 403
            code:
              type: number
              description: Internal error code
              example: 403
    VersionReportPage:
      title: Version Report Page
      required:
      - id
      - title
      - hasDraft
      - listed
      - created
      - createdBy
      - updated
      - updatedBy
      - sourceCreated
      - sourceCreatedBy
      type: object
      properties:
        id:
          type: integer
          description: Page ID
          example: 86123
        title:
          type: string
          description: Title of the page
          example: Getting Started
        hasDraft:
          type: boolean
          description: True if the page has unpublished draft changes
          example: false
        listed:
          type: boolean
          description: True if the page is accessible for readers
          example: true
        sourceCreated:
          type: string
          description: Date the page was originally created, tracked through version duplication to the original page
          example: 2019-03-20T19:02:14+0000
        sourceCreatedBy:
          $ref: '#/components/schemas/VersionReportUser'
        created:
          type: string
          description: Date of creation in this version
          example: 2019-03-20T19:02:14+0000
        createdBy:
          $ref: '#/components/schemas/VersionReportUser'
        updated:
          type: string
          description: Date of last update
          example: 2019-03-20T19:02:14+0000
        updatedBy:
          $ref: '#/components/schemas/VersionReportUser'
      description: One page's row in the version report
    UnsupportedContentType:
      title: UnsupportedContentType
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Message of the error
              example: Unsupported content-type 'form'. Supported content-type is 'application/json'.
            httpCode:
              type: number
              description: HTTP code returned
              example: 415
            code:
              type: number
              description: Internal error code
              example: 415
    TooManyRequests:
      title: TooManyRequests
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Message of the error
              example: You exceeded the rate limit
            httpCode:
              type: number
              description: HTTP code returned
              example: 429
            code:
              type: number
              description: Internal error code
              example: 9
    BrokenLink:
      title: Broken Link
      required:
      - severity
      - issue
      - message
      - isDraft
      - page
      - link
      - target
      type: object
      properties:
        severity:
          type: string
          description: Severity of the issue. `error` for links that will not resolve; `warning` for links that may resolve to the wrong or to hidden content.
          example: error
          enum:
          - error
          - warning
        issue:
          type: string
          description: 'Machine-readable issue code. Currently one of: `broken_link` (points to a page or reference that does not exist in this version), `app_link` (points to the DeveloperHub app instead of your documentation), `same_slug` (another page in the same section shares the slug, so the link may resolve to the wrong page), `linked_page_unlisted` (the linked page is unlisted), `linked_page_in_unpublished_documentation` (the linked page is in an unpublished documentation section), or `linked_page_in_unpublished_reference` (the linked page is in an unpublished API reference). New codes may be added over time.'
          example: broken_link
        message:
          type: string
          description: Human-readable explanation of the issue, suitable for display.
          example: The link points to a page or reference that does not exist in this version.
        isDraft:
          type: boolean
          description: True if the link was found in the page's unpublished draft content.
          example: false
        page:
          type: object
          description: The page whose content contains the offending link.
          required:
          - id
          - title
          properties:
            id:
              type: integer
              description: Page ID
              example: 86123
            title:
              type: string
              description: Title of the page
              example: Getting Started
        link:
          type: object
          description: The offending link.
          required:
          - text
          - href
          - type
          - fragment
          - targetId
          properties:
            text:
              type:
              - string
              - 'null'
              description: The anchor text of the link. Null if the link had no text.
              example: our login screen
            href:
              type:
              - string
              - 'null'
              description: The link target as authored. Null when not applicable to the issue.
              example: /getting-started
            type:
              type: string
              description: 'What the link points at: an internal page, an API reference, or an external URL.'
              example: page
              enum:
              - page
              - ref
              - external
            fragment:
              type:
              - string
              - 'null'
              description: The heading anchor (URL fragment) the link points to. Null if there is none.
              example: installation
            targetId:
              type:
              - integer
              - 'null'
              description: ID of the page or reference the link resolves to, when known. Null when no target could be resolved.
              example: 86444
        target:
          type: object
          description: Details about the linked content, when the issue resolves one.
          required:
          - title
          - section
          properties:
            title:
              type:
              - string
              - 'null'
              description: Title of the linked page. Null when the issue does not resolve a page.
              example: Hidden Page
            section:
              type:
              - string
              - 'null'
              description: Name of the documentation section or API reference the linked page belongs to. Null when not applicable.
              example: Internal Docs
      description: A broken or risky link found in a version's content
  headers:
    X-RateLimit-Limit:
      description: Requests permitted until reset time
      schema:
        type: integer
        example: 300
    X-RateLimit-Remaining:
      description: Requests consumed in current period
      schema:
        type: integer
        example: 253
    X-RateLimit-Reset:
      description: Unix timestamp at which requests consumed will reset
      schema:
        type: integer
        example: 1611530395
  securitySchemes:
    Api-Key:
      type: apiKey
      description: 'Generate an API Key from [DeveloperHub.io platform](https://app.developerhub.io) and provide it in the header such as `--header "X-Api-Key: <api-key>"` for cURL for all the requests requiring this authentication.'
      name: X-Api-Key
      in: header