openapi: 3.2.0
info:
  title: Page 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: Page
  description: Operations for creating, reading, updating, publishing, and deleting pages.
paths:
  /page:
    get:
      tags:
      - Page
      summary: Get page by slug
      description: 'Get a page by slugs and read its content in Markdoc

        or a derived format. Rate limit: 60 in 1 minute.


        Either `version_id` or `version_slug` must be provided. Either `documentation_id` or `documentation_slug` must be provided.'
      operationId: get_page
      parameters:
      - name: version_id
        in: query
        description: Version ID.
        required: false
        schema:
          type: integer
      - name: version_slug
        in: query
        description: Version Slug.
        required: false
        schema:
          type: string
      - name: documentation_id
        in: query
        description: Documentation ID.
        required: false
        schema:
          type: integer
      - name: documentation_slug
        in: query
        description: Documentation Slug.
        required: false
        schema:
          type: string
      - name: page_slug
        in: query
        description: Page Slug.
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: Format type
        required: false
        schema:
          type: string
          default: markdoc
          enum:
          - markdoc
          - markdown
          - html
          - text
      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/Page'
        '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
  /page/{id}:
    get:
      tags:
      - Page
      summary: Read page
      description: 'Read a page including its content in Markdoc or a derived format. Rate limit: 600 in 1 minute.'
      operationId: read_page
      parameters:
      - name: id
        in: path
        description: Page ID
        required: true
        schema:
          type: integer
      - name: format
        in: query
        description: Format type
        required: false
        schema:
          type: string
          default: markdoc
          enum:
          - markdoc
          - markdown
          - html
          - text
      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/Page'
        '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
    put:
      tags:
      - Page
      summary: Update a page
      description: 'Updates a page title, slug or draft contents. Rate limit: 10800 in 1 hour.'
      operationId: update_page
      parameters:
      - name: id
        in: path
        description: Page ID
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Page object
              properties:
                title:
                  type: string
                  description: Title of the page
                  example: Getting Started
                slug:
                  type: string
                  description: Slug in the URL. Generated if it was not provided
                  example: getting-started
                content:
                  type: string
                  description: Draft contents of the page in [Markdoc format](https://docs.developerhub.io/support-center/exporting-documentation#markdoc)
                  example: 'Let''s start here


                    ## Step 1

                    Welcome to **DeveloperHub**


                    {% callout type="info" title="Note" %}

                    Content is written in Markdoc.

                    {% /callout %}

                    '
                message:
                  type: string
                  description: Page history message
                  default: Updated using API
      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/Page'
        '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
    delete:
      tags:
      - Page
      summary: Delete a page
      description: 'Deletes a page and removes it from the navigation index. Rate limit: 10800 in 1 hour.'
      operationId: delete_page
      parameters:
      - name: id
        in: path
        description: Page 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: object
                description: Empty object
        '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
  /documentation/{id}/page:
    post:
      tags:
      - Page
      summary: Create a page
      description: 'Creates a page with draft contents. To insert in a pre-existing category, set the `categoryTitle`. Rate limit: 10800 in 1 hour.'
      operationId: create_page
      parameters:
      - name: id
        in: path
        description: Documentation ID
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Page object
              properties:
                title:
                  type: string
                  description: Title of the page
                  example: Getting Started
                slug:
                  type: string
                  description: Slug in the URL. Generated if it was not provided
                  example: getting-started
                content:
                  type: string
                  description: Draft contents of the page in [Markdoc format](https://docs.developerhub.io/support-center/exporting-documentation#markdoc)
                  example: 'Let''s start here


                    ## Step 1

                    Welcome to **DeveloperHub**


                    {% callout type="info" title="Note" %}

                    Content is written in Markdoc.

                    {% /callout %}

                    '
                categoryTitle:
                  type: string
                  description: To create the page inside a category, provide the pre-existing category title here (case insensitive). The page is added after the category's existing pages.
                  example: Installation
                message:
                  type: string
                  description: Page history message
                  default: Created using API
              required:
              - title
              - content
      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/Page'
        '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
  /page/{id}/publish:
    put:
      tags:
      - Page
      summary: Publish a page
      description: 'Publishes a page from its draft contents. Rate limit: 10800 in 1 hour.'
      operationId: publish_page
      parameters:
      - name: id
        in: path
        description: Page 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:
                $ref: '#/components/schemas/Page'
        '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
components:
  schemas:
    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
    Page:
      title: Page
      required:
      - id
      - listed
      - title
      - created
      - updated
      - slug
      - path
      - contentDraft
      - contentPublished
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier
          example: 86123
        listed:
          type: boolean
          description: True if it can be viewed by readers if the version is published
          example: true
        title:
          type: string
          description: Title of the page
          example: Getting Started
        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: getting-started
        path:
          type: string
          description: Path of the page as version, documentation and page slugs
          example: v1.0/support-center/getting-started
        contentDraft:
          type:
          - string
          - 'null'
          description: Draft content in the selected format. Null if the page has no draft
          example: This is the page contents
        contentPublished:
          type:
          - string
          - 'null'
          description: Published content in the selected format. Null if never published
          example: This is the page contents
      description: Page 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
    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
  headers:
    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
    X-RateLimit-Limit:
      description: Requests permitted until reset time
      schema:
        type: integer
        example: 300
  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