> ## Documentation Index > Fetch the complete documentation index at: https://docs.bey.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Knowledge File > Create a knowledge file and start its upload. Text files are stored immediately. PDF files begin a chunked upload: use the returned ID to upload each chunk via `PUT /{id}/upload`, then finalize with `POST /{id}/submit`. ## OpenAPI ````yaml /openapi.json post /v1/knowledge-files openapi: 3.1.0 info: title: Beyond Presence 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 security: [] tags: - name: Avatars description: Retrieve information about the avatars available to your account. - name: Agents description: Create and configure Managed Agents. - name: Agent Conversations description: >- Retrieve information about the conversations your Managed Agents have had, including their status, participants, and transcripts. - name: Agent Integration description: >- Primitives for embedding a Managed Agent in your own application with advanced cusotmization. **Most integrations do not need these.** - name: Agent Knowledge Files description: >- Manage the knowledge base documents your Managed Agents can draw on during a conversation. - name: Agents External APIs description: >- Store credentials for external services, such as an OpenAI-compatible LLM, so Managed Agents can reference them by ID. - name: Authentication description: Verify your API key. - name: Speech-to-Video Sessions description: >- Attach an avatar to a voice agent you build and run yourself. Prefer using the [LiveKit Plugin](https://docs.bey.dev/integrations/voice-agents/livekit) over calling these endpoints directly. paths: /v1/knowledge-files: post: tags: - Agent Knowledge Files summary: Create Knowledge File description: >- Create a knowledge file and start its upload. Text files are stored immediately. 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 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' security: - APIKeyHeader: [] components: schemas: CreateKnowledgeFileRequest: oneOf: - $ref: '#/components/schemas/CreateTextKnowledgeFileRequest' - $ref: '#/components/schemas/CreatePdfKnowledgeFileRequest' discriminator: propertyName: format mapping: pdf: $ref: '#/components/schemas/CreatePdfKnowledgeFileRequest' text: $ref: '#/components/schemas/CreateTextKnowledgeFileRequest' KnowledgeFileResponse: oneOf: - $ref: '#/components/schemas/ToUploadKnowledgeFileResponse' - $ref: '#/components/schemas/AvailableKnowledgeFileResponse' discriminator: propertyName: status mapping: available: $ref: '#/components/schemas/AvailableKnowledgeFileResponse' to-upload: $ref: '#/components/schemas/ToUploadKnowledgeFileResponse' 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. 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: 100000 minLength: 1 title: Content type: object required: - name - format - content title: CreateTextKnowledgeFileRequest description: Request model for creating a text 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 exclusiveMinimum: 0 title: Upload Num Chunks type: object required: - name - format - upload_num_chunks title: CreatePdfKnowledgeFileRequest description: Request model for creating a PDF knowledge file. 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. 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 type: object required: - id - name - format - text title: AvailableKnowledgeFileResponse description: Response model for an available knowledge file. KnowledgeFileFormat: type: string enum: - text - pdf title: KnowledgeFileFormat description: Format of the knowledge file. securitySchemes: APIKeyHeader: type: apiKey description: Your Beyond Presence API Key. in: header name: x-api-key ```` ## Related topics - [Submit Knowledge File](/api-reference/agent-knowledge-files/submit-knowledge-file.md) - [List Knowledge Files](/api-reference/agent-knowledge-files/list-knowledge-files.md) - [Delete Knowledge File](/api-reference/agent-knowledge-files/delete-knowledge-file.md) - [Retrieve Knowledge File](/api-reference/agent-knowledge-files/retrieve-knowledge-file.md) - [Upload Knowledge File Chunk](/api-reference/agent-knowledge-files/upload-knowledge-file-chunk.md)