Overview The Research API allows you to submit research tasks that run asynchronously in the background. You can research a topic, analyze specific sources, or both. Each task returns a task ID that you can use to track progress and retrieve results.
Submit Research Task
POST /research Submit a new research task for topic or sources analysis
Request The notebook ID to store the research results
The research topic to investigate (minimum 3 characters). Either topic or sources must be provided.
Array of sources to research. Either topic or sources must be provided. Show ResearchSource object
Type of source. One of: URL, MANUAL, UPLOAD
The URL of the source (required for URL type)
The content of the source (for MANUAL or UPLOAD types)
Response Unique identifier for the submitted task
The notebook ID where results will be stored
Current task status: IN_QUEUE
Human-readable status message
Example Request curl -X POST https://api.decipherit.com/research \ -H "Content-Type: application/json" \ -d '{ "notebook_id": "nb_123456", "topic": "quantum computing applications" }'
Example Response { "task_id" : "task_abc123" , "notebook_id" : "nb_123456" , "status" : "IN_QUEUE" , "message" : "Research task submitted and will be processed." }
Error Responses Returned when:
notebook_id is missing or emptyBoth topic and sources are missing or empty
{ "detail" : "Notebook ID is required." }
{ "detail" : "Either topic or sources must be provided." }
Get Task Status
GET /research/{task_id} Retrieve status and results of a research task
Request The unique task identifier returned when submitting the research task
Response Unique identifier for the task
The notebook ID where results are stored
The research topic (if provided)
Array of research sources (if provided)
Current task status: IN_QUEUE, IN_PROGRESS, COMPLETED, or FAILED
ISO 8601 timestamp when the task was created
Task results (available when status is COMPLETED)
Error message (available when status is FAILED)
ISO 8601 timestamp when the task completed (if applicable)
ISO 8601 timestamp when the task failed (if applicable)
Example Request curl -X GET https://api.decipherit.com/research/task_abc123
Example Response (In Progress) { "task_id" : "task_abc123" , "notebook_id" : "nb_123456" , "topic" : "quantum computing applications" , "sources" : null , "status" : "IN_PROGRESS" , "created_at" : "2026-03-03T10:30:00Z" , "result" : null , "error" : null , "completed_at" : null , "failed_at" : null }
Example Response (Completed) { "task_id" : "task_abc123" , "notebook_id" : "nb_123456" , "topic" : "quantum computing applications" , "sources" : null , "status" : "COMPLETED" , "created_at" : "2026-03-03T10:30:00Z" , "result" : { "content" : "Research findings..." , "sources" : [ ... ] }, "error" : null , "completed_at" : "2026-03-03T10:32:15Z" , "failed_at" : null }
Error Responses Returned when the task ID does not exist { "detail" : "Task not found." }
Submit Research with Sources Example: Research URLs curl -X POST https://api.decipherit.com/research \ -H "Content-Type: application/json" \ -d '{ "notebook_id": "nb_123456", "sources": [ { "source_type": "URL", "source_url": "https://example.com/article1" }, { "source_type": "URL", "source_url": "https://example.com/article2" } ] }'
Example: Research Manual Content curl -X POST https://api.decipherit.com/research \ -H "Content-Type: application/json" \ -d '{ "notebook_id": "nb_123456", "sources": [ { "source_type": "MANUAL", "source_content": "Your custom research content here..." } ] }'
Example: Combined Topic and Sources { "notebook_id" : "nb_123456" , "topic" : "renewable energy trends" , "sources" : [ { "source_type" : "URL" , "source_url" : "https://example.com/solar-power-report" } ] }