Files API

Files are text records submitted directly to a project for indexing. They do not have a source URL. The API accepts JSON text only; binary and multipart uploads are not exposed.

File object

{
  "id": "pg_file1",
  "name": "Refund policy",
  "content": "Customers can request a refund within 14 days.",
  "status": "parsing",
  "status_error": null,
  "size_bytes": 49,
  "updated_at": "2026-09-11T09:20:00+00:00"
}

Field	Description
id	File ID for read, update and deletion methods.
content	Full text currently stored for indexing.
status	Current indexing state.
status_error	Processing error, or null.
size_bytes	UTF-8 byte length of the stored text.

List files

GET /api/files
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

200 OK returns:

{
  "items": [
    {
      "id": "pg_file1",
      "name": "Refund policy",
      "content": "Customers can request a refund within 14 days.",
      "status": "ready",
      "status_error": null,
      "size_bytes": 49,
      "updated_at": "2026-09-11T09:20:00+00:00"
    }
  ]
}

Create a file

POST /api/files
Authorization: Bearer CLIENT_ID.CLIENT_SECRET
Content-Type: application/json

{
  "name": "Refund policy",
  "content": "Customers can request a refund within 14 days."
}

JSON field	Required	Rules
name	Yes	Non-empty string, maximum 255 characters.
content	Yes	Text to index.

201 Created returns the file object. The response may show parsing while the normal indexing pipeline runs. Text exceeding the configured indexing limit is returned with a processing error and is not queued.

Read one file

GET /api/files/{file_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Path parameter	Description
file_id	The id returned by the list or create method.

200 OK returns one file object. A non-file page, an unknown ID, or a file in another project returns 404.

Update a file

PATCH /api/files/{file_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET
Content-Type: application/json

{
  "name": "Refund policy — updated",
  "content": "Updated policy text."
}

JSON field	Required	Effect
name	No	Replaces the file name.
content	No	Replaces the text, removes prior indexed chunks, and queues indexing again.

200 OK returns the complete updated file object. Supplying only name does not reindex the content.

Delete a file

DELETE /api/files/{file_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

204 No Content confirms deletion. The method returns 404 for an unknown, non-file, or out-of-project ID.