Roark Knowledge Base API
The Knowledge Base API from Roark — 2 operation(s) for knowledge base.
The Knowledge Base API from Roark — 2 operation(s) for knowledge base.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/roark:roark-knowledge-base-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
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