Roark Knowledge Base API

openapi: 3.2.0
info:
  title: Roark Analytics Knowledge Base API
  description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
  version: 1.0.0
servers:
- description: Production
  url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Knowledge Base
paths:
  /v1/knowledge-base:
    get:
      responses:
        '200':
          description: A page of knowledge bases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Unique identifier of the knowledge base.
                        name:
                          type: string
                          description: Customer-supplied name. Unique within the project.
                        description:
                          type:
                          - string
                          - 'null'
                          description: Optional customer-supplied description.
                        sourceType:
                          type: string
                          enum:
                          - TEXT
                          - FILE
                          - JSON
                          - URL
                          description: How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown.
                        status:
                          type: string
                          enum:
                          - READY
                          - PROCESSING
                          - PENDING_UPLOAD
                          - FAILED
                          description: Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`.
                        originalFilename:
                          type:
                          - string
                          - 'null'
                          description: 'For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL.'
                        mimeType:
                          type:
                          - string
                          - 'null'
                          description: 'For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL.'
                        sourceUrl:
                          type:
                          - string
                          - 'null'
                          description: 'For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE.'
                        byteSize:
                          type: integer
                          minimum: 0
                          description: Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size.
                        contentHash:
                          type:
                          - string
                          - 'null'
                          description: SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content.
                        errorMessage:
                          type:
                          - string
                          - 'null'
                          description: When `status` is FAILED, the reason. Null otherwise.
                        createdAt:
                          type: string
                          description: Creation timestamp in ISO 8601 format.
                        updatedAt:
                          type: string
                          description: Last update timestamp in ISO 8601 format.
                      required:
                      - id
                      - name
                      - description
                      - sourceType
                      - status
                      - originalFilename
                      - mimeType
                      - sourceUrl
                      - byteSize
                      - contentHash
                      - errorMessage
                      - createdAt
                      - updatedAt
                      title: KnowledgeBase
                      description: A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time.
                  pagination:
                    type: object
                    properties:
                      total:
                        type: number
                        description: Total number of items
                      hasMore:
                        type: boolean
                        description: Whether there are more items to fetch
                      nextCursor:
                        type:
                        - string
                        - 'null'
                        description: Cursor for the next page of items
                    required:
                    - total
                    - hasMore
                    - nextCursor
                required:
                - data
                - pagination
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Knowledge-base
      tags:
      - Knowledge Base
      summary: List knowledge bases
      description: Returns a cursor-paginated list of knowledge bases for the authenticated project. Soft-deleted knowledge bases are excluded.
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      - in: query
        name: after
        schema:
          type: string
      - in: query
        name: searchText
        schema:
          type: string
      - in: query
        name: sourceType
        schema:
          type: string
          enum:
          - TEXT
          - FILE
          - JSON
          - URL
          description: How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown.
    post:
      responses:
        '201':
          description: The created knowledge base.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier of the knowledge base.
                      name:
                        type: string
                        description: Customer-supplied name. Unique within the project.
                      description:
                        type:
                        - string
                        - 'null'
                        description: Optional customer-supplied description.
                      sourceType:
                        type: string
                        enum:
                        - TEXT
                        - FILE
                        - JSON
                        - URL
                        description: How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown.
                      status:
                        type: string
                        enum:
                        - READY
                        - PROCESSING
                        - PENDING_UPLOAD
                        - FAILED
                        description: Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`.
                      originalFilename:
                        type:
                        - string
                        - 'null'
                        description: 'For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL.'
                      mimeType:
                        type:
                        - string
                        - 'null'
                        description: 'For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL.'
                      sourceUrl:
                        type:
                        - string
                        - 'null'
                        description: 'For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE.'
                      byteSize:
                        type: integer
                        minimum: 0
                        description: Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size.
                      contentHash:
                        type:
                        - string
                        - 'null'
                        description: SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content.
                      errorMessage:
                        type:
                        - string
                        - 'null'
                        description: When `status` is FAILED, the reason. Null otherwise.
                      createdAt:
                        type: string
                        description: Creation timestamp in ISO 8601 format.
                      updatedAt:
                        type: string
                        description: Last update timestamp in ISO 8601 format.
                    required:
                    - id
                    - name
                    - description
                    - sourceType
                    - status
                    - originalFilename
                    - mimeType
                    - sourceUrl
                    - byteSize
                    - contentHash
                    - errorMessage
                    - createdAt
                    - updatedAt
                    title: KnowledgeBase
                    description: A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time.
                required:
                - data
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Validation error
              example:
                type: validation
                code: invalid_parameter
                message: The request was invalid
                param: email
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: postV1Knowledge-base
      tags:
      - Knowledge Base
      summary: Create a knowledge base
      description: Creates a knowledge base. TEXT and JSON sources accept inline `content`. FILE sources require `filename`, `mimeType`, and base64-encoded `contentBase64` — the file is decoded server-side, stored in S3, and (for PDFs) text-extracted inline before the response returns.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Customer-facing name. Unique within the project. Required.
                description:
                  type:
                  - string
                  - 'null'
                  maxLength: 500
                  description: Optional short blurb shown in pickers.
                sourceType:
                  type: string
                  enum:
                  - TEXT
                  - FILE
                  - JSON
                  description: Source types accepted via the public create endpoint. URL ingestion is currently only available in the platform UI.
                content:
                  type:
                  - string
                  - 'null'
                  description: 'For TEXT: raw markdown/text. For JSON: a JSON string (validated server-side and re-formatted with stable whitespace). Required for TEXT and JSON; omit for FILE.'
                filename:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  maxLength: 255
                  description: 'For FILE: customer-supplied filename (informational only — used for download links).'
                mimeType:
                  type:
                  - string
                  - 'null'
                  enum:
                  - application/pdf
                  - text/plain
                  - text/markdown
                  description: 'For FILE: mime type of the uploaded file. Only `application/pdf`, `text/plain`, and `text/markdown` are accepted.'
                contentBase64:
                  type:
                  - string
                  - 'null'
                  description: 'For FILE: base64-encoded file bytes. Required for FILE. Max 10 MB after decoding. PDFs are text-extracted server-side; image-only PDFs are rejected.'
              required:
              - name
              - sourceType
              title: CreateKnowledgeBaseInput
              description: Input for creating a knowledge base. See `sourceType` for which fields are required.
  /v1/knowledge-base/{id}:
    get:
      responses:
        '200':
          description: The requested knowledge base.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier of the knowledge base.
                      name:
                        type: string
                        description: Customer-supplied name. Unique within the project.
                      description:
                        type:
                        - string
                        - 'null'
                        description: Optional customer-supplied description.
                      sourceType:
                        type: string
                        enum:
                        - TEXT
                        - FILE
                        - JSON
                        - URL
                        description: How the knowledge base content was provided. TEXT/JSON are stored as-is; FILE was uploaded and its text content extracted (PDF → text); URL was scraped from a webpage into markdown.
                      status:
                        type: string
                        enum:
                        - READY
                        - PROCESSING
                        - PENDING_UPLOAD
                        - FAILED
                        description: Lifecycle of the knowledge base. READY means the content is available to metrics. PROCESSING is set during PDF text extraction. FAILED means extraction errored — see `errorMessage`.
                      originalFilename:
                        type:
                        - string
                        - 'null'
                        description: 'For FILE source: the customer-supplied filename. Null for TEXT/JSON/URL.'
                      mimeType:
                        type:
                        - string
                        - 'null'
                        description: 'For FILE source: the mime type of the uploaded file. Null for TEXT/JSON/URL.'
                      sourceUrl:
                        type:
                        - string
                        - 'null'
                        description: 'For URL source: the page that was scraped into markdown. Null for TEXT/JSON/FILE.'
                      byteSize:
                        type: integer
                        minimum: 0
                        description: Size of the content the model will read at evaluation time. For FILE this is the EXTRACTED text size, not the original PDF size.
                      contentHash:
                        type:
                        - string
                        - 'null'
                        description: SHA-256 of the content. Stable across whitespace-equivalent edits for JSON (pretty-printed before hashing). Use it to detect change without diffing the content.
                      errorMessage:
                        type:
                        - string
                        - 'null'
                        description: When `status` is FAILED, the reason. Null otherwise.
                      createdAt:
                        type: string
                        description: Creation timestamp in ISO 8601 format.
                      updatedAt:
                        type: string
                        description: Last update timestamp in ISO 8601 format.
                    required:
                    - id
                    - name
                    - description
                    - sourceType
                    - status
                    - originalFilename
                    - mimeType
                    - sourceUrl
                    - byteSize
                    - contentHash
                    - errorMessage
                    - createdAt
                    - updatedAt
                    title: KnowledgeBase
                    description: A customer-uploaded reference document attached to custom metrics as ground truth at evaluation time.
                required:
                - data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Authentication error
              example:
                type: authentication
                code: unauthorized
                message: Authentication required
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Not found error
              example:
                type: not_found
                code: resource_not_found
                message: The requested resource could not be found
          description: Not Found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
                description: Server error
              example:
                type: internal
                code: internal_error
                message: Internal server error
          description: Internal Server Error
      operationId: getV1Knowledge-baseById
      tags:
      - Knowledge Base
      summary: Get a knowledge base by ID
      description: Returns metadata for a single knowledge base. Does not include content — content is read by metrics at evaluation time and is not exposed over the public API.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Knowledge base ID
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
          - validation
          - authentication
          - forbidden
          - not_found
          - conflict
          - payment_required
          - rate_limit
          - internal
          description: The error type category
          examples:
          - validation
          - authentication
        code:
          type: string
          description: Machine-readable error code identifier
          examples:
          - invalid_parameter
          - missing_required_field
          - unauthorized
        message:
          type: string
          description: Human-readable error message
          examples:
          - The request was invalid
          - Authentication required
        param:
          type: string
          description: The parameter that caused the error (if applicable)
          examples:
          - email
          - user_id
        details:
          description: Additional error context information
      required:
      - type
      - code
      - message
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT