Skip to main content

​
API Introduction

The DecipherIt API is a FastAPI-based REST API that powers intelligent research agents. It enables you to submit research tasks, track their progress, generate audio overviews, create mindmaps, and interact with research content through chat.

​
Base URL

The API is served at: Development (self-hosted): 
http://localhost:8001/api
Production: 
https://api.decipherit.com
All endpoints are prefixed with /api. For example, the health check endpoint is available at /api/health. Code examples in this documentation use the production URL format.

​
API Architecture

DecipherIt uses an asynchronous, background task processing model:
  1. Submit Tasks - Research, audio overview, and mindmap generation tasks are submitted and return immediately with a task ID
  2. Background Processing - Tasks are processed asynchronously by AI agents
  3. Poll for Status - Check task status and retrieve results using the task ID
  4. Real-time Chat - Interact with research content through synchronous chat endpoints

​
Core Concepts

​
Notebooks

A notebook is the primary organizational unit in DecipherIt. Each research task is associated with a notebook ID, which groups related research, summaries, audio overviews, and mindmaps together.

​
Background Tasks

Most operations return a task_id immediately and process in the background. Task statuses include:
  • IN_QUEUE - Task is waiting to be processed
  • IN_PROGRESS - Task is currently being processed
  • COMPLETED - Task finished successfully
  • FAILED - Task encountered an error

​
Research Sources

Research can be initiated from multiple source types:
  • URL - Web-based sources
  • MANUAL - Manually provided content
  • UPLOAD - Uploaded documents

​
Available Endpoints

​
Health Check

GET /api/health
Returns the API health status and current timestamp. Response: 
{
  "status": "healthy",
  "timestamp": "2026-03-03T10:30:00.000Z"
}

​
Research Endpoints

  • POST /api/research - Submit a new research task
  • GET /api/research/{task_id} - Get research task status
  • POST /api/research/audio-overview/{notebook_id} - Generate audio overview
  • POST /api/research/mindmap/{notebook_id} - Generate mindmap

​
Chat Endpoints

  • POST /api/chat/message - Send a chat message and receive AI response

​
Request/Response Format

All requests and responses use JSON format. The API follows RESTful conventions:
  • 200 OK - Successful GET request
  • 201 Created - Successful POST request (synchronous)
  • 202 Accepted - Successful POST request (asynchronous task submitted)
  • 400 Bad Request - Invalid request data
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

​
CORS Configuration

The API currently allows requests from all origins (*). In production, configure allow_origins in the CORS middleware to restrict access to trusted domains.
The API includes CORS middleware that allows:
  • All origins (configure for production)
  • Credentials
  • All HTTP methods
  • All headers

​
Error Handling

Errors return a JSON response with an HTTP status code and detail message: 
{
  "detail": "Task not found."
}
Common error scenarios:
  • Missing required fields (notebook_id, topic/sources)
  • Task or notebook not found
  • Processing failures

​
Next Steps

Authentication

Learn about API authentication

Research API

Submit and track research tasks

Chat API

Interact with research content

Audio & Mindmap APIs

Generate audio overviews and mindmaps

Build docs developers (and LLMs) love

Get started for freeTalk to us