Associate file with knowledge base

curl --request POST \
  --url https://asteragents.com/api/kb/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kbId": 123,
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "quarterly-report.pdf",
  "fileKey": "org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf",
  "contentKey": "org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md",
  "contentType": "application/pdf",
  "fileSize": 1048576
}
'

{
  "success": true,
  "file": {
    "id": 456,
    "knowledgeBaseId": 123,
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "quarterly-report.pdf",
    "fileKey": "org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf",
    "contentKey": "org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md",
    "contentType": "application/pdf",
    "processingStatus": "completed",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z",
    "fileSize": 1048576,
    "processingError": null,
    "imageKeys": [
      "org_xxx/images/file-uuid/page-1.png",
      "org_xxx/images/file-uuid/page-2.png"
    ],
    "userMetadata": {},
    "extractedData": {}
  }
}

Knowledge Bases API

Associate file with knowledge base

Associate an uploaded file with a knowledge base and trigger processing.

This is Step 2 of the file upload flow (after uploading to the presigned URL).

What this endpoint does:

Creates a database record for the file
Triggers content extraction (text, images)
Triggers chunking and embedding generation
For PDFs, generates page images for preview

The orgId is automatically extracted from your JWT token - you don’t need to include it in the request body.

Complete upload flow:

1. POST /upload/presigned  → Get signed URL + file metadata
2. PUT to signed URL       → Upload file to storage
3. POST /kb/files          → Associate with KB & trigger processing

POST

files

Associate file with knowledge base

curl --request POST \
  --url https://asteragents.com/api/kb/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "kbId": 123,
  "fileId": "550e8400-e29b-41d4-a716-446655440000",
  "fileName": "quarterly-report.pdf",
  "fileKey": "org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf",
  "contentKey": "org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md",
  "contentType": "application/pdf",
  "fileSize": 1048576
}
'

{
  "success": true,
  "file": {
    "id": 456,
    "knowledgeBaseId": 123,
    "fileId": "550e8400-e29b-41d4-a716-446655440000",
    "fileName": "quarterly-report.pdf",
    "fileKey": "org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf",
    "contentKey": "org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md",
    "contentType": "application/pdf",
    "processingStatus": "completed",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z",
    "fileSize": 1048576,
    "processingError": null,
    "imageKeys": [
      "org_xxx/images/file-uuid/page-1.png",
      "org_xxx/images/file-uuid/page-2.png"
    ],
    "userMetadata": {},
    "extractedData": {}
  }
}

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

kbId

integer

required

The ID of the knowledge base to associate the file with

Example:

123

fileId

string<uuid>

required

The file UUID returned from the presigned upload endpoint

Example:

"550e8400-e29b-41d4-a716-446655440000"

fileName

string

required

Original filename

Example:

"quarterly-report.pdf"

fileKey

string

required

The storage key returned from the presigned upload endpoint

Example:

"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf"

contentKey

string

required

The content key returned from the presigned upload endpoint

Example:

"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md"

contentType

string

required

MIME type of the file

Example:

"application/pdf"

fileSize

integer

File size in bytes (optional but recommended)

Example:

1048576

Response

File associated and processing started

success

boolean

required

Example:

true

file

object

required

Show child attributes

file.id

integer

required

Database record ID

Example:

456

file.knowledgeBaseId

integer

required

ID of the parent knowledge base

Example:

123

file.fileId

string<uuid>

required

Unique file identifier (UUID)

Example:

"550e8400-e29b-41d4-a716-446655440000"

file.fileName

string

required

Original filename

Example:

"quarterly-report.pdf"

file.fileKey

string

required

Storage path for the original file

Example:

"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf"

file.contentKey

string

required

Storage path for extracted text content

Example:

"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md"

file.contentType

string

required

MIME type

Example:

"application/pdf"

file.processingStatus

enum<string>

required

Current processing status

Available options:

parsing,

parsed,

chunking,

chunk_failed,

parse_failed,

extract_failed,

completed

Example:

"completed"

file.createdAt

string<date-time>

required

When the file was associated

Example:

"2024-01-15T10:30:00.000Z"

file.updatedAt

string<date-time>

required

When the file was last updated

Example:

"2024-01-15T10:35:00.000Z"

file.fileSize

integer | null

File size in bytes

Example:

1048576

file.processingError

string | null

Error message if processing failed

Example:

null

file.imageKeys

string[] | null

Storage paths for generated page images (PDFs only)

Example:

[
  "org_xxx/images/file-uuid/page-1.png",
  "org_xxx/images/file-uuid/page-2.png"
]

file.userMetadata

object

Custom user-defined metadata

file.extractedData

object

Structured data extracted from the file (if extraction schema is configured)

Get presigned upload URL List files in a knowledge base

⌘I

API Documentation

Admin API

Files API

Knowledge Bases API

Other Endpoints

Legacy Endpoints (Deprecated)

Associate file with knowledge base

Authorizations

Body

Response