Beyond Presence Agent Knowledge Files API
Manage the knowledge base documents your Managed Agents can draw on during a conversation.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/beyond-presence:beyond-presence-agent-knowledge-files-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API 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 Specification
openapi: 3.2.0
info:
title: Beyond Presence Agent Knowledge Files API
summary: Create, configure, and run interactive real-time avatars.
description: 'The Beyond Presence API lets you build lifelike, real-time avatars.
## Starting a conversation with a Managed Agent
There are two ways to put a user in front of one of your agents, and most
integrations only need the first:
1. **Open the agent''s managed room** at `https://bey.chat/`. This
needs no API call at all and is available on every plan. Use the
`Agent Conversations` endpoints afterwards to read status and transcripts.
2. **Drive the media session yourself** from a LiveKit client SDK, using
`POST /v1/livekit-rooms` in the `Agent Integration` group to mint room
credentials. This requires the Growth plan or above.
## Authentication
Authenticate every request with your API key in the `x-api-key` header:
```
x-api-key:
```
You can create and manage API keys in the dashboard, and verify a key with
`GET /v1/auth/verify`.
## Pagination
List endpoints are cursor-paginated. Pass `limit` (1-50, default 10) to control
the page size and `cursor` to fetch the next page. Each response includes a
`next_cursor` when more results are available.
## Errors
Errors return the appropriate HTTP status code with a JSON body containing a
`detail` message with more information.
## Rate limits
Usage and concurrency limits are tied to your plan and surfaced as HTTP `429`
responses.'
version: 0.3.0
servers:
- url: https://api.bey.dev
tags:
- name: Agent Knowledge Files
description: Manage the knowledge base documents your Managed Agents can draw on during a conversation.
paths:
/v1/knowledge-files:
get:
tags:
- Agent Knowledge Files
summary: List Knowledge Files
description: 'List your knowledge files.
Returns a cursor-paginated list of the knowledge files you own, along with
their processing status.'
operationId: list_knowledge_files_v1_knowledge_files_get
security:
- APIKeyHeader: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
exclusiveMinimum: 0
description: Maximum number of objects to return.
default: 10
title: Limit
description: Maximum number of objects to return.
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for pagination.
title: Cursor
description: Cursor for pagination.
responses:
'200':
description: Paginated List of Knowledge Files
content:
application/json:
schema:
$ref: '#/components/schemas/Page_KnowledgeFileResponse_'
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
tags:
- Agent Knowledge Files
summary: Create Knowledge File
description: 'Create a knowledge file and start its upload.
Text files are stored immediately and begin indexing, so they come back
as `processing` and are ready to attach to an agent once they read
`available`. PDF files begin a chunked upload: use the returned ID to
upload each chunk via `PUT /{id}/upload`, then finalize with
`POST /{id}/submit`.'
operationId: create_knowledge_file_v1_knowledge_files_post
security:
- APIKeyHeader: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateKnowledgeFileRequest'
responses:
'201':
description: Created Knowledge File
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeFileResponse'
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/knowledge-files/{id}:
get:
tags:
- Agent Knowledge Files
summary: Retrieve Knowledge File
description: Retrieve a single knowledge file by ID, including its extracted text.
operationId: get_knowledge_file_v1_knowledge_files__id__get
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Knowledge File ID.
title: Id
description: Knowledge File ID.
responses:
'200':
description: Requested Knowledge File
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeFileResponse'
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
tags:
- Agent Knowledge Files
summary: Delete Knowledge File
description: 'Delete a knowledge file.
Fails if any of your agents still references the file; detach it from those
agents first.'
operationId: delete_knowledge_file_v1_knowledge_files__id__delete
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Knowledge File ID.
title: Id
description: Knowledge File ID.
responses:
'204':
description: Successful Response
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/knowledge-files/{id}/upload:
put:
tags:
- Agent Knowledge Files
summary: Upload Knowledge File Chunk
description: 'Upload a single chunk of a PDF knowledge file.
Send the raw chunk bytes as the request body. Chunks are zero-indexed via
the `chunk_number` query parameter and can be uploaded in any order.'
operationId: upload_knowledge_file_chunk_v1_knowledge_files__id__upload_put
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Knowledge File ID.
title: Id
description: Knowledge File ID.
- name: chunk_number
in: query
required: true
schema:
type: integer
minimum: 0
description: Chunk number, starting from 0.
title: Chunk Number
description: Chunk number, starting from 0.
responses:
'204':
description: Successful Response
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/knowledge-files/{id}/submit:
post:
tags:
- Agent Knowledge Files
summary: Submit Knowledge File
description: 'Finalize a chunked knowledge file upload.
Assembles the uploaded chunks and starts extracting and indexing them.
Returns the file as `processing`; it becomes `available` once that
finishes, which takes minutes for a long document.'
operationId: submit_knowledge_file_v1_knowledge_files__id__submit_post
security:
- APIKeyHeader: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Knowledge File ID.
title: Id
description: Knowledge File ID.
responses:
'200':
description: Processed Knowledge File
content:
application/json:
schema:
$ref: '#/components/schemas/KnowledgeFileResponse'
'401':
description: Authentication failed. The `x-api-key` header is missing or the provided API key is invalid.
content:
application/json:
examples:
missing:
summary: Missing API key
value:
detail: API key is required.
invalid:
summary: Invalid API key
value:
detail: Invalid API key.
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The API key is valid but not permitted to perform this action, either because the resource belongs to someone else or because the requested feature requires a plan upgrade.
content:
application/json:
examples:
permission:
summary: Not permitted
value:
detail: You do not have permission to access this resource.
plan:
summary: Plan upgrade required
value:
detail: This feature is not available on your current plan. Please upgrade your plan.
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The requested resource does not exist or is not accessible with this API key.
content:
application/json:
example:
detail: The requested resource was not found.
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request is malformed. `detail` lists each field that failed validation, where it was located, and why.
content:
application/json:
example:
detail:
- loc:
- body
- name
msg: Field required
type: missing
'429':
description: A plan limit has been exceeded, either the usage limit or the number of concurrent sessions.
content:
application/json:
examples:
usage:
summary: Usage limit exceeded
value:
detail: Usage limit exceeded. Please upgrade your plan.
concurrency:
summary: Concurrency limit exceeded
value:
detail: You have reached your concurrency limit. Please upgrade your plan or stop other ongoing sessions.
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
FailedKnowledgeFileResponse:
properties:
id:
type: string
title: Id
description: Unique identifier of the object in the database.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
$ref: '#/components/schemas/KnowledgeFileFormat'
status:
type: string
const: failed
title: Status
default: failed
reason:
type: string
title: Reason
type: object
required:
- id
- name
- format
- reason
title: FailedKnowledgeFileResponse
description: Response model for a knowledge file that could not be processed.
AvailableKnowledgeFileResponse:
properties:
id:
type: string
title: Id
description: Unique identifier of the object in the database.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
$ref: '#/components/schemas/KnowledgeFileFormat'
status:
type: string
const: available
title: Status
default: available
text:
type: string
title: Text
description: Text extracted from the file. Shortened to the start of the file when it is a large one; see `is_text_complete`.
is_text_complete:
type: boolean
title: Is Text Complete
description: Whether `text` is the whole file rather than the start of it. A large file is stored and searched in full either way; this only says how much of it this endpoint hands back.
type: object
required:
- id
- name
- format
- text
- is_text_complete
title: AvailableKnowledgeFileResponse
description: Response model for an available knowledge file.
CreateKnowledgeFileRequest:
oneOf:
- $ref: '#/components/schemas/CreateTextKnowledgeFileRequest'
- $ref: '#/components/schemas/CreatePdfKnowledgeFileRequest'
discriminator:
propertyName: format
mapping:
pdf: '#/components/schemas/CreatePdfKnowledgeFileRequest'
text: '#/components/schemas/CreateTextKnowledgeFileRequest'
CreateTextKnowledgeFileRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
type: string
const: text
title: Format
content:
type: string
maxLength: 250000
minLength: 1
title: Content
type: object
required:
- name
- format
- content
title: CreateTextKnowledgeFileRequest
description: Request model for creating a text knowledge file.
Page_KnowledgeFileResponse_:
anyOf:
- $ref: '#/components/schemas/HasMorePage_KnowledgeFileResponse_'
- $ref: '#/components/schemas/NoMorePage_KnowledgeFileResponse_'
ToUploadKnowledgeFileResponse:
properties:
id:
type: string
title: Id
description: Unique identifier of the object in the database.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
$ref: '#/components/schemas/KnowledgeFileFormat'
status:
type: string
const: to-upload
title: Status
default: to-upload
type: object
required:
- id
- name
- format
title: ToUploadKnowledgeFileResponse
description: Response model for a knowledge file that is to be uploaded.
KnowledgeFileFormat:
type: string
enum:
- text
- pdf
title: KnowledgeFileFormat
description: Format of the knowledge file.
CreatePdfKnowledgeFileRequest:
properties:
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
type: string
const: pdf
title: Format
upload_num_chunks:
type: integer
maximum: 1000.0
exclusiveMinimum: 0.0
title: Upload Num Chunks
type: object
required:
- name
- format
- upload_num_chunks
title: CreatePdfKnowledgeFileRequest
description: Request model for creating a PDF knowledge file.
ProcessingKnowledgeFileResponse:
properties:
id:
type: string
title: Id
description: Unique identifier of the object in the database.
examples:
- 01234567-89ab-cdef-0123-456789abcdef
name:
type: string
maxLength: 100
minLength: 1
title: Name
examples:
- Hitchhiker's Guide to the Galaxy
format:
$ref: '#/components/schemas/KnowledgeFileFormat'
status:
type: string
const: processing
title: Status
default: processing
type: object
required:
- id
- name
- format
title: ProcessingKnowledgeFileResponse
description: Response model for a knowledge file that is still being processed.
NoMorePage_KnowledgeFileResponse_:
properties:
data:
items:
$ref: '#/components/schemas/KnowledgeFileResponse'
type: array
title: Data
description: List of objects.
has_more:
type: boolean
const: false
title: Has More
description: Whether there are more objects to fetch.
default: false
type: object
required:
- data
title: NoMorePage[KnowledgeFileResponse]
ErrorResponse:
properties:
detail:
type: string
title: Detail
description: Human-readable description of the error.
examples:
- Invalid API key.
type: object
required:
- detail
title: ErrorResponse
description: 'Standard error response body.
Carries a single human-readable `detail` message describing what went
wrong. This is the shape of every error response except validation errors
(`422`), which instead return a list of per-field error objects.'
KnowledgeFileResponse:
oneOf:
- $ref: '#/components/schemas/ToUploadKnowledgeFileResponse'
- $ref: '#/components/schemas/ProcessingKnowledgeFileResponse'
- $ref: '#/components/schemas/AvailableKnowledgeFileResponse'
- $ref: '#/components/schemas/FailedKnowledgeFileResponse'
discriminator:
propertyName: status
mapping:
available: '#/components/schemas/AvailableKnowledgeFileResponse'
failed: '#/components/schemas/FailedKnowledgeFileResponse'
processing: '#/components/schemas/ProcessingKnowledgeFileResponse'
to-upload: '#/components/schemas/ToUploadKnowledgeFileResponse'
HasMorePage_KnowledgeFileResponse_:
properties:
data:
items:
$ref: '#/components/schemas/KnowledgeFileResponse'
type: array
title: Data
description: List of objects.
has_more:
type: boolean
const: true
title: Has More
description: Whether there are more objects to fetch.
default: true
next_cursor:
type: string
title: Next Cursor
description: The cursor for the next page of objects.
type: object
required:
- data
- next_cursor
title: HasMorePage[KnowledgeFileResponse]
securitySchemes:
APIKeyHeader:
type: apiKey
description: Your Beyond Presence API Key.
in: header
name: x-api-key
x-provenance:
method: harvested
publisher: Beyond Presence
source: https://api.bey.dev/openapi.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)