openapi: 3.2.0
info:
  title: Routebase Public Docs as Code API
  description: 'This reference covers the part of the Routebase API that is a commitment to

    customers.'
  version: 1.0.0
servers:
- url: https://api.routebase.dev
tags:
- name: Docs as Code
  description: 'Keep documentation pages in your own repository and push them into Routebase from

    a pipeline. These endpoints back `routebase docs push` and `routebase docs pull`.'
paths:
  /api/projects/{projectId}/docs:
    get:
      tags:
      - Docs as Code
      summary: List the documentations of a project
      description: 'Returns the documentations of a project with their versions, which is how a

        pipeline finds the id of the version it should write into. Only a version whose

        status is `draft` or `review` accepts changes, so pick one of those.'
      operationId: getDocumentations
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      responses:
        '200':
          description: The documentations of the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentationsResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
  /api/projects/{projectId}/docs/{docId}/versions/{versionId}/folders:
    post:
      tags:
      - Docs as Code
      summary: Create a folder
      description: 'Creates a folder in a version. A folder with `isSection` set becomes a top level

        section in the portal header rather than an entry in the sidebar, and only a

        folder at the root can be one.'
      operationId: createDocFolder
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocFolderRequest'
        required: true
      responses:
        '201':
          description: The folder was created.
          headers:
            Location:
              description: URL of the new folder.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDocFolderResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
  /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages:
    post:
      tags:
      - Docs as Code
      summary: Create a page
      description: 'Creates a page inside a version, at the root or under a folder. The slug is

        derived from the title when you do not send one, and it is what the public

        portal URL is built from, so set it explicitly if the URL matters to you.'
      operationId: createDocPage
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocPageRequest'
        required: true
      responses:
        '201':
          description: The page was created.
          headers:
            Location:
              description: URL of the new page.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDocPageResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
  /api/projects/{projectId}/docs/{docId}/versions/{versionId}/pages/{pageId}:
    get:
      tags:
      - Docs as Code
      summary: Get a page with its content
      description: 'Returns one page including its Markdown content and its `rowVersion`. Send that

        `rowVersion` back on the next update and a concurrent edit is rejected with 409

        instead of silently overwriting someone else''s work.'
      operationId: getDocPageDetail
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/PageId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      responses:
        '200':
          description: The page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocPageDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
    put:
      tags:
      - Docs as Code
      summary: Update a page
      description: 'Replaces the title and content of a page, which is the call that carries a

        Markdown file from your repository into Routebase. A page that a person has

        locked in the editor is not writable, and the call is rejected until the lock is

        released.'
      operationId: updateDocPage
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/PageId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDocPageRequest'
        required: true
      responses:
        '200':
          description: The updated page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocPageDetail'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
  /api/projects/{projectId}/docs/{docId}/versions/{versionId}/tree:
    get:
      tags:
      - Docs as Code
      summary: Get the page tree of a version
      description: 'Returns the full hierarchy of a documentation version. Each node is exactly one

        of a page, a folder or an API reference snapshot, and the `type` field says

        which of the three is filled.


        The response carries an ETag, so a pipeline that syncs repeatedly can send

        `If-None-Match` and skip the work when nothing moved.'
      operationId: getDocTree
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      responses:
        '200':
          description: The documentation tree.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocTree'
        '304':
          description: Nothing changed since the ETag you sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
  /api/projects/{projectId}/docs/{docId}/versions/{versionId}/tree/reorder:
    put:
      tags:
      - Docs as Code
      summary: Reorder the items under one parent
      description: 'Sets the order of the items inside one folder, or at the root when

        `parentFolderPublicId` is null. Send the complete list of ids in the order you

        want, because the position of an item is its index in that list.'
      operationId: reorderTreeItems
      parameters:
      - $ref: '#/components/parameters/DocId'
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/DocVersionId'
      - name: X-RB-Region
        in: header
        description: Region of your organization. US organizations must send `us`; EU organizations leave the header out. Without it a US call is routed to the EU region and answered with 401.
        schema:
          type: string
          example: us
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderTreeItemsRequest'
        required: true
      responses:
        '204':
          description: The order was applied.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          description: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              required: true
              schema:
                type: integer
                format: int32
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - ApiKeyAuth: []
      x-routebase-folder-path: Docs as Code
components:
  schemas:
    DocVisibility:
      enum:
      - internal
      - authenticated
      - public
      type: string
      description: Who can read a published documentation version.
    CreateDocPageResult:
      required:
      - id
      - slug
      type: object
      properties:
        id:
          type: string
          description: Public id of the new page.
          format: uuid
        slug:
          type: string
          description: URL segment the page received, derived from the title unless you sent one.
      description: The id and slug the new page received.
    DocVersionStatus:
      enum:
      - draft
      - review
      - published
      - archived
      type: string
      description: 'The lifecycle state of a documentation version. Only `draft` and `review` accept

        content changes.

        '
    CreateDocPageRequest:
      required:
      - title
      type: object
      properties:
        title:
          type: string
          description: Page title. It becomes the heading and, unless you send a slug, the URL segment.
        content:
          type:
          - 'null'
          - string
          description: Page content as Markdown.
        parentFolderPublicId:
          type:
          - 'null'
          - string
          description: Folder to create the page in, or null for the root.
          format: uuid
        pageType:
          oneOf:
          - $ref: '#/components/schemas/DocPageType'
          - type: 'null'
          description: Template of the page. Defaults to `custom`.
        structuredContent:
          type:
          - 'null'
          - string
          description: The editor representation of the content as JSON. Send content instead unless you are mirroring the editor.
        icon:
          type:
          - 'null'
          - string
          description: Icon name to show next to the page in the sidebar.
        slug:
          type:
          - 'null'
          - string
          description: URL segment of the page. Derived from the title when you leave it out.
      description: A new page. Only the title is required.
    DocTreeNode:
      required:
      - id
      - type
      - sortOrder
      type: object
      properties:
        id:
          type: string
          description: Public id of the tree entry itself, which is what the reorder call takes.
          format: uuid
        type:
          enum:
          - page
          - folder
          - specSnapshot
          type: string
          description: Which kind of node this is.
        sortOrder:
          type: integer
          description: Position among its siblings.
          format: int32
        page:
          oneOf:
          - $ref: '#/components/schemas/DocTreePage'
          - type: 'null'
          description: The page payload. Filled only when type is page.
        folder:
          oneOf:
          - $ref: '#/components/schemas/DocTreeFolder'
          - type: 'null'
          description: The folder payload. Filled only when type is folder.
        specSnapshot:
          oneOf:
          - $ref: '#/components/schemas/DocTreeSpecSnapshot'
          - type: 'null'
          description: The API reference payload. Filled only when type is specSnapshot.
      description: One node of the tree. `type` says which of the three payload fields is filled, and the other two are null.
    VersionNumberingScheme:
      enum:
      - semantic
      - simple
      - dateBased
      - custom
      type: string
      description: How a documentation numbers its versions.
    DocVersion:
      required:
      - id
      - versionNumber
      - status
      - visibility
      - createdAt
      type: object
      properties:
        id:
          type: string
          description: Public id of the documentation version.
          format: uuid
        versionNumber:
          type: integer
          description: Sequential number of the version, counting from 1.
          format: int32
        status:
          description: Where the version stands. Only draft and review accept content changes.
          $ref: '#/components/schemas/DocVersionStatus'
        visibility:
          description: Who can read the version once it is published.
          $ref: '#/components/schemas/DocVisibility'
        publishedAt:
          type:
          - 'null'
          - string
          description: When the version was published, in UTC. Null while it is a draft.
          format: date-time
        createdAt:
          type: string
          description: When the version was created, in UTC.
          format: date-time
        rowVersion:
          type:
          - 'null'
          - string
          description: Base64 concurrency token.
      description: One version of a documentation. Only draft and review accept content changes.
    Problem:
      required:
      - status
      type: object
      properties:
        type:
          type: string
          description: A URI identifying the problem type.
        title:
          type: string
          description: A short summary of the problem type.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        detail:
          type: string
          description: A human readable explanation.
        instance:
          type: string
          description: The path that produced the error.
        code:
          type: string
          description: 'The stable machine readable error code, for example `CONCURRENCY_CONFLICT`,

            `PROJECT_LOCKED`, `API_KEY_SCOPE_DENIED` or `NOT_A_MEMBER`.

            '
      description: 'The error shape of the API, which follows RFC 9457. Branch on `code`, because

        `detail` is written for people and may be reworded.

        '
    DocTreeSpecSnapshot:
      required:
      - id
      - specName
      - versionNumber
      - endpointCount
      - playgroundEnabled
      - autoSyncEnabled
      - openApiJson
      - sourceSpecPublicId
      - hasNewerVersion
      type: object
      properties:
        id:
          type: string
          description: Public id of the snapshot, which the snapshot endpoints take.
          format: uuid
        specName:
          type: string
          description: Name of the specification this snapshot was taken from.
        versionNumber:
          type: string
          description: Version label that was frozen into this snapshot.
        endpointCount:
          type: integer
          description: How many operations the frozen document holds.
          format: int32
        playgroundEnabled:
          type: boolean
          description: Whether the portal offers Try It on these endpoints.
        autoSyncEnabled:
          type: boolean
          description: Whether publishing a new specification version refreshes this snapshot on its own.
        openApiJson:
          type: string
          description: The frozen OpenAPI document.
        sourceSpecPublicId:
          type: string
          description: Public id of the specification in the API designer, so you can trace it back.
          format: uuid
        hasNewerVersion:
          type: boolean
          description: A newer published version exists than the one frozen here.
        latestPublishedVersionNumber:
          type:
          - 'null'
          - string
          description: Newest published version of the source specification. Compare it with versionNumber to see how far behind the snapshot is.
        endpointAnnotations:
          type:
          - 'null'
          - string
          description: Per-endpoint annotations, as JSON.
        endpointSortOrders:
          type:
          - 'null'
          - string
          description: Per-endpoint order, as JSON.
        tagSortOrders:
          type:
          - 'null'
          - string
          description: Tag order, as JSON.
        folderDescriptions:
          type:
          - 'null'
          - string
          description: Folder intro texts, as JSON.
      description: A frozen copy of a published API specification, rendered as the API reference of the portal.
    DocTreeFolder:
      required:
      - id
      - name
      - slug
      - isSection
      - children
      type: object
      properties:
        id:
          type: string
          description: Public id of the folder, which the folder endpoints take.
          format: uuid
        name:
          type: string
          description: Folder name shown in the sidebar or the header.
        slug:
          type: string
          description: URL segment the folder contributes to the portal path.
        icon:
          type:
          - 'null'
          - string
          description: Icon name shown next to the folder.
        isSection:
          type: boolean
          description: The folder is a top level section in the portal header.
        description:
          type:
          - 'null'
          - string
          description: Intro text shown on the folder overview page.
        children:
          type: array
          items:
            $ref: '#/components/schemas/DocTreeNode'
          description: Pages, folders and snapshots inside this folder, already in sort order.
        rowVersion:
          type:
          - 'null'
          - string
          description: Base64 concurrency token.
      description: A folder inside the tree, carrying its children inline.
    ReorderTreeItemsRequest:
      required:
      - itemPublicIds
      type: object
      properties:
        parentFolderPublicId:
          type:
          - 'null'
          - string
          description: The folder whose children you are ordering, or null for the root.
          format: uuid
        itemPublicIds:
          type: array
          items:
            type: string
            format: uuid
          description: Every id under that parent, in the order you want them.
      description: The complete, ordered list of ids under one parent. Position is the index in that list.
    DocPageDetail:
      required:
      - id
      - title
      - slug
      - content
      - pageType
      - createdAt
      - isLocked
      type: object
      properties:
        id:
          type: string
          description: Public id of the page.
          format: uuid
        title:
          type: string
          description: Page title, also used as the heading in the portal.
        slug:
          type: string
          description: URL segment of the page in the portal path.
        content:
          type: string
          description: The page content as Markdown.
        pageType:
          description: The template the page was created from.
          $ref: '#/components/schemas/DocPageType'
        structuredContent:
          type:
          - 'null'
          - string
          description: The editor representation of the content, as JSON.
        icon:
          type:
          - 'null'
          - string
          description: Icon name shown next to the page in the sidebar.
        createdAt:
          type: string
          description: When the page was created, in UTC.
          format: date-time
        modifiedAt:
          type:
          - 'null'
          - string
          description: When the page was last edited, in UTC. Null when it was never touched in this version.
          format: date-time
        rowVersion:
          type:
          - 'null'
          - string
          description: Base64 concurrency token. Send it back on the next update.
        isLocked:
          type: boolean
          description: Someone holds the page open in the editor, so it cannot be written.
      description: A single page with its Markdown content and its concurrency token.
    Branding:
      type: object
      properties:
        logoUrl:
          type:
          - 'null'
          - string
          description: Logo shown in the portal header. Null falls back to the plain title.
        primaryColor:
          type:
          - 'null'
          - string
          description: Primary brand color as a CSS color value.
        accentColor:
          type:
          - 'null'
          - string
          description: Accent color used for links and highlights, as a CSS color value.
        faviconUrl:
          type:
          - 'null'
          - string
          description: Icon shown in the browser tab.
        footerText:
          type:
          - 'null'
          - string
          description: Text placed in the portal footer, for example a copyright line.
      description: Logo, colors and footer of a public documentation portal.
    DocTreePage:
      required:
      - id
      - title
      - slug
      - pageType
      - isEmpty
      - hasEdits
      type: object
      properties:
        id:
          type: string
          description: Public id of the page, which the page endpoints take.
          format: uuid
        title:
          type: string
          description: Page title, also used as the heading in the portal.
        slug:
          type: string
          description: The segment this page gets in the portal URL.
        pageType:
          description: The template the page was created from.
          $ref: '#/components/schemas/DocPageType'
        icon:
          type:
          - 'null'
          - string
          description: Icon name shown next to the page in the sidebar.
        modifiedAt:
          type:
          - 'null'
          - string
          description: Last edit, falling back to creation. A display timestamp, in UTC.
          format: date-time
        modifiedByName:
          type:
          - 'null'
          - string
          description: Display name of whoever last edited the page.
        isEmpty:
          type: boolean
          description: The page has no content yet.
        hasEdits:
          type: boolean
          description: 'The page was actually edited inside this version. A freshly cloned version

            starts with this false everywhere, which is how you tell a real change from

            a carried-over page.

            '
      description: A content page inside the tree.
    DocTree:
      required:
      - items
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DocTreeNode'
          description: The root level of the tree. Folders carry their children inline.
      description: The page hierarchy of a documentation version.
    UpdateDocPageRequest:
      required:
      - title
      - content
      type: object
      properties:
        title:
          type: string
          description: New page title. Sending the old one leaves it unchanged.
        content:
          type: string
          description: Page content as Markdown.
        structuredContent:
          type:
          - 'null'
          - string
          description: The editor representation of the content as JSON. Send content instead unless you are mirroring the editor.
        icon:
          type:
          - 'null'
          - string
          description: Icon name to show next to the page in the sidebar.
        expectedRowVersion:
          type:
          - 'null'
          - string
          description: 'The `rowVersion` you read. When it no longer matches, the call is rejected

            with 409 instead of overwriting a competing edit.

            '
          format: byte
        slug:
          type:
          - 'null'
          - string
          description: New URL segment. The old one keeps redirecting.
      description: The new title and content of a page. Both replace what is there.
    DocPageType:
      enum:
      - custom
      - gettingStarted
      - authentication
      - environments
      - errorCodes
      type: string
      description: The template a documentation page was created from.
    CreateDocFolderResult:
      required:
      - id
      - slug
      type: object
      properties:
        id:
          type: string
          description: Public id of the new folder, which you pass as parentFolderPublicId to fill it.
          format: uuid
        slug:
          type: string
          description: URL segment the folder received, derived from the name unless you sent one.
      description: The id and slug the new folder received.
    Documentation:
      required:
      - id
      - customDomainVerified
      - branding
      - versioningScheme
      - requireApproval
      - portalEnabled
      - versions
      type: object
      properties:
        id:
          type: string
          description: Public id of the documentation.
          format: uuid
        customDomain:
          type:
          - 'null'
          - string
          description: Custom domain of the public portal.
        customDomainVerified:
          type: boolean
          description: Whether the DNS record for the custom domain has been checked and accepted.
        branding:
          description: Logo, colors and footer of the public portal.
          $ref: '#/components/schemas/Branding'
        versioningScheme:
          description: How this documentation numbers its versions.
          $ref: '#/components/schemas/VersionNumberingScheme'
        requireApproval:
          type: boolean
          description: Whether a version needs an approval before it can be published.
        portalEnabled:
          type: boolean
          description: Whether the public portal is switched on.
        versions:
          type: array
          items:
            $ref: '#/components/schemas/DocVersion'
          description: Every version of this documentation, newest and oldest alike.
        rowVersion:
          type:
          - 'null'
          - string
          description: Base64 concurrency token.
      description: A documentation with its portal settings, branding and the full list of its versions.
    GetDocumentationsResult:
      required:
      - documentations
      type: object
      properties:
        documentations:
          type: array
          items:
            $ref: '#/components/schemas/Documentation'
          description: The documentations of the project. A project usually has exactly one.
      description: The documentations of a project.
    CreateDocFolderRequest:
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: Folder name. It becomes the sidebar label and, unless you send a slug, the URL segment.
        icon:
          type:
          - 'null'
          - string
          description: Icon name to show next to the folder.
        description:
          type:
          - 'null'
          - string
          description: Intro text shown on the folder overview.
        parentFolderPublicId:
          type:
          - 'null'
          - string
          description: Folder to nest inside, or null for the root.
          format: uuid
        isSection:
          type: boolean
          description: 'Make this a top level section in the portal header instead of a sidebar

            entry. Only a folder at the root can be one.

            '
          default: false
        slug:
          type:
          - 'null'
          - string
          description: URL segment. Derived from the name when you leave it out.
      description: A new folder. Only the name is required.
  responses:
    BadRequest:
      description: The request was malformed or failed validation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: 'The resource does not exist, or it belongs to another organization or project.

        Both cases answer the same way on purpose, so the API cannot be used to probe

        for foreign identifiers.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: 'The API key is missing, invalid, expired or revoked. A US organization calling

        without `X-RB-Region: us` also lands here, because the request reached the wrong

        region.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Conflict:
      description: 'The resource changed since you read it. Reload it, reapply your change and send

        the fresh `rowVersion`. The `code` is `CONCURRENCY_CONFLICT`.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Forbidden:
      description: 'The key is valid but lacks the permission or the project scope for this call.

        A scoped key is also refused on organization level operations by design.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  parameters:
    DocId:
      name: DocId
      in: path
      description: Public id of the documentation.
      required: true
      schema:
        type: string
        format: uuid
    DocVersionId:
      name: DocVersionId
      in: path
      description: Public id of the documentation version.
      required: true
      schema:
        type: string
        format: uuid
    PageId:
      name: PageId
      in: path
      description: Public id of the documentation page.
      required: true
      schema:
        type: string
        format: uuid
    ProjectId:
      name: ProjectId
      in: path
      description: Public id of the project.
      required: true
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: 'An organization API key, created under Settings then API Keys. Keys start with

        `rb_live_` and carry their own permission scopes, so a key only reaches what it

        was granted.'
      name: X-API-Key
      in: header
    ScimBearerAuth:
      type: http
      description: 'The SCIM token of the organization, issued when SCIM provisioning is enabled.

        It is separate from an API key and only unlocks the SCIM endpoints.'
      scheme: bearer
x-routebase-folders:
- name: API Specs
  children: []
- name: CI & Test Runs
  children: []
- name: Docs as Code
  children: []
- name: SCIM
  children: []
- name: Security
  children: []