Docent · Developer API

Ask your own documents from your own software.

Your intranet, your help desk or your app asks in plain words and gets an answer from your organisation's own documents and data — with the sources it came from, and only from the collections the key may read.

Create an account → make a key Keys are made on your organisation's API keys screen; the API comes with a plan.

Use an AI app such as Claude or ChatGPT? Connect an AI agent — it asks your organisation's documents for you, with the same permissions and the same charges.

Authentication and conventions

Make a key on your organisation's API keys screen (it is shown once) and send it on every request:

Authorization: Bearer docent_your_key
Accept: application/json

• Base URL https://www.drivebird.com/api/docent/v1. JSON in, JSON out.
• Success: {"data": …}, with meta on lists. Failure: {"data": null, "errors": ["…"], "code": "MACHINE-CODE"} — branch on code, show errors to a person.
• A key reads only the collections chosen when it was made. A document, source or conversation outside them answers 410 Gone, exactly like one that does not exist — DriveBird never answers 404.
• Times are YYYY-MM-DD HH:MM in UTC; day on /usage is the India day the free answers count in.

Key permissions and expiry

A key carries only the permissions ticked when it was made, so a key you paste into a chat widget need not be able to delete your documents. Each endpoint below shows the permission it needs.

Permission	What it allows
`ASK`	Ask questions
`READ`	Read collections, sources, documents and usage
`WRITE`	Add and delete documents, start a sync

• A call the key may not make answers 403 SCOPE-MISSING: the key works — make one with the permission you need.
• A key may carry an expiry day; from that day it answers 401 KEY-EXPIRED. A revoked key answers 401 KEY-REVOKED at once.
• Keys work while the organisation has a plan with the API; without one they answer 403 PLAN-REQUIRED.

Limits and charging

• 60 requests a minute with one key, and at most 120 a minute from one address — exceed either and the call answers 429 RATE-LIMITED.
• An answer is charged exactly like one in the chat: the organisation's 3 free answers of the day first, then its plan's answers, then ₹1 an answer from its owner's wallet. "I don't know" is never charged. When none is left the call answers 429 LIMIT-REACHED with the reason.
• A question is at most 1,000 characters.

Endpoints

POST /api/docent/v1/ask Needs ASK — Ask a question — the answer comes only from the collections the key may read

Fields: question (1 to 1000 characters), conversation_id (optional — one of this key's conversations, to ask a follow-up). mode is DOCUMENTS, DATABASE, BOTH or NO-ANSWER; an answer the documents cannot give says "I don't know" and is never charged.

curl

curl https://www.drivebird.com/api/docent/v1/ask -H "Authorization: Bearer docent_your_key" -H "Accept: application/json" \
  -H "Content-Type: application/json" -d '{"question": "How many casual leave days do we get?"}'

Response

{"data": {"answer": "Every employee gets twelve casual leave days a year [1].", "citations": [{"n": 1, "piece_id": 812, "document_id": 64, "title": "Leave policy.pdf", "where": "page 3 · Leave"}], "mode": "DOCUMENTS", "conversation_id": 31, "message_id": 207, "billed_by": "FREE", "note": null}}

GET /api/docent/v1/collections Needs READ — The collections the key may read

curl

curl https://www.drivebird.com/api/docent/v1/collections -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": [{"id": 3, "name": "HR", "description": "Leave, pay and travel", "documents": 18}]}

GET /api/docent/v1/sources Needs READ — The sources of those collections

curl

curl https://www.drivebird.com/api/docent/v1/sources -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": [{"id": 12, "name": "Handbook", "type": "UPLOAD", "status": "ACTIVE", "collection_id": 3, "last_synced_at": null, "next_sync_at": null, "last_error": null}]}

POST /api/docent/v1/sources/{source}/sync Needs WRITE — Sync a website, S3 bucket or database now

Answers 202. The same rules as "Sync now" on the source's page: an upload source has nothing to sync, and on a plan a sync waits an hour after the last one.

curl

curl -X POST https://www.drivebird.com/api/docent/v1/sources/14/sync -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": {"id": 14, "name": "Our website", "type": "WEB", "status": "SYNCING", "collection_id": 3, "last_synced_at": "2026-11-01 02:00", "next_sync_at": null, "last_error": null}}

GET /api/docent/v1/documents?source_id=&status=&page=&per_page= Needs READ — The documents, newest first

per_page is 1 to 100 (default 25); status is QUEUED, READING, EMBEDDING, READY, FAILED or WAITING-SPACE.

curl

curl "https://www.drivebird.com/api/docent/v1/documents?status=READY&per_page=50" -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": [ …document… ], "meta": {"page": 1, "per_page": 50, "total": 18, "last_page": 1}}

POST /api/docent/v1/documents Needs WRITE — Add a file to an upload source (multipart)

Answers 201; the file is read in the background — poll GET /documents/{document} until it is READY. The kinds, sizes and counts the upload screen allows apply here too.

curl

curl https://www.drivebird.com/api/docent/v1/documents -H "Authorization: Bearer docent_your_key" -H "Accept: application/json" \
  -F "source_id=12" -F "file=@Leave policy.pdf"

Response

{"data": {"id": 64, "title": "Leave policy.pdf", "status": "QUEUED", "origin": "FILE", "mime": "application/pdf", "pages": 0, "pieces": 0, "source_id": 12, "collection_id": 3, "failure": null, "created_at": "2026-11-02 09:15", "read_at": null}}

GET /api/docent/v1/documents/{document} Needs READ — One document

curl

curl https://www.drivebird.com/api/docent/v1/documents/64 -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": {"id": 64, "title": "Leave policy.pdf", "status": "READY", "origin": "FILE", "mime": "application/pdf", "pages": 4, "pieces": 9, "source_id": 12, "collection_id": 3, "failure": null, "created_at": "2026-11-02 09:15", "read_at": "2026-11-02 09:16"}}

DELETE /api/docent/v1/documents/{document} Needs WRITE — Delete a document — its passages and its file go with it

curl

curl -X DELETE https://www.drivebird.com/api/docent/v1/documents/64 -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": {"id": 64, "deleted": true}}

GET /api/docent/v1/usage Needs READ — Today's answers, and the documents against the plan

curl

curl https://www.drivebird.com/api/docent/v1/usage -H "Authorization: Bearer docent_your_key" -H "Accept: application/json"

Response

{"data": {"day": "2026-11-02", "answers": {"free_used": 3, "free_per_day": 3, "plan_used": 41, "plan_left": 259, "wallet": 0, "unanswered": 2, "unanswered_cap": 50}, "documents": {"used": 18, "limit": 500}, "pages": {"used": 240, "limit": 1000}, "file_mb": 25, "plan": true}}

Error codes

Status	code	When
401	UNAUTHENTICATED	No key was sent, or it is not a Docent key.
401	KEY-REVOKED	The key was revoked on the organisation's API keys screen.
401	KEY-EXPIRED	The key has passed the expiry date it was made with.
403	SCOPE-MISSING	The key may not do this — make a key with the permission the endpoint names.
403	PLAN-REQUIRED	The organisation has no plan with API access; its keys work again once its owner adds one.
422	VALIDATION	A field is missing or wrong — `errors` says which.
410	GONE	The conversation, source or document does not exist, or this key may not see it.
429	LIMIT-REACHED	The organisation may not ask now: today's answers are used up, or too many questions today found nothing.
503	ANSWER-FAILED	The answer could not be written just now; nothing was charged — ask again.
422	SYNC-REFUSED	The source does not sync, is syncing already, or synced too recently for its plan.
422	UPLOAD-REFUSED	The file was not accepted: its kind, its size or the plan's limits.
429	RATE-LIMITED	More than 60 requests a minute with one key, or 120 from one address.