Graine AI
API referenceKnowledge bases

List a knowledge base's documents

List what has been uploaded to a knowledge base, newest first.

List what has been uploaded to a knowledge base, newest first.

One entry is one upload, not one file. A request that uploaded three files is a single entry whose files array has three names.

total is a lower bound. The knowledge service exposes no exact count, so this endpoint probes one item past the page: page until has_more is false rather than dividing total yourself.

An upload whose metadata record failed to write is invisible here even though its text is retrievable — that is what metadata_recorded: false on the upload response was warning about.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/knowledge-bases/{collection}/documents
/v2/knowledge-bases/product-handbook/documents?page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Path Parameters

collection
Required
Collection

The knowledge base name.

Query Parameters

organization_idOrganization Id

Must match the organisation the API key belongs to.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of uploads, newest first.

data
Required
Data

This page of uploads, newest first.

pagination
Required
Pagination

Where this page sits; 'total' is a lower bound.

400

1000 — malformed input (bad knowledge base name, unreadable or empty file).

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

404

1200 — no such knowledge base in this organisation. Cross-tenant reads answer 404, never 403.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — the knowledge service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

504

1502 — the knowledge service did not respond in time. A slow ingest may still complete.

error
Required
Error

Stable integer code from the /v2 error table. Branch on this.

message
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X GET "https://api.graine.ai/v2/knowledge-bases/product-handbook/documents?organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of uploads, newest first.

{
  "data": [
    {
      "document_id": "3f9a7c21-58d4-4e6b-b7f0-2a1c9d8e4b60",
      "collection": "product-handbook",
      "files": [
        "pricing-2026.pdf"
      ],
      "chunks_indexed": 84,
      "status": "active",
      "created_at": "2026-08-26T10:48:18.239Z",
      "updated_at": "2026-08-26T10:48:18.239Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

Call progress

Next

Fetch one knowledge base GET