Knowledge

Knowledge bases your agents answer from.

List knowledge documents

GET /knowledge-bases

Lists your organisation’s knowledge documents with their ingestion status. The organisation always comes from the API key.

Scope: knowledge:read

Example request

curl -X GET "https://api.foan.ai/api/v1/knowledge-bases" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": [
    {
      "id": "kb_3f9a2c1e7b",
      "name": "Return policy",
      "description": "Returns and refunds FAQ",
      "status": "ready",
      "error": null,
      "source_type": "file",
      "file_count": 1,
      "chunk_count": 42,
      "created_at": "2026-09-25T09:30:00Z",
      "updated_at": "2026-09-25T09:30:00Z"
    }
  ],
  "message": "Knowledge documents retrieved"
}

Errors

Code	When
401	Missing, invalid or revoked API key
403	Key lacks knowledge:read
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Add a knowledge document

POST /knowledge-bases

Adds a knowledge document to your organisation from pasted text and/or uploaded files. It is chunked and embedded in the background: poll the document until status is ready, then attach its id to an agent. The organisation always comes from the API key.

Scope: knowledge:write

Body (multipart/form-data)

Field	Type	Required	Description
name	string	yes
description	string	no
text	string	no	Text content. Send text, files, or both.
files	file	no	Up to 5 files, 4 MB each: .pdf, .docx, .txt, .md (the CLI also sends .csv and .json).

Example request

curl -X POST "https://api.foan.ai/api/v1/knowledge-bases" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 201

{
  "success": true,
  "data": {
    "id": "kb_3f9a2c1e7b",
    "name": "Return policy",
    "description": "Returns and refunds FAQ",
    "status": "processing",
    "error": null,
    "source_type": "file",
    "file_count": 1,
    "chunk_count": null,
    "created_at": "2026-09-25T09:30:00Z",
    "updated_at": "2026-09-25T09:30:00Z"
  },
  "message": "Knowledge document created"
}

Errors

Code	When
400	Rejected by the knowledge service (for example missing name or no content); its message is passed through
401	Missing, invalid or revoked API key
403	Key lacks knowledge:write
422	Rejected by the knowledge service’s validation
429	Rate limited
500	A file over 4 MB or more than 5 files (the upload error is not translated, so it surfaces as a generic 500)
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Get a knowledge document

GET /knowledge-bases/{id}

Returns one knowledge document and its ingestion status. Only documents in the key’s organisation are found.

Scope: knowledge:read

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Knowledge document ID.

Example request

curl -X GET "https://api.foan.ai/api/v1/knowledge-bases/{id}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "id": "kb_3f9a2c1e7b",
    "name": "Return policy",
    "description": "Returns and refunds FAQ",
    "status": "ready",
    "error": null,
    "source_type": "file",
    "file_count": 1,
    "chunk_count": 42,
    "created_at": "2026-09-25T09:30:00Z",
    "updated_at": "2026-09-25T09:30:00Z"
  },
  "message": "Knowledge document retrieved"
}

Errors

Code	When
401	Missing, invalid or revoked API key
403	Key lacks knowledge:read
404	No such document in your organisation
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out

Delete a knowledge document

DELETE /knowledge-bases/{id}

Permanently deletes a knowledge document and its chunks from your organisation. Agents that reference it lose that knowledge.

Scope: knowledge:write

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Knowledge document ID.

Example request

curl -X DELETE "https://api.foan.ai/api/v1/knowledge-bases/{id}" \
  -H "Authorization: Bearer $FOAN_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "deleted": true,
    "id": "kb_3f9a2c1e7b"
  },
  "message": "Knowledge document deleted"
}

Errors

Code	When
401	Missing, invalid or revoked API key
403	Key lacks knowledge:write
404	No such document in your organisation
429	Rate limited
502	Knowledge service failed or is unreachable
503	Knowledge service is not configured on this server
504	Knowledge service timed out