REST API

All endpoints are under the /api prefix. Document processing (digitization and rewriting) runs asynchronously — upload a document and poll its status.

Authentication

Supply your API key in the X-Api-Key header.

curl -X GET https://knowledge.hidoba.com/api/knowledgebases/my-partner \
  -H "X-Api-Key: YOUR_API_KEY"

Content Types

List Content Types

GET /api/content_types

Returns the available content types for document processing. No authentication required.

Response

["auto", "article", "youtube", "book"]

Knowledge Bases

List Knowledge Bases

GET /api/knowledgebases/{partner}

Returns all knowledge bases for the partner, including embedding status.

Response

[
  {
    "name": "my-kb",
    "documents": [],
    "embedding_info": {
      "last_successful_update_time": "2025-01-15T10:30:00Z",
      "last_update_status": "success",
      "embedding_stale": false
    }
  }
]

Create Knowledge Base

POST /api/knowledgebases/{partner}
Content-Type: multipart/form-data

curl -X POST https://knowledge.hidoba.com/api/knowledgebases/my-partner \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "name=my-kb"

Parameter	Type	Default	Description
name	String	—	Knowledge base name. Required.
expert_name	String	—	Default expert/author name for documents.
user_email	String	—	Default user email for documents.

Delete Knowledge Base

DELETE /api/knowledgebases/{partner}/{kb}

Folders

List Folders

GET /api/folders/{partner}/{kb}

Create Folder

POST /api/folders/{partner}/{kb}

curl -X POST https://knowledge.hidoba.com/api/folders/my-partner/my-kb \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "chapter-1"}'

Delete Folder

DELETE /api/folders/{partner}/{kb}/{folder}

Documents

List Documents

GET /api/documents/{partner}/{kb}

Returns the knowledge base with all documents and embedding info.

Get Combined Data

GET /api/kb-data/{partner}/{kb}

Returns documents, folders, and embedding info in a single call.

Get KB Statistics

GET /api/kb-stats/{partner}/{kb}

Response

{
  "document_count": 42,
  "digitized_count": 40,
  "draft_rewrite_count": 38,
  "final_rewrite_count": 35,
  "total_digitized_chars": 250000,
  "total_draft_rewrite_chars": 200000,
  "total_final_rewrite_chars": 180000,
  "error_count": 2,
  "embedded_count": 35
}

Get Single Document

GET /api/document/{partner}/{kb}/{doc_id}

Create Document (File Upload)

POST /api/documents/{partner}/{kb}
Content-Type: multipart/form-data

curl -X POST https://knowledge.hidoba.com/api/documents/my-partner/my-kb \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "type=file" \
  -F "folder=chapter-1" \
  -F "file=@document.pdf" \
  -F "auto_rewrite=true" \
  -F "model_tier=standard"

Form Parameters

Parameter	Type	Default	Description
type	String	—	file or url. Required.
folder	String	—	Target folder name. Required.
file	File	—	File to upload. Required when type=file.
url	String	—	URL to fetch. Required when type=url.
name	String	—	Document name. Auto-detected from file/URL if omitted.
expert_name	String	—	Content author or speaker name.
user_email	String	—	Email of the uploading user.
auto_rewrite	String	false	Automatically queue for rewriting after digitization. Pass "true" to enable.
model_tier	String	standard	LLM model tier: standard or economy.
use_original_as_rewritten	String	false	Skip rewriting and use original content as-is. Pass "true" to enable.

Create Document (URL)

curl -X POST https://knowledge.hidoba.com/api/documents/my-partner/my-kb \
  -H "X-Api-Key: YOUR_API_KEY" \
  -F "type=url" \
  -F "folder=articles" \
  -F "url=https://example.com/article"

Batch URL Import

POST /api/documents/{partner}/{kb}/batch
Content-Type: application/json

curl -X POST https://knowledge.hidoba.com/api/documents/my-partner/my-kb/batch \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folder": "articles",
    "urls": [
      "https://example.com/article-1",
      "https://example.com/article-2"
    ],
    "use_original_as_rewritten": false
  }'

note

Maximum 1,000 URLs per batch request.

Response

{
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  },
  "results": [
    {
      "url": "https://example.com/article-1",
      "status": "success",
      "document_id": "a1b2c3d4-e5f6-..."
    },
    {
      "url": "https://example.com/article-2",
      "status": "success",
      "document_id": "f7g8h9i0-j1k2-..."
    }
  ]
}

Create Empty Document

POST /api/documents/{partner}/{kb}/empty

Creates a document with no content, for manual content editing.

Parameter	Type	Default	Description
name	String	—	Document name. Required.
folder	String	—	Target folder name. Required.
type	String	—	file or url. Required.
url	String	—	URL (if type is url).

Rename Document

PUT /api/documents/{partner}/{kb}/{doc_id}/name

Update Document Type

PUT /api/documents/{partner}/{kb}/{doc_id}/type

Update Document URL

PUT /api/documents/{partner}/{kb}/{doc_id}/url

Delete Document

DELETE /api/documents/{partner}/{kb}/{doc_id}

Pass force=true as a query parameter to force-delete a document that is currently being processed. Defaults to true.

curl -X DELETE "https://knowledge.hidoba.com/api/documents/my-partner/my-kb/DOC_ID?force=false" \
  -H "X-Api-Key: YOUR_API_KEY"

Document Content

Get Content

GET /api/documents/{partner}/{kb}/{doc_id}/content/{type}

Where {type} is one of: original, digitized, rewritten, draft.

Response

{
  "content": "# Document Title\n\nProcessed document content..."
}

Update Content

PUT /api/documents/{partner}/{kb}/{doc_id}/content/{type}

Send content as a form parameter.

Upload Content as File

POST /api/documents/{partner}/{kb}/{doc_id}/content/{type}
Content-Type: multipart/form-data

Download Rewritten Bundle

GET /api/documents/{partner}/{kb}/rewritten-bundle

Returns a ZIP archive of all rewritten documents in the knowledge base.

Processing

Queue Document for Processing

POST /api/queue/process

Parameter	Type	Default	Description
document	Object	—	Document object (JSON body).
action	String	process	Processing action: digitize, rewrite, or process.
partner	String	—	Partner name.
kb	String	—	Knowledge base name.
content_type	String	auto	auto, article, youtube, or book.
person_name	String	—	Author/speaker name for the rewrite prompt.

Content Type Auto-Detection

When content_type is set to auto:

• YouTube URLs and audio files → youtube template
• PDF files → book template
• Everything else → article template

Bulk Rewrite (Folder)

POST /api/bulk/rewrite/folder/{partner}/{kb}/{folder}

Parameter	Type	Default	Description
skip_rewritten	Boolean	true	Skip documents that already have rewritten content.
content_type	String	auto	Content type template to use.
person_name	String	—	Author/speaker name.

Bulk Rewrite (Knowledge Base)

POST /api/bulk/rewrite/kb/{partner}/{kb}

Parameter	Type	Default	Description
skip_rewritten	Boolean	true	Skip documents that already have rewritten content.
content_type	String	auto	Content type template to use.
person_name	String	—	Author/speaker name.

Embedding

Get Embedding Status

GET /api/embedding/{partner}/{kb}

Response

{
  "last_successful_update_time": "2025-01-15T10:30:00Z",
  "last_update_time": "2025-01-15T10:30:00Z",
  "last_update_status": "success",
  "last_update_details": {},
  "last_successful_details": {},
  "runpod_job_id": "abc123",
  "embedding_stale": false
}

Start Embedding

POST /api/embedding/{partner}/{kb}
Content-Type: multipart/form-data

Parameter	Type	Default	Description
split_level	Integer	0	Heading split level (0–6).
language	String	english	Content language.

Document Model

A document returned from the API includes the following fields:

Field	Type	Description
id	String	UUID identifier.
name	String	Document name.
folder	String	Folder name.
type	String	file or url.
url	String	Source URL (if type is url).
file_original	String	Original uploaded filename.
file_digitized	String	Digitized content filename.
file_rewritten_draft	String	Draft rewrite filename.
file_rewritten	String	Final rewrite filename.
user_email	String	Email of the uploading user.
in_queues	Array	Active processing queues (e.g., ["digitize"], ["rewrite"]).
expert_name	String	Content author/speaker.
auto_rewrite	Boolean	Whether auto-rewrite is enabled.
model_tier	String	standard or economy.
rewrite_model	String	LLM model used for rewriting.
rewrite_input_tokens	Integer	Input tokens consumed.
rewrite_output_tokens	Integer	Output tokens generated.
rewrite_completed_at	String	ISO timestamp of rewrite completion.
processing_error	String	Error message if processing failed.
is_embedded	Boolean	Whether the document has been embedded.
digitized_char_count	Integer	Character count of digitized content.
draft_rewrite_char_count	Integer	Character count of draft rewrite.
final_rewrite_char_count	Integer	Character count of final rewrite.

Error Responses

Unauthorized (401)

{
  "detail": "Invalid API key"
}

Forbidden (403)

{
  "detail": "Access denied"
}

Not Found (404)

{
  "detail": "Document not found"
}

Rate Limited (429)

{
  "detail": "Rate limit exceeded"
}