API Quickstart

Welcome to the Incredible API Quickstart! This guide walks you through the core endpoints in the order you’ll likely adopt them. Each section includes working code examples, response formats, and links to detailed documentation. What you’ll build:

Single-turn Q&A with the Answer endpoint
Multi-turn conversations with context
Real-time streaming responses
Autonomous agents with tool calling
File-enhanced AI with document context
Advanced research capabilities

🔑

Get your Incredible API key

Generate a key to start calling the API—takes 30 seconds

→

Quick Reference

Endpoint	Use Case	Key Feature
`/v1/answer`	Single-turn Q&A, JSON extraction	Stateless, fast responses
`/v1/conversation`	Multi-turn chat, contextual dialogue	History-aware conversations
`/v1/agent`	Tool calling, complex workflows	Autonomous function execution
`/v1/web-search`	Real-time web search	Current information retrieval
`/v1/deep-research`	Multi-step research	Comprehensive reports with citations
`/v1/files/*`	Document processing	PDF, CSV, images with OCR

1) Answer - Single-turn Q&A

The Answer endpoint is perfect for stateless interactions where you need a quick, direct response. No conversation history needed—just ask and get an answer. Best for:

FAQ systems and knowledge bases
Quick facts and definitions
JSON extraction from text
Data transformation tasks

curl -X POST "https://api.incredible.one/v1/answer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Kubernetes in one sentence?"
  }'

Response format:

{
  "success": true,
  "answer": "Kubernetes is an open-source container orchestration platform that automates deploying, scaling, and managing containerized applications."
}

Structured JSON Output

The Answer endpoint can return structured data by providing a response_format schema:

from incredible_python import Incredible

client = Incredible(api_key="YOUR_API_KEY")

response = client.answer(
    query="Extract info from: John Doe, 30 years old, lives in San Francisco",
    response_format={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "age": {"type": "number"},
            "city": {"type": "string"}
        },
        "required": ["name", "age", "city"]
    }
)

print(response.data)
# {"name": "John Doe", "age": 30, "city": "San Francisco"}

Learn more: Answer API Documentation

2) Conversation - Multi-turn Dialogue

The Conversation endpoint maintains context across multiple exchanges, making it ideal for chatbots and interactive applications. You provide the full conversation history with each request. Best for:

Chatbots and virtual assistants
Customer support interfaces
Interactive tutorials and guides
Contextual dialogue systems

Key difference from Answer: Conversation understands previous messages and maintains context throughout the dialogue.

curl -X POST "https://api.incredible.one/v1/conversation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Plan a 2-day NYC trip."},
      {"role": "assistant", "content": "I'\''d be happy to help! Do you prefer cultural experiences like museums, or food and nightlife?"},
      {"role": "user", "content": "Definitely food and city views."}
    ]
  }'

Response format:

{
  "success": true,
  "response": "Perfect! Here's a food-focused 2-day itinerary:\n\nDay 1:\n- Morning: Breakfast at Russ & Daughters...\n- Afternoon: Walk the High Line for city views...\n\nDay 2:\n- Sunset: Top of the Rock for panoramic views..."
}

Adding System Instructions

Control the assistant’s behavior with a system_prompt:

response = client.conversation(
    messages=[
        {"role": "user", "content": "How do I reset my password?"}
    ],
    system_prompt="You are a helpful customer service agent for TechCorp. Be friendly, concise, and always provide step-by-step instructions."
)

Learn more: Conversation API Documentation

3) Streaming - Real-time Responses

Add stream: true to any endpoint to receive responses as they’re generated. This creates a natural, chat-like experience and reduces perceived latency. Why use streaming:

Better UX - Users see progress immediately instead of waiting
Reduced perceived latency - Engagement starts while the response generates
Cancellation support - Users can stop long responses early
Natural feel - Mimics human typing for chat interfaces

Works with: Answer, Conversation, and Agent endpoints.

curl -X POST "https://api.incredible.one/v1/answer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Explain how neural networks learn",
    "stream": true
  }'

# Outputs streaming events:
# data: {"content": "Neural", "done": false}
# data: {"content": " networks", "done": false}
# data: {"content": " learn through...", "done": false}
# data: {"done": true}

Stream event types:

content - Text chunks as generated
thinking - Internal reasoning (visible with some models)
done - Completion signal
error - Error information if something fails

Learn more: Streaming Responses Guide

4) Agent - Autonomous Tool Calling

The Agent endpoint enables your AI to autonomously decide when and how to use tools (functions). Perfect for complex workflows, external integrations, and multi-step tasks. Best for:

Database queries and API calls
Mathematical calculations
External service integrations (email, CRM, payments)
Multi-step workflows
Real-time data lookups

How it works:

Define tools the agent can use
Agent analyzes user request and decides which tools to call
Agent returns tool calls with arguments (doesn’t execute)
Your app executes tools securely
Send results back for final response

curl -X POST "https://api.incredible.one/v1/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What'\''s 157 * 23?"}
    ],
    "tools": [
      {
        "name": "calculator",
        "description": "Evaluate mathematical expressions. Use for arithmetic, algebra, and calculations.",
        "input_schema": {
          "type": "object",
          "properties": {
            "expression": {
              "type": "string",
              "description": "The math expression to evaluate (e.g., '\''157 * 23'\'')"
            }
          },
          "required": ["expression"]
        }
      }
    ]
  }'

Response with tool call:

{
  "success": true,
  "response": "I'll search for wireless headphones for you.",
  "tool_calls": [
    {
      "id": "call_abc123",
      "name": "search_database",
      "inputs": {
        "query": "wireless headphones",
        "category": "electronics"
      }
    }
  ]
}

Complete Tool Calling Pattern

Here’s the full agentic workflow:

from incredible_python import Incredible

client = Incredible(api_key="YOUR_API_KEY")

# Your actual tool implementations
def get_weather(location):
    # Call weather API
    return {"temp": 72, "condition": "sunny"}

def get_time(location):
    # Get current time
    return "3:45 PM"

tools = [
    {
        "name": "get_weather",
        "description": "Get weather for a location",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get current time for a location",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        }
    }
]

# Initial request
response = client.agent(
    messages=[{"role": "user", "content": "What's the weather and time in Tokyo?"}],
    tools=tools
)

# Execute tools if requested
if response.tool_calls:
    tool_results = []
    
    for call in response.tool_calls:
        # Execute the appropriate tool
        if call.name == "get_weather":
            result = get_weather(call.inputs["location"])
        elif call.name == "get_time":
            result = get_time(call.inputs["location"])
        
        tool_results.append({
            "tool_call_id": call.id,
            "result": result
        })
    
    # Send results back to agent for final response
    final_response = client.agent(
        messages=[
            {"role": "user", "content": "What's the weather and time in Tokyo?"},
            {"role": "assistant", "tool_calls": response.tool_calls},
            {"role": "tool", "tool_call_results": tool_results}
        ],
        tools=tools
    )
    
    print(final_response.response)
    # "In Tokyo, it's currently 72°F and sunny, and the local time is 3:45 PM."

Pro tips:

Descriptive tool names - Use clear names like search_products not search_db
Detailed descriptions - Explain what the tool does, when to use it, and what it returns
Parameter descriptions - Describe each input parameter clearly
Error handling - Always handle tool execution failures gracefully
Security - Validate tool inputs and restrict dangerous operations

Learn more: Agent API Documentation · Function Calling Guide

5) Files - Document Context

Upload files once and reuse them across unlimited API requests. The Files API supports PDFs, images, spreadsheets, and more with automatic OCR and content extraction. Best for:

Document Q&A and analysis
Resume parsing and extraction
Invoice and receipt processing
Report summarization
Image analysis with text

Supported formats:

PDFs - Automatic OCR text extraction
Images - PNG, JPEG, GIF, WebP with OCR
Spreadsheets - CSV, Excel with column analysis
Documents - TXT, Markdown, JSON

Important: Upload once, store the file_id, reuse forever. Don’t re-upload the same file repeatedly.

# Step 1: Request upload URL
curl -X POST "https://api.incredible.one/v1/files/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "quarterly_report.pdf"}'

# Response: {"file_id": "file_abc123", "upload_url": "https://..."}

# Step 2: Upload file directly to storage
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/pdf" \
  --data-binary @quarterly_report.pdf

# Step 3: Confirm upload (triggers processing)
curl -X POST "https://api.incredible.one/v1/files/confirm-upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_abc123",
    "filename": "quarterly_report.pdf",
    "file_size": 245678
  }'

# Step 4: Use file in requests (unlimited times!)
curl -X POST "https://api.incredible.one/v1/answer" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What were Q3 revenue numbers?",
    "file_ids": ["file_abc123"]
  }'

What Happens During Processing

When you confirm upload, files are automatically processed:

File Type	Processing	Extracted Data
PDF	OCR text extraction	Page count, full text, structure
Images	Vision + OCR	Text from image, visual analysis
CSV/Excel	Structure parsing	Columns, types, row count, preview
JSON	Schema analysis	Keys, structure, data types

Processing usually takes 2-10 seconds depending on file size.

Best Practices

Upload once, reuse forever:

# ✅ GOOD - Upload once, store ID
file = client.files.upload(...)
db.save(user_id, file.file_id)  # Store in database

# Use file_id many times
response1 = client.answer(query="Q1?", file_ids=[file.file_id])
response2 = client.answer(query="Q2?", file_ids=[file.file_id])

# ❌ BAD - Re-uploading same file
file1 = client.files.upload(...)  # Waste of time and resources
file2 = client.files.upload(...)  # Same file, different ID

Check file status:

# Get file metadata and processing status
metadata = client.files.metadata(file_id=file.file_id)
print(f"Status: {metadata.status}")  # "processing", "ready", "failed"
print(f"Pages: {metadata.pages}")

Learn more: Files API Documentation

6) Web Search - Real-time Information

Access current web information with the Web Search endpoint. Perfect for AI applications that need real-time data beyond the model’s training cutoff. Best for:

Current events and news
Real-time data lookups
Fact-checking with sources
Research and discovery

from incredible_python import Incredible

client = Incredible(api_key="YOUR_API_KEY")

# Semantic web search
response = client.web_search(
    query="latest developments in AI regulation 2024",
    num_results=5
)

for result in response.results:
    print(f"{result.title}")
    print(f"URL: {result.url}")
    print(f"Snippet: {result.snippet}\n")

Learn more: Web Search API

7) Deep Research - Comprehensive Reports

For complex research tasks, Deep Research conducts autonomous multi-step investigations and generates comprehensive reports with citations. Best for:

Market research
Competitive analysis
Academic literature reviews
Due diligence
Strategic planning

from incredible_python import Incredible

client = Incredible(api_key="YOUR_API_KEY")

# Autonomous research
response = client.deep_research(
    instructions="Research the current state of quantum computing and its commercial applications",
    depth="standard"  # "quick", "standard", or "thorough"
)

print(response.output)  # Comprehensive report
print(f"\nCitations: {len(response.citations)}")

Research depths:

quick - 10-15 sources, 5-10 min
standard - 20-30 sources, 10-20 min
thorough - 40+ sources, 20-40 min

Learn more: Deep Research API

Next Steps & Resources

📚 Explore the Docs

💡 Quick Tips

Authentication:

Get your API key from the platform dashboard
Include in headers: Authorization: Bearer YOUR_API_KEY
Keep keys secure, never commit to version control

Error Handling:

try:
    response = client.answer(query="...")
except Exception as e:
    print(f"Error: {e}")
    # Handle rate limits, network issues, etc.

Rate Limits:

Generous limits on all plans
429 status code if exceeded
Implement exponential backoff for retries

Best Practices:

Use Answer for single-turn, Conversation for multi-turn
Only use Agent when you need tool calling
Upload files once, store and reuse file_id
Enable streaming for better UX on long responses
Write clear, descriptive tool definitions

🔧 Common Patterns

Building a chatbot:

# Maintain conversation history in your app
history = []

while True:
    user_msg = input("You: ")
    history.append({"role": "user", "content": user_msg})
    
    response = client.conversation(messages=history)
    history.append({"role": "assistant", "content": response.response})
    
    print(f"Bot: {response.response}")

Structured data extraction:

# Extract structured data from text
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "email": {"type": "string"},
        "phone": {"type": "string"}
    }
}

result = client.answer(
    query="Extract contact info: John Doe, [email protected], 555-0100",
    response_format=schema
)
# Returns: {"name": "John Doe", "email": "[email protected]", "phone": "555-0100"}

Document Q&A system:

# Upload document library once
file_ids = []
for doc in documents:
    file = client.files.upload(file=doc)
    file_ids.append(file.file_id)
    db.save(file.file_id)  # Store in database

# Answer questions about any document
def answer_question(question, doc_id):
    return client.answer(
        query=question,
        file_ids=[doc_id]
    )

🆘 Need Help?

API Status: status.incredible.one
Discord Community: Join Discord
GitHub Examples: API Cookbook
Blog & Tutorials: web.incredible.one/blog

Getting Started

Text

Prompt Engineering

File Support

Research

Media

OCR

Quick Reference

1) Answer - Single-turn Q&A

Structured JSON Output

2) Conversation - Multi-turn Dialogue

Adding System Instructions

3) Streaming - Real-time Responses

4) Agent - Autonomous Tool Calling

Complete Tool Calling Pattern

5) Files - Document Context

What Happens During Processing

Best Practices

6) Web Search - Real-time Information

7) Deep Research - Comprehensive Reports

Next Steps & Resources

📚 Explore the Docs

💡 Quick Tips

🔧 Common Patterns

🆘 Need Help?

Getting Started

Text

Prompt Engineering

File Support

Research

Media

OCR

​Quick Reference

​1) Answer - Single-turn Q&A

​Structured JSON Output

​2) Conversation - Multi-turn Dialogue

​Adding System Instructions

​3) Streaming - Real-time Responses

​4) Agent - Autonomous Tool Calling

​Complete Tool Calling Pattern

​5) Files - Document Context

​What Happens During Processing

​Best Practices

​6) Web Search - Real-time Information

​7) Deep Research - Comprehensive Reports

​Next Steps & Resources

​📚 Explore the Docs

​💡 Quick Tips

​🔧 Common Patterns

​🆘 Need Help?

Quick Reference

1) Answer - Single-turn Q&A

Structured JSON Output

2) Conversation - Multi-turn Dialogue

Adding System Instructions

3) Streaming - Real-time Responses

4) Agent - Autonomous Tool Calling

Complete Tool Calling Pattern

5) Files - Document Context

What Happens During Processing

Best Practices

6) Web Search - Real-time Information

7) Deep Research - Comprehensive Reports

Next Steps & Resources

📚 Explore the Docs

💡 Quick Tips

🔧 Common Patterns

🆘 Need Help?