Archbee Public API

openapi: 3.1.0
info:
  title: Archbee Public API
  description: The Archbee Public API manages documentation spaces, documents, space groups, File Manager
    files, reader suggestions, organization exports and imported OpenAPI references in an Archbee workspace.
    Authentication uses an HTTP Bearer token whose value is base64(docSpaceId~apiKey), or a team key beginning
    abteam_.
  version: '2026-09-04'
  contact:
    name: Archbee Support
    email: support@archbee.com
    url: https://www.archbee.com/
  termsOfService: https://www.archbee.com/terms-of-service
  x-generated-from: https://www.archbee.com/docs/<slug>.md api-oas-v2 blocks published by Archbee
  x-generated-by: API Evangelist enrichment pipeline, local-v3
  x-generated-date: '2026-09-04'
servers:
- url: https://api.archbee.com/api/public-api
  description: Archbee API Server
security:
- bearerAuth: []
tags:
- name: API Reference
  description: Sync and inspect an imported OpenAPI reference
- name: Access Control
  description: Magic-link access requests for gated portals
- name: Documents
  description: Create, read, update, delete and search documents
- name: File Manager
  description: Upload, list, move, replace and delete File Manager files
- name: Organization
  description: Organization-level export and display rules
- name: Space Groups
  description: Grouping of documentation spaces
- name: Spaces
  description: Documentation space lifecycle — create, update, clone, publish, delete
- name: Suggestions
  description: Reader-submitted suggested changes — merge or discard
paths:
  /access-control/request:
    post:
      operationId: requestMagicLinkAccess
      summary: Request Magic Link Access
      tags:
      - Access Control
      x-source-doc: https://www.archbee.com/docs/request-magic-link-access
      description: 'Submit a reader''s email as a pending request to be added to the space''s magic-link
        whitelist. The request does NOT grant access on its own — an admin must approve it. The space
        must be configured for Magic Link (Magic Link enabled, the portal gating content, and the team''s
        plan allowing it); otherwise the request is refused with 400. There is one request per (email,
        space). A repeat request for the same email is idempotent per status: a Pending request returns
        the existing row unchanged; an Accepted request whose email is still whitelisted also returns
        it unchanged; but an Accepted request whose access was later revoked, or a previously Rejected
        request, is put back into the Pending queue and re-notifies the admins — so a rejected or revoked
        reader can always re-apply.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  enum:
                  - email
                  description: Email address requesting access
                  example: reader@example.com
              required:
              - email
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: access control request id
                      status:
                        type: string
                        enum:
                        - Pending
                        - Accepted
                        - Rejected
                        description: request status
                description: Process status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /doc:
    delete:
      operationId: deleteDocument
      summary: Delete document
      tags:
      - Documents
      x-source-doc: https://www.archbee.com/docs/delete-document
      description: Delete document by docId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docId:
                  type: string
                  description: Document id that will be permanently deleted.
                  example: 21-character__string0
              required:
              - docId
      responses:
        '200':
          description: Delete status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                  data:
                    type: object
                    properties:
                      status:
                        type: boolean
                description: Delete status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
    get:
      operationId: getDocument
      summary: Get document
      tags:
      - Documents
      x-source-doc: https://www.archbee.com/docs/get-document
      description: Retrieve a document in markdown, html, json, or source format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docId:
                  type: string
                  description: The ID of the document to be returned.
                  example: 21-character__string0
                format:
                  type: string
                  enum:
                  - markdown
                  - html
                  - json
                  - source
                  description: The format of the returned data. Default is markdown.
                  example: markdown
              required:
              - docId
      responses:
        '200':
          description: Successful response containing the document content.
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: The content of the document in the specified format.
                  format:
                    type: string
                    description: The format of the returned document.
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
    post:
      operationId: updateCreateDocument
      summary: Update / Create document
      tags:
      - Documents
      x-source-doc: https://www.archbee.com/docs/update-create-document
      description: Create / Update Doc by docId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: markdown, MDX or JSON content used to update the document.
                  example: '# this is a h1 title

                    And this is a paragraph

                    - list item 1

                    - list item 2'
                format:
                  type: string
                  enum:
                  - markdown
                  - mdx
                  - json
                  description: OPTIONAL. Specify the format of the content. Default is markdown. Use mdx
                    when the content contains JSX-style Archbee components (<hint>, <CtaButton />, <Tabs>);
                    directive-style components (:::hint{type="info"}) work in both markdown and mdx.
                  example: markdown
                title:
                  type: string
                  description: OPTIONAL, set the name of the document.
                description:
                  type: string
                  description: OPTIONAL, set the description of the document.
                previewImgURL:
                  type: string
                  description: OPTIONAL, set the preview image URL of the document.
                slug:
                  type: string
                  description: OPTIONAL, set the slug (url key) of the document.
                alias:
                  type: string
                  description: OPTIONAL, set the url alias.
                conditionalRuleId:
                  type: string
                  description: OPTIONAL, set the conditional rule id.
                sorting:
                  type: string
                  enum:
                  - alphabetical
                  - chronological
                  description: OPTIONAL. Specify the type of ordering for document insertion.
                  example: alphabetical
                hidden:
                  type: boolean
                  description: OPTIONAL, set document as hidden or not.
                docId:
                  type: string
                  description: OPTIONAL, document id. If present and valid, the doc will be updated.
                  example: 21-character__string0
                parentDocId:
                  type: string
                  description: OPTIONAL, parent document id. If present and valid, the parent docId will
                    be updated. If sent empty, the document will be moved to the root of the tree.
                  example: 21-character__string0
              required:
              - content
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response status.
                  data:
                    type: object
                    properties:
                      docId:
                        type: string
                      newRecord:
                        type: boolean
                description: Process status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /docs/search:
    post:
      operationId: searchDocument
      summary: Search document
      tags:
      - Documents
      x-source-doc: https://www.archbee.com/docs/search-document
      description: 'Search Archbee documents in docSpace. Can perform one of the 3 types of search:


        ai-chat to return ai generative answer accompanied by source docs;

        ai-retrieval to return just similar docs with the query;

        words to perform normal search aka. "word-based"; use empty query to return all docs

        single-doc to return document info by id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Filter text, question or document title
                searchOnlyTitle:
                  type: boolean
                  description: OPTIONAL. Search only by title
                persistSearch:
                  type: boolean
                  description: OPTIONAL. Wether to keep a SearchSession in our database and return its
                    id.
                searchSessionId:
                  type: string
                  description: OPTIONAL. id for the SearchSession object to update. More useful for AI
                    chat.
                docId:
                  type: string
                  description: OPTIONAL. Return only one document with this id, if there is one
                  example: 21-character__string0
                dataTextFormat:
                  type: string
                  enum:
                  - markdown
                  - html
                  description: OPTIONAL. Return documents with dataText in this format
                parentDocId:
                  type: string
                  description: OPTIONAL. Return only child documents of the doc with this id, if there
                    are any. Can be "null" for retrieving the root docs.
                  example: 21-character__string0
                type:
                  type: string
                  enum:
                  - words
                  - ai-chat
                  - ai-retrieval
                  description: OPTIONAL. which type of search to use; default is word-based
              required:
              - query
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                  data:
                    type: object
                    properties:
                      searchSessionId:
                        type: string
                        description: Search session id, can be used as input for next search calls.
                      docs:
                        type: object
                        properties:
                          id:
                            type: string
                            description: Archbee id, used for private access
                          name:
                            type: string
                            description: name of document
                          urlKey:
                            type: string
                            description: url of public document, used for public access (if published)
                          urlAlias:
                            type: string
                            description: In case you are migrating from another platform and you’d like
                              to get a redirecting url to your current url, you can use this url path.
                          hidden:
                            type: boolean
                            description: indicates if document is hidden
                          privacy:
                            type: string
                            enum:
                            - private
                            - shared with team
                            - public-via-link
                            - public
                            description: describes how to access the document via public url (if published)
                          highlight:
                            type: object
                            description: text from document, similar with query (word-based search only)
                        description: Array of Doc responses
                    description: Response Data
                description: Process status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /file-manager/file:
    delete:
      operationId: deleteAFileManagerFile
      summary: Delete a File Manager file
      tags:
      - File Manager
      x-source-doc: https://www.archbee.com/docs/delete-a-file-manager-file
      description: Permanently delete a File Manager file or folder (folders delete their contents recursively).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fileId:
                  type: string
                  description: Id of the file or folder to delete.
              required:
              - fileId
      responses:
        '200':
          description: Delete OK status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /file-manager/files:
    get:
      operationId: listFileManagerFiles
      summary: List File Manager files
      tags:
      - File Manager
      x-source-doc: https://www.archbee.com/docs/list-file-manager-files
      description: List files and folders in the File Manager. Omitting parentId lists every entry across
        all folders (use searchQuery/pagination to find one); pass a folder id to list that folder's direct
        children. Filter with itemType (directory, image, or file).
      parameters:
      - name: parentId
        in: query
        required: false
        schema:
          type: string
        description: OPTIONAL. Folder id to list the direct children of. Omit to list all entries across
          every folder.
      - name: itemType
        in: query
        required: false
        schema:
          type: string
          enum:
          - directory
          - image
          - file
        description: OPTIONAL. Filter by entry type.
      - name: searchQuery
        in: query
        required: false
        schema:
          type: string
        description: OPTIONAL. Case-insensitive filename filter.
      - name: pageIndex
        in: query
        required: false
        schema:
          type: integer
        description: OPTIONAL. Zero-based page index (default 0).
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
        description: OPTIONAL. Page size (1-200).
      responses:
        '200':
          description: List OK status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /file-manager/move:
    post:
      operationId: moveAFileManagerFile
      summary: Move a File Manager file
      tags:
      - File Manager
      x-source-doc: https://www.archbee.com/docs/move-a-file-manager-file
      description: Move a File Manager file or folder into another folder. Pass a null newParentId to
        move it to the root.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fileId:
                  type: string
                  description: Id of the file or folder to move.
                newParentId:
                  type: string
                  description: Destination folder id, or null for the root.
              required:
              - fileId
              - newParentId
      responses:
        '200':
          description: Move OK status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /file-manager/replace:
    post:
      operationId: overwriteAFileManagerFile
      summary: Overwrite a File Manager file
      tags:
      - File Manager
      x-source-doc: https://www.archbee.com/docs/overwrite-a-file-manager-file
      description: Replace the contents of an existing File Manager file in place. The file keeps its
        id and public URL, so existing document embeds update automatically.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                fileId:
                  type: string
                  description: Id of the existing file to overwrite.
                file:
                  type: string
                  format: binary
                  description: New file contents.
              required:
              - fileId
              - file
      responses:
        '200':
          description: Overwrite OK status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /import-content:
    post:
      operationId: importContent
      summary: Import Content
      tags:
      - Documents
      x-source-doc: https://www.archbee.com/docs/import-content
      description: Create new Doc from imported markdown file. In case of zip file, create a new docTree
        and keeps archived tree structure.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Markdown file (.md) or archive (.zip) containing multiple markdown files.
                  example: upload file
                  default: '@markdowns.zip'
                type:
                  type: string
                  enum:
                  - markdown
                  description: Type of import file. Only markdown supported for now on this route.
                  example: markdown
                  default: markdown
              required:
              - file
      responses:
        '200':
          description: Import OK status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                    example: OK
                  data:
                    type: object
                    properties:
                      docId:
                        type: string
                        description: Created Doc id (first doc in case of archive tree).
                        example: 21-character__string0
                description: Import OK status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /info-api-reference:
    get:
      operationId: infoOpenApiDocument
      summary: Info Open Api document
      tags:
      - API Reference
      x-source-doc: https://www.archbee.com/docs/info-open-api-document
      description: Get info of an existing Open Api tree
      requestBody:
        required: false
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                docTreeId:
                  type: string
                  description: DocTree id is main category id where open api was imported.
                  example: 21-character__string0
      responses:
        '200':
          description: Status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                    example: OK
                  data:
                    type: object
                    properties:
                      result:
                        type: string
                      importedContent:
                        type: string
                description: Status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /space-group/create:
    post:
      operationId: createSpaceGroup
      summary: Create Space Group
      tags:
      - Space Groups
      x-source-doc: https://www.archbee.com/docs/create-space-group
      description: Create a new space group with desired fields, return the space group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: name of space group
                isLlmEnabled:
                  type: boolean
                  description: whether AI will be enabled
                isReviewSystemEnabled:
                  type: boolean
                  description: whether review system will be enabled
                isBranchingSystemEnabled:
                  type: boolean
                  description: whether branching will be enabled
              required:
              - name
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response Status
                description: Process status
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    - Not OK
                    description: Response Status
                    example: Not OK
                  messages:
                    type: array
                    items:
                      type: string
                      example: Some error message
                    description: Array of messages
                    example: '["Some error message"]'
  /space-group/delete:
    delete:
      operationId: deleteSpaceGroup
      summary: Delete Space Group
      tags:
      - Space Groups
      x-source-doc: https://www.archbee.com/docs/delete-space-group
      description: Delete Archbee space group with given spaceGroupId.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spaceGroupId:
                  type: string
                  description: Space group id to delete.
                  example: 21-character__string0
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - OK
                    description: Response S

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archbee/refs/heads/main/openapi/archbee-public-api-openapi.yml