Skip to main content
POST
/
kb
/
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",
    "fileSize": 1048576,
    "processingStatus": "parsing",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

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

​
userMetadata
object

Optional metadata to attach to the file record. For inbound email files, this includes emailId, emailSubject, emailFrom, emailDate, and emailMessageId to link files from the same email.

Example:
{
  "source": "inbound-email",
  "emailId": "7ef4b7eb-4345-4f3f-ab95-ab76f7bd9634",
  "emailSubject": "Updated contract",
  "emailFrom": "user@example.com"
}

Response

File associated and processing started

​
success
boolean
required
Example:

true

​
file
object
required