Deep Research API Documentation

Built with Altera Corporation Deep Research technology
This documentation explains how to use the Deep Research API for structured, analytical research tasks.

Parameters

All input parameters are passed via query string for GET requests or body JSON for POST requests.

Parameter	Type	Description	Default
prompt	string	The main research query or text input for the deep research model	required
key	string	Your access key for authentication	required
openai_api_key	string	Your OpenAI API key (optional). If provided, this key will be used instead of the server's default key	null
model	string	Which deep research model to use	o4-mini-deep-research
background	boolean	If true, the research will run in background mode	false
autopoll	boolean	If true and background=true, the server will poll until job complete	false
pollintervalms	number	Milliseconds between polling attempts in background mode	3000
enable_code_interpreter	boolean	Enable the code interpreter tool for analytical tasks	false
max_tool_calls	number	Maximum number of tool calls allowed	unlimited
vector_store_ids	array	Array of vector store ids for private data searches	null
extratools	array	Array of extra tool configurations	[]
instructions	string	Optional instructions for the model	default research instructions

---

Default Instructions

If no instructions are provided, the following structured prompt is used:

Use the deep research model to produce a structured, auditable research report.

Output structure:
1) Executive summary (≤ 250 words)
2) Brief methodology (tools used: web_search/file_search/code_interpreter)
3) Key findings — include figures, trends, and measurable metrics
4) Analysis and interpretation (data-backed reasoning)
5) Practical implications and recommendations
6) Sources with full metadata (title, url, publish date, source type)

Requirements:
- Prioritize high-quality sources (peer-reviewed journals, reputable agencies)
- Include inline citations for non-opinion claims and return source metadata
- Avoid exposing or transmitting personal/sensitive data
- If using private data, only query trusted stores/servers
- If assumptions are made, list them and note limitations
- Be analytical and avoid unsupported generalities

---

Example Usage (Node.js)

const axios = require('axios');

async function runResearch() {
  const response = await axios.post('https://altera-api.vercel.app/api/deep-research', {
    prompt: 'Research the economic impact of semaglutide on global healthcare systems.',
    key: 'A-CORE',
    openai_api_key: 'sk-your-openai-key-here',
    background: true,
    autopoll: true,
    enable_code_interpreter: true,
    max_tool_calls: 50,
    vector_store_ids: ['vs_68870b8868b88191894165101435eef6']
  });

  console.log(response.data);
}

runResearch();

Or using GET request:

https://altera-api.vercel.app/api/deep-research?prompt=research+semaglutide&key=A-CORE&openai_api_key=sk-your-key

---

Models Available

• o4-mini-deep-research — High-level research model, faster, optimized for multi-step analysis
• o3-deep-research — Classic deep research model, thorough and analytical

Tools

• web_search_preview — Search public web for information
• file_search — Query private vector stores
• code_interpreter — Perform computations, analysis, or data manipulation
• mcp servers — Optional remote servers for private internal data search

Best Practices

• Always use background mode for long-running research tasks
• Include vector_store_ids only for trusted data
• Use instructions to guide research style or report structure
• Use openai_api_key to use your own OpenAI credits
• Monitor tool calls for security when using MCP or web search
• Prefer high-quality sources for research tasks

Error Handling

The API returns a JSON object with success: false and an error message in case of issues:

{
  "success": false,
  "error": "Polling timeout — job not completed in time."
}

---

Security Notes

• Only allow trusted API keys from allowedApiKeys
• OpenAI API keys are optional - server will use its own key if not provided
• Do not expose sensitive internal data in web search or MCP calls
• Log all requests and tool calls for audit and monitoring