Extraction
Timeline Builder
View DocsAPI Reference
Authorization
ApiKeyAuth access-key<token>
Your unique access-key generated from the platform UI
In: header
Request Body
application/json
doc_process_ids*array<string>
Array of document processing IDs to analyze
domain*string
Analysis domain: general, pharma, legal, or finance
Value in
"general" | "pharma" | "legal" | "finance"model_data*
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.k-v.ai/api/agent/timeline_builder" \ -H "Content-Type: application/json" \ -d '{ "doc_process_ids": [ "b7c90fd1892870e25530ff375c9b851f" ], "domain": "general", "model_data": { "model_name": "gpt-5.1", "api_key": "" } }'{
"value": {
"data": {
"timeline": {
"success": true,
"data": {
"timeline": {
"nodes": [
{
"id": 0,
"date": "2002-12-16",
"event": "Event description...",
"precision": "111",
"source": "document.pdf",
"page_number": "30",
"page_numbers": [
"30"
],
"sources": [
"document.pdf"
],
"domain": "general",
"topics": [
"business",
"corporate"
],
"is_cluster": false,
"cluster_size": 1,
"is_merged": false,
"merged_count": 1,
"spans_multiple_pages": false,
"precision_flags": {
"year_exact": true,
"month_exact": true,
"day_exact": true
}
}
],
"periods": [
{
"year": "2002",
"label": "2002",
"node_ids": [
0,
1
],
"event_count": 2
}
],
"connections": [
{
"id": 0,
"source_node": 0,
"target_node": 1,
"type": "same_source",
"strength": 0.96
}
]
},
"metadata": {
"total_events": 109,
"merged_events": 0,
"unique_events": 109,
"date_range": {
"start": "2002-12-16",
"end": "2016-12-29"
},
"sources": [
"document.pdf"
],
"total_sources": 1,
"domains": [
"general"
],
"topics": [
"business",
"contracts",
"corporate"
],
"total_topics": 7
},
"visualization_config": {
"layout": "horizontal",
"group_by": "year",
"show_precision": true,
"show_page_numbers": true,
"highlight_merged": true,
"cluster_threshold": 5,
"color_by_domain": true
}
},
"metadata": {
"total_events": 109,
"filtered_events": 109,
"total_tokens": {
"input": 41948,
"output": 11384,
"total": 53332
},
"model_used": "gpt-5.1",
"export_format": "default",
"filters_applied": false
},
"errors": []
},
"file_hash_mapping": {
"document.pdf": "b7c90fd1892870e25530ff375c9b851f"
},
"metadata": {
"user_name": "user@example.com",
"domain": "general",
"processed_at": "2026-01-07T10:51:22.262479",
"total_files": 1,
"total_chunks": 144
}
},
"message": "Timelines generated successfully"
}
}{
"value": {
"data": {},
"message": "Invalid docs selected"
}
}{
"value": {
"data": {},
"message": "Invalid or missing access key"
}
}{
"detail": [
{
"type": "literal_error",
"loc": [
"body",
"domain"
],
"msg": "Input should be 'general', 'pharma', 'legal' or 'finance'",
"input": "generall",
"ctx": {
"expected": "'general', 'pharma', 'legal' or 'finance'"
}
}
]
}{
"data": {},
"message": "litellm.AuthenticationError: AuthenticationError: OpenAIException - Incorrect API key provided: tyrdfuih**uhf7. You can find your API key at https://platform.openai.com/account/api-keys."
}