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
}
'

import requests

url = "https://asteragents.com/api/kb/files"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://asteragents.com/api/kb/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://asteragents.com/api/kb/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://asteragents.com/api/kb/files"

	payload := strings.NewReader("{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://asteragents.com/api/kb/files")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/kb/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}"

response = http.request(request)
puts response.read_body

{
  "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"
  }
}

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
}
'

import requests

url = "https://asteragents.com/api/kb/files"

payload = {
    "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
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://asteragents.com/api/kb/files', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://asteragents.com/api/kb/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://asteragents.com/api/kb/files"

	payload := strings.NewReader("{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://asteragents.com/api/kb/files")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://asteragents.com/api/kb/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"kbId\": 123,\n  \"fileId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"fileName\": \"quarterly-report.pdf\",\n  \"fileKey\": \"org_xxx/uploads/550e8400-e29b-41d4-a716-446655440000/quarterly-report.pdf\",\n  \"contentKey\": \"org_xxx/contents/550e8400-e29b-41d4-a716-446655440000.md\",\n  \"contentType\": \"application/pdf\",\n  \"fileSize\": 1048576\n}"

response = http.request(request)
puts response.read_body

{
  "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 | null

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

Show child attributes

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

Associate file with knowledge base

Authorizations

Body

Response