openapi: 3.0.2
servers:
  - url: https://dash.readme.io/api/v1
info:
  description: Create beautiful product and API documentation with our developer friendly platform.
  title: API Endpoints
  version: 2.0.0
  x-apisguru-categories:
    - developer_tools
  x-logo:
    url: https://readme.com/static/brandkit/readme-blue.svg
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/readmeio/oas/master/packages/examples/3.0/json/readme.json
      version: "3.0"
  x-providerName: readme.io
paths:
  /:
    get:
      description: Returns project data for API key
      operationId: getProject
      responses:
        "200":
          description: Project data
      security:
        - apiKey: []
      summary: Get metadata about the current project
      tags:
        - Projects
  /api-specification:
    get:
      description: Get API specification metadata
      operationId: getAPISpecification
      parameters:
        - $ref: "#/components/parameters/perPage"
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "200":
          description: Successfully retrieved API specification metadata.
          headers:
            Link:
              $ref: "#/components/headers/link"
      security:
        - apiKey: []
      tags:
        - API Specification
    post:
      description: Upload an API specification to ReadMe. Or, to use a newer solution see https://docs.readme.com/guides/docs/automatically-sync-api-specification-with-github
      operationId: uploadAPISpecification
      parameters:
        - $ref: "#/components/parameters/x-readme-version"
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                spec:
                  description: OpenAPI/Swagger file
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        "201":
          description: The API specification successfully imported
        "400":
          description: There was a validation error during import
      security:
        - apiKey: []
      tags:
        - API Specification
  "/api-specification/{id}":
    delete:
      description: Delete an API specification in ReadMe
      operationId: deleteAPISpecification
      parameters:
        - description: ID of the API specification. The unique ID for each API can be found by navigating to your **API Definitions** page.
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: The API specification was deleted
        "404":
          description: There is no API specification with that ID
      security:
        - apiKey: []
      tags:
        - API Specification
    put:
      description: Update an API specification in ReadMe
      operationId: updateAPISpecification
      parameters:
        - description: ID of the API specification. The unique ID for each API can be found by navigating to your **API Definitions** page.
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                spec:
                  description: OpenAPI/Swagger file
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        "200":
          description: The API specification was updated
        "400":
          description: There was a validation error during import
        "404":
          description: There is no API specification with that ID
      security:
        - apiKey: []
      tags:
        - API Specification
  "/categories/{slug}":
    get:
      description: Returns the category with this slug
      operationId: getCategory
      parameters:
        - description: Slug of category. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the the category "Getting Started", enter the slug "getting-started"
          example: getting-started
          in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "200":
          description: The category exists and has been returned
        "404":
          description: There is no category with that slug
      security:
        - apiKey: []
      summary: Get category
      tags:
        - Categories
  "/categories/{slug}/docs":
    get:
      description: Returns the docs and children docs within this category
      operationId: getCategoryDocs
      parameters:
        - description: Slug of category. Slugs must be all lowercase, and replace spaces with hyphens. For example, for the the category "Getting Started", enter the slug "getting-started"
          example: getting-started
          in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "200":
          description: The category exists and all of the docs have been returned
        "404":
          description: There is no category with that slug
      security:
        - apiKey: []
      summary: Get docs for category
      tags:
        - Categories
  /changelogs:
    get:
      description: Returns a list of changelogs associated with the project API key
      operationId: getChangelogs
      parameters:
        - $ref: "#/components/parameters/perPage"
        - $ref: "#/components/parameters/page"
      responses:
        "200":
          description: OK
          headers:
            Link:
              $ref: "#/components/headers/link"
      security:
        - apiKey: []
      summary: Get changelogs
      tags:
        - Changelog
    post:
      description: Create a new changelog inside of this project
      operationId: createChangelog
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Changelog"
        description: Changelog object
        required: true
      responses:
        "201":
          description: The changelog has successfully been created
        "400":
          description: There was a validation error during creation
      security:
        - apiKey: []
      summary: Create changelog
      tags:
        - Changelog
  "/changelogs/{slug}":
    delete:
      description: Delete the changelog with this slug
      operationId: deleteChangelog
      parameters:
        - description: Slug of changelog
          in: path
          name: slug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: The changelog has successfully been updated
        "404":
          description: There is no changelog with that slug
      security:
        - apiKey: []
      summary: Delete changelog
      tags:
        - Changelog
    get:
      description: Returns the changelog with this slug
      operationId: getChangelog
      parameters:
        - description: Slug of changelog
          in: path
          name: slug
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The changelog exists and has been returned
        "404":
          description: There is no changelog with that slug
      security:
        - apiKey: []
      summary: Get changelog
      tags:
        - Changelog
    put:
      description: Update a changelog with this slug
      operationId: updateChangelog
      parameters:
        - description: Slug of changelog
          in: path
          name: slug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Changelog"
        description: Changelog object
        required: true
      responses:
        "200":
          description: The changelog has successfully been updated
        "400":
          description: There was a validation error during update
        "404":
          description: There is no changelog with that slug
      security:
        - apiKey: []
      summary: Update changelog
      tags:
        - Changelog
  /custompages:
    get:
      description: Returns a list of custom pages associated with the project API key
      operationId: getCustomPages
      parameters:
        - $ref: "#/components/parameters/perPage"
        - $ref: "#/components/parameters/page"
      responses:
        "200":
          description: OK
          headers:
            Link:
              $ref: "#/components/headers/link"
      security:
        - apiKey: []
      summary: Get custom pages
      tags:
        - Custom Pages
    post:
      description: Create a new custom page inside of this project
      operationId: createCustomPage
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomPage"
        description: CustomPage object
        required: true
      responses:
        "201":
          description: The custom page has successfully been created
        "400":
          description: There was a validation error during creation
      security:
        - apiKey: []
      summary: Create custom page
      tags:
        - Custom Pages
  "/custompages/{slug}":
    delete:
      description: Delete the custom page with this slug
      operationId: deleteCustomPage
      parameters:
        - description: Slug of custom page
          in: path
          name: slug
          required: true
          schema:
            type: string
      responses:
        "204":
          description: The custom page has successfully been updated
        "404":
          description: There is no custom page with that slug
      security:
        - apiKey: []
      summary: Delete custom page
      tags:
        - Custom Pages
    get:
      description: Returns the custom page with this slug
      operationId: getCustomPage
      parameters:
        - description: Slug of custom page
          in: path
          name: slug
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The custom page exists and has been returned
        "404":
          description: There is no custom page with that slug
      security:
        - apiKey: []
      summary: Get custom page
      tags:
        - Custom Pages
    put:
      description: Update a custom page with this slug
      operationId: updateCustomPage
      parameters:
        - description: Slug of custom page
          in: path
          name: slug
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomPage"
        description: CustomPage object
        required: true
      responses:
        "200":
          description: The custom page has successfully been updated
        "400":
          description: There was a validation error during update
        "404":
          description: There is no custom page with that slug
      security:
        - apiKey: []
      summary: Update custom page
      tags:
        - Custom Pages
  /docs:
    post:
      description: Create a new doc inside of this project
      operationId: createDoc
      parameters:
        - $ref: "#/components/parameters/x-readme-version"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Doc"
        description: Doc object
        required: true
      responses:
        "201":
          description: The doc has successfully been created
        "400":
          description: There was a validation error during creation
      security:
        - apiKey: []
      summary: Create doc
      tags:
        - Docs
  /docs/search:
    post:
      description: Returns all docs that match the search
      operationId: searchDocs
      parameters:
        - description: Search string to look for
          in: query
          name: search
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "200":
          description: The search was successful and results were returned
        "500":
          description: There is an internal error
      security:
        - apiKey: []
      summary: Search docs
      tags:
        - Docs
  "/docs/{slug}":
    delete:
      description: Delete the doc with this slug
      operationId: deleteDoc
      parameters:
        - description: Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
          example: new-features
          in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "204":
          description: The doc has successfully been updated
        "404":
          description: There is no doc with that slug
      security:
        - apiKey: []
      summary: Delete doc
      tags:
        - Docs
    get:
      description: Returns the doc with this slug
      operationId: getDoc
      parameters:
        - description: Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
          example: new-features
          in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      responses:
        "200":
          description: The doc exists and has been returned
        "404":
          description: There is no doc with that slug
      security:
        - apiKey: []
      summary: Get doc
      tags:
        - Docs
    put:
      description: Update a doc with this slug
      operationId: updateDoc
      parameters:
        - description: Slug of doc. must be lowercase, and replace spaces with hyphens. For example, for the page titled "New Features", enter the slug "new-features"
          example: new-features
          in: path
          name: slug
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-readme-version"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Doc"
        description: Doc object
        required: true
      responses:
        "200":
          description: The doc has successfully been updated
        "400":
          description: There was a validation error during update
        "404":
          description: There is no doc with that slug
      security:
        - apiKey: []
      summary: Update doc
      tags:
        - Docs
  /errors:
    get:
      description: Returns with all of the error page types for this project
      operationId: getErrors
      responses:
        "200":
          description: An array of the errors
      security:
        - apiKey: []
      summary: Get errors
      tags:
        - Errors
  /swagger:
    post:
      deprecated: true
      description: DEPRECATED. Instead use https://docs.readme.com/developers/reference/api-specification#uploadapispecification to upload a Swagger file to ReadMe
      operationId: uploadSwagger
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                swagger:
                  description: Swagger file
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        "201":
          description: The Swagger file was successfully imported
        "400":
          description: There was a validation error during import
      security:
        - apiKey: []
      tags:
        - Swagger
  "/swagger/{id}":
    delete:
      deprecated: true
      description: DEPRECATED. Instead, use https://docs.readme.com/developers/reference/api-specification#deleteapispecification to delete a Swagger file in ReadMe
      operationId: deleteSwagger
      parameters:
        - description: ID of swagger the file
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: The Swagger file was successfully deleted
        "404":
          description: There is no Swagger file with that ID
      security:
        - apiKey: []
      tags:
        - Swagger
    put:
      deprecated: true
      description: DEPRECATED. Instead, use https://docs.readme.com/developers/reference/api-specification#updateapispecification to update a Swagger file.
      operationId: updateSwagger
      parameters:
        - description: ID of the Swagger file
          in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
                swagger:
                  description: Swagger file
                  format: binary
                  type: string
              type: object
        required: true
      responses:
        "200":
          description: The Swagger file was successfully updated
        "400":
          description: There was a validation error during import
        "404":
          description: There is no Swagger file with that ID
      security:
        - apiKey: []
      tags:
        - Swagger
  /version:
    get:
      description: Retrieve a list of versions associated with a project API key
      operationId: getVersions
      responses:
        "200":
          description: JSON list of versions
      security:
        - apiKey: []
      summary: Get versions
      tags:
        - Version
    post:
      description: Create a new version
      operationId: createVersion
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Version"
        description: Version object
        required: true
      responses:
        "200":
          description: The model was successfully created and associated with the target project
        "400":
          description: That version already exists in the project, or there are validation errors with the request
        "404":
          description: Could not find target fork in database
      security:
        - apiKey: []
      summary: Create version
      tags:
        - Version
  "/version/{versionId}":
    delete:
      description: Delete a version
      operationId: deleteVersion
      parameters:
        - $ref: "#/components/parameters/versionId"
      responses:
        "200":
          description: The target version was successfully deleted
        "400":
          description: Cannot delete the main version for a project
        "404":
          description: Could not find target version in database
      security:
        - apiKey: []
      summary: Delete version
      tags:
        - Version
    get:
      description: Returns the version with this version ID
      operationId: getVersion
      parameters:
        - $ref: "#/components/parameters/versionId"
      responses:
        "200":
          description: JSON version model
        "404":
          description: Could not find target version in database
      security:
        - apiKey: []
      summary: Get version
      tags:
        - Version
    put:
      description: Update an existing version
      operationId: updateVersion
      parameters:
        - $ref: "#/components/parameters/versionId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Version"
        description: Version object
        required: true
      responses:
        "200":
          description: The target version was successfully updated
        "400":
          description: Cannot demote a version through update
        "404":
          description: Could not find target version in database
      security:
        - apiKey: []
      summary: Update version
      tags:
        - Version
components:
  headers:
    link:
      description: Pagination information. See https://docs.readme.com/reference#pagination
      schema:
        type: string
  parameters:
    page:
      description: Used to specify further pages (starts at 1)
      in: query
      name: page
      schema:
        default: 1
        minimum: 1
        type: integer
    perPage:
      description: Number of items to include in pagination (up to 100, defaults to 10)
      in: query
      name: perPage
      schema:
        default: 10
        maximum: 100
        minimum: 1
        type: integer
    versionId:
      description: Semver version indentifier
      in: path
      name: versionId
      required: true
      schema:
        type: string
    x-readme-version:
      description: Version number of your docs project, for example, v3.0. To see all valid versions for your docs project call https://docs.readme.com/developers/reference/version#getversions.
      example: v3.0
      in: header
      name: x-readme-version
      required: true
      schema:
        type: string
  schemas:
    Changelog:
      properties:
        body:
          description: Body content of the changelog
          type: string
        hidden:
          default: true
          description: Visibility of the changelog
          type: boolean
        title:
          description: Title of the changelog
          type: string
        type:
          default: ""
          enum:
            - ""
            - added
            - fixed
            - improved
            - deprecated
            - removed
          type: string
      required:
        - title
        - body
      type: object
    CustomPage:
      properties:
        body:
          description: Body formatted in Markdown (displayed by default).
          type: string
        hidden:
          default: true
          description: Visibility of the custom page
          type: boolean
        html:
          description: Body formatted in HTML (sanitized, only displayed if `htmlmode` is **true**).
          type: string
        htmlmode:
          default: false
          description: "**true** if `html` should be displayed, **false** if `body` should be displayed."
          type: boolean
        title:
          description: Title of the custom page
          type: string
      required:
        - title
      type: object
    Doc:
      properties:
        body:
          description: Body content of the page, formatted in ReadMe or Github flavored Markdown. Accepts long page content, for example, greater than 100k characters
          type: string
        category:
          description: "Category ID of the page, which you can get through https://docs.readme.com/developers/reference/categories#getcategory "
          type: string
        hidden:
          default: true
          description: Visibility of the page
          type: boolean
        parentDoc:
          description: For a subpage, specify the parent doc ID, which you can get through https://docs.readme.com/developers/reference/docs#getdoc
          type: string
        title:
          description: Title of the page
          type: string
        type:
          description: Type of the page. The available types all show up under the /docs/ URL path of your docs project (also known as the "guides" section). Can be "basic" (most common), "error" (page desribing an API error), or "link" (page that redirects to an external link)
          enum:
            - basic
            - error
            - link
          type: string
      required:
        - title
        - category
      type: object
    Version:
      properties:
        codename:
          description: Dubbed name of version
          type: string
        from:
          description: Semantic Version to use as the base fork
          type: string
        is_beta:
          default: true
          type: boolean
        is_deprecated:
          description: Should this be deprecated? Only allowed in PUT operations
          type: boolean
        is_hidden:
          description: Should this be publically accessible?
          type: boolean
        is_stable:
          description: Should this be the **main** version
          type: boolean
        version:
          description: Semantic Version
          type: string
      required:
        - version
        - from
      type: object
  securitySchemes:
    apiKey:
      scheme: basic
      type: http
