Oshara Docs

List documents


GET /api/knowledge-base/{slug}/documents/

Returns all documents attached to the character.


curl https://api.oshara.ai/api/knowledge-base/support-bot/documents/ \
  -H "Authorization: Bearer <token>"

Response:


[
  {
    "id": 1,
    "file": "https://storage.oshara.ai/documents/refund-policy.pdf",
    "file_type": "pdf",
    "status": "PROCESSED",
    "chunk_count": 23,
    "created_at": "2025-06-01T10:00:00Z"
  },
  {
    "id": 2,
    "file": "https://storage.oshara.ai/documents/shipping-faq.docx",
    "file_type": "docx",
    "status": "PENDING",
    "chunk_count": 0,
    "created_at": "2025-06-10T14:30:00Z"
  }
]

Document fields

Field	Description
`id`	Document ID.
`file`	Storage URL of the uploaded file.
`file_type`	`"pdf"`, `"docx"`, or `"txt"`.
`status`	`"PENDING"`, `"PROCESSED"`, or `"FAILED"`.
`chunk_count`	Number of text chunks generated (0 while `PENDING`).
`created_at`	ISO 8601 upload timestamp.

Upload a document


POST /api/knowledge-base/{slug}/documents/

Upload a file as multipart/form-data. Processing is asynchronous — poll the document’s status until it reaches PROCESSED.


curl -X POST https://api.oshara.ai/api/knowledge-base/support-bot/documents/ \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/refund-policy.pdf"

Response: 201 Created


{
  "id": 3,
  "file": "https://storage.oshara.ai/documents/refund-policy.pdf",
  "file_type": "pdf",
  "status": "PENDING",
  "chunk_count": 0,
  "created_at": "2025-06-10T15:00:00Z"
}

Supported formats

Format	Extension
PDF	`.pdf`
Word Document	`.docx`
Plain text	`.txt`

Polling for processing completion


# Check status every few seconds
curl https://api.oshara.ai/api/knowledge-base/support-bot/documents/ \
  -H "Authorization: Bearer <token>" \
  | jq '.[] | select(.id == 3) | .status'

A newly uploaded PDF typically takes 5–30 seconds to reach PROCESSED depending on file size.

Delete a document

Documents cannot be deleted via the API directly — manage them through the dashboard. If you need programmatic deletion, contact support.

Path parameter

Parameter	Description
`slug`	The character’s slug (e.g. `support-bot`). Documents are scoped per character.