DeveloperHub Project API

openapi: 3.2.0
info:
  title: DeveloperHub.io Documentation Project 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.
  version: 1.1.0
  contact:
    name: DeveloperHub
    url: https://docs.developerhub.io/api/ref
servers:
- url: https://api.developerhub.io/api/v1
  variables: {}
security:
- Api-Key: []
tags:
- name: Project
  description: Project-level operations such as export, search, audit log, and users.
paths:
  /export:
    get:
      tags:
      - Project
      summary: Exports project
      description: 'Exports the project into a ZIP file of Markdoc or Markdown files. Only available for
        enterprise plans. Rate limit: 10 in 60 minutes.'
      operationId: export_project
      parameters:
      - name: format
        in: query
        description: Format of the exported page files.
        required: false
        schema:
          type: string
          default: markdoc
          enum:
          - markdoc
          - markdown
      - name: version_slug
        in: query
        description: Export only the version with this slug. Omit to export all versions.
        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/zip:
              schema:
                type: string
                description: OK
                format: binary
        '400':
          description: Upgrade Plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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
  /search:
    get:
      tags:
      - Project
      summary: Search content
      description: 'Searches through project or version. Use this to build custom search into your own
        website/services which directs users to documentation. Minimum plan required is Grow plan. Rate
        limit: 10,800 in 60 minutes.'
      operationId: search
      parameters:
      - name: query
        in: query
        schema:
          type: string
        description: Search query
        example: variables
        required: true
      - name: version_slug
        in: query
        schema:
          type: string
        description: Slug of the version to be searched. To use always the default published version,
          use 'latest'. Omit to search in the entire project
        example: v1.0
        required: false
      - name: page
        in: query
        schema:
          type: integer
          default: 0
        description: Specify the page to retrieve. Numbering starts from 0.
        required: false
        example: 1
      - name: hits
        in: query
        schema:
          type: integer
          default: 20
        description: Number of hits to retrieve.
        required: false
        example: 20
      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/SearchResult'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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'
  /all:
    get:
      tags:
      - Project
      summary: Get all resources
      description: 'Returns all pages, documentation, references and versions of your project. Rate limit:
        30 in 60 minutes.'
      operationId: all_project
      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:
                $ref: '#/components/schemas/AllProject'
        '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
  /audit:
    get:
      tags:
      - Project
      summary: Get audit log
      description: 'Query the audit log. Only available in enterprise plans. Rate limit: 600 in 60 minutes.'
      operationId: get_audit_log
      parameters:
      - name: scopes
        in: query
        schema:
          type: array
          default:
          - content
          items:
            type: string
            enum:
            - content
            - users
            - hosting
            - security
            - plan
            - other
        description: Scope of the audit logs.
        example:
        - content
        required: false
      - name: max_date
        in: query
        schema:
          type: string
        description: Maximum date to retrieve audits in Y-m-d\TH:i:sP format. Note that "+" character
          must be encoded to "%2B"
        example: '2021-01-24T17:06:24+00:00'
        required: false
      - name: hits
        in: query
        schema:
          type: integer
          default: 20
        description: Number of hits to retrieve. Maximum is 100
        example: 20
        required: false
      - name: cursor
        in: query
        schema:
          type: string
        description: Cursor for next page of results
        example: XAr
        required: false
      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/Audit'
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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
  /users:
    get:
      tags:
      - Project
      summary: Get users
      description: 'Get all users and their roles. Rate limit: 3600 in 60 minutes.'
      operationId: get_users
      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/User'
                description: OK
        '400':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '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:
  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
  schemas:
    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
    AllProject:
      title: AllProject
      required:
      - page
      - documentation
      - reference
      - version
      type: object
      properties:
        page:
          type: object
          description: A key-value dictionary mapping of page ID to page details
          additionalProperties:
            type: object
            properties:
              title:
                type: string
                description: Page title
                example: Getting Started
              updated:
                type: string
                description: Date of last update
                example: 2019-03-20T19:02:14+0000
              documentationId:
                type: integer
                description: Documentation ID
                example: 412
              listed:
                type: boolean
                description: True if page is accessible for readers
                example: true
          example:
            '6177':
              title: Getting Started
              updated: 2019-03-20T19:02:14+0000
              documentationId: 412
              listed: true
        documentation:
          type: object
          description: A key-value dictionary mapping of documentation ID to documentation details
          additionalProperties:
            type: object
            properties:
              title:
                type: string
                description: Documentation title
                example: Getting Started
              versionId:
                type: integer
                description: Version ID
                example: 310
          example:
            '412':
              title: Support Center
              versionId: 310
        reference:
          type: object
          description: A key-value dictionary mapping of reference ID to reference details
          additionalProperties:
            type: object
            properties:
              title:
                type: string
                description: Reference title
                example: Getting Started
              versionId:
                type: integer
                description: Version ID
                example: 310
          example:
            '917':
              title: Support Center
              versionId: 310
        version:
          type: object
          description: A key-value dictionary mapping of version ID to version details
          additionalProperties:
            type: object
            properties:
              name:
                type: string
                description: Version title
                example: Getting Started
              published:
                type: boolean
                description: True if it can be viewed by readers
                example: true
          example:
            '310':
              name: v1.0
              published: true
      description: All resources in a project
    Audit:
      type: object
      required:
      - data
      - count
      - total
      - cursor
      properties:
        data:
          type: array
          items:
            title: Audit Log
            required:
            - ipAddress
            - entity
            - entityId
            - details
            - scope
            - message
            - operation
            - timestamp
            type: object
            properties:
              ipAddress:
                type: string
                description: IP Address of the user who made the change
                example: 81.123.55.209
              entity:
                type: string
                description: Type of entity.
                example: page
                enum:
                - page
                - documentation
                - reference
                - version
                - project
                - landing-page
                - index
                - project-import
                - project-user
              entityId:
                type: string
                description: ID of entity
                example: '452'
              details:
                type: object
                description: Changes to the entity
              scope:
                type: string
                description: Scope of the change
                example: content
              message:
                type: string
                description: Message describing the change
                example: edited
              operation:
                type: string
                description: Operation of the change
                example: INS
                enum:
                - INS
                - UPD
                - DEL
                - READ
                - ADD
                - REM
              timestamp:
                type: string
                description: Date of change
                example: '2021-01-19T20:43:56+00:00'
              user:
                type: string
                description: User making the change
                example: 829 <hello@developerhub.io>
              apiKey:
                type: boolean
                description: True if change was authenticated through an API Key
                example: false
            description: Audit log object
        count:
          type: integer
          description: Number of hits retrieved
          example: 20
        total:
          type: integer
          description: Total number of hits retrievable
          example: 620
        cursor:
          type: string
          description: Cursor for next page of results. Null value if there are no more results
          example: XAr
    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
    SearchResult:
      title: SearchResult
      type: object
      properties:
        hits:
          type: array
          items:
            type: object
            properties:
              content:
                type: string
                description: Content where hit was found
                example: "To use project variables in an API Reference, replace all occurrences of the\
                  \ variable with the variable reference. For example, one definition property could be:\n\
                  version:\n    type: string\n    description: Version of the API\n    example: \"%versions.last_version%\"\
                  \n\n\nWarning\nNote that YAML requires you to use double quotations to escape a string\
                  \ containing percent sign.\nKnown Limitations\n\nVariables do not work as HREFs for\
                  \ links.\n"
              title:
                description: Title of the hit. It is either the page title or the heading title for the
                  hit if it is in a documentation page, or the name of the operation if it was in an API
                  reference.
                type: string
                example: Using Project Variables in References
              sectionType:
                description: 'Type of section: ''doc'' for documentation or ''ref'' for reference'
                type: string
                example: doc
                enum:
                - doc
                - ref
              version:
                type: string
                example: v1.0
                description: Name of version
              section:
                type: string
                example: Support Center
                description: Name of section
              page:
                type: string
                example: Variables
                description: Name of page
              pageId:
                type: number
                example: 86444
                description: Page ID
              fragment:
                type: string
                example: using-project-variables-in-references
                description: URL fragment
              path:
                type: string
                example: /v1.0/support-center/variables#using-project-variables-in-references
                description: Path, without the host, to direct the user to to find the content
            required:
            - content
            - title
            - sectionType
            - version
            - section
            - path
        nbHits:
          type: integer
          description: Number of hits retrieved
          example: 20
        page:
          type: integer
          description: Current page
          example: 1
        nbPages:
          type: integer
          description: Number of pages that can be searched for this query
          example: 3
        hitsPerPage:
          type: integer
          description: Number of hits per page
          example: 20
        query:
          type: string
          description: Query used
          example: variables
        basepath:
          type: string
          description: Basepath of the project, if any.
          example: docs
        host:
          type: string
          description: Host of the project including scheme.
          example: https://docs.pied-piper.com
      required:
      - hits
      - nbHits
      - page
      - nbPages
      - hitsPerPage
      - query
      - basepath
    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
    User:
      title: User
      required:
      - id
      - email
      - role
      - name
      - lastActiveAt
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 3609
        name:
          type: string
          description: User name
          example: Peter Griffin
        email:
          type: string
          description: User e-mail address
          example: peter@example.com
        role:
          type: string
          description: Role of user
          example: ADMIN
          enum:
          - ADMIN
          - PUBLISHER
          - WRITER
          - REVIEWER
        lastActiveAt:
          type: string
          description: Date of last time user accessed DeveloperHub
          example: 2021-03-20T19:02:14+0000
      description: User object
  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