Skip to content
Dashboard
GET
/knowledge-bases/{id}/files/{fileId}
curl --request GET \
--url 'https://app.whatsetter.com/api/v1/knowledge-bases/example/files/example?offset=0&limit=100000' \
--header 'Authorization: Bearer <token>'

One file with its whole text. text_source says where the text comes from:

  • file: the text of the file, to the character (a .txt, .md or .csv file). It comes with a revision: pass it back as if_revision when you rewrite the file.
  • passages: put back together from the passages the agents hold (a PDF or Word file). The words are the file’s, its layout is not, and it is not the file to the character: a word that ends one passage and starts the next can come back twice, or once.
  • passages_unordered: the same, when the order of the passages is not known (a file read at an agent’s creation, or a very long line cut in pieces).

While a change of a text file is being saved, and after one that was cut short, the text returned is the last one that was saved. In the rare case where that cannot be told, revision is null: send the whole text then, without if_revision.

A long text comes in windows of limit characters: while next_offset is not null, call again with offset set to it. Requires scope knowledge:read.

id
required
string
fileId
required

The id of a source of kind file from GET /knowledge-bases/{id}

string
offset
integer
0

Where to start reading, in characters.

limit
integer
default: 100000 >= 1 <= 200000

How many characters to return.

The file and its text

Media typeapplication/json
object
data
object
id
string
name
string | null
status
string
Allowed values: ready reading failed empty
size_bytes
integer | null
pages

PDF files read from the dashboard; null otherwise.

integer | null
passages

How many passages the agents hold for this file: what the search picks from.

integer
editable

true for a text file (.txt, .md).

boolean
created_at
string | null format: date-time
updated_at
string | null format: date-time
characters

The length of the file’s text.

integer
text

The text, or the window of it that offset and limit ask for.

string
text_source
string
Allowed values: file passages passages_unordered
revision

The revision of the whole text (not of the window). null when the text is put back together from passages.

string | null
characters

The length of the whole text.

integer
offset
integer
next_offset

Where the next window starts; null when the text is complete.

integer | null
Example
{
"data": {
"id": "68e61c2a0019f0a4d3b1",
"name": "opening-hours.txt",
"status": "ready",
"size_bytes": 72,
"pages": null,
"passages": 1,
"editable": true,
"created_at": "2026-10-09T08:40:10.000+00:00",
"updated_at": "2026-10-09T08:40:10.000+00:00",
"text": "Monday to Friday: 7 am to 10 pm.\nSaturday: 9 am to 6 pm.\nClosed on Sunday.",
"text_source": "file",
"revision": "5f2a9c81d04be637",
"characters": 72,
"offset": 0,
"next_offset": null
}
}

Missing, unknown or revoked API key

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The key lacks the required scope (insufficient_scope), the plan does not have this part of the API (not_in_plan), or Instagram is not enabled on the workspace (instagram_not_enabled, Instagram routes)

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

Resource not found in this workspace

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

A PDF or Word file too long to be read whole through the API

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

offset or limit out of bounds

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}

The knowledge store did not answer

Media typeapplication/json
object
error
object
code
string
message
string
Examplegenerated
{
"error": {
"code": "example",
"message": "example"
}
}