Skip to main content

​
Quick Reference

EndpointMethodPurpose
/session/newPOSTCreate a new conversation session
/session/{session_id}/inquiry/agentPOSTSubmit a question to a session
/inquiry/{inquiry_id}/statusGETGet current status and answer
/inquiry/{inquiry_id}/resultGETWait for completion (long-poll)
All endpoints are prefixed with /api (full URL: https://be.jedify.com/api/session/new). All endpoints require the X-API-Key header. See Authentication.

​
Create Session

Create a new conversation session. Sessions group related questions together, enabling follow-up queries with shared context. 
POST /api/session/new
Request Body: None required Example: 
curl -X POST https://be.jedify.com/api/session/new \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY"
Response (200): 
{
  "session_id": "session_abc123"
}

​
Submit Query

Submit a natural language question to a session. Returns immediately with an inquiry_id — the query processes asynchronously in the background. 
POST /api/session/{session_id}/inquiry/agent
Path Parameters: Request Body:
FieldTypeRequiredDescription
querystringYesThe natural language question
dimensionsobjectNoDimension filters to scope the query
Example: 
curl -X POST https://be.jedify.com/api/session/session_abc123/inquiry/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"query": "What were total sales last month?"}'
Response (200): 
{
  "inquiry_id": "inquiry_xyz789"
}

​
Get Inquiry Status

Get the current status and answer for an inquiry. Use this for manual polling, or use Wait for Result instead. 
GET /api/inquiry/{inquiry_id}/status
Path Parameters: Example: 
curl https://be.jedify.com/api/inquiry/inquiry_xyz789/status \
  -H "X-API-Key: YOUR_API_KEY"
Response (200): The response is the full QueryStatusResponse. Key fields: 
{
  "status": {
    "general": "done",
    "answer": "ready",
    "chart": "ready"
  },
  "inquiry_type": "agent",
  "user_input": "What were total sales last month?",
  "answer": "Total sales last month were $1,234,567.",
  "sql_query": "SELECT SUM(amount) AS total_sales FROM sales WHERE ...",
  "data": {
    "title": "Total Sales",
    "data": [{"TOTAL_SALES": 1234567}],
    "symbols": {"TOTAL_SALES": "$"},
    "semantic_types": {}
  },
  "chart": {
    "chart_type": "bar",
    "chart_metadata": { ... },
    "chart_data": [ ... ]
  },
  "explanation": "...",
  "time_frame": "last_month",
  "answer_explanation": { ... },
  "thinking": { "title": "...", "messages": [ ... ] }
}
The response includes additional fields (follow_up_type, pin_data, chart_view_items, selected_view, etc.) used by the Jedify UI. You can safely ignore fields you don’t need. While processing, status.general is "processing" and answer, sql_query, and data.data will be empty.

​
Polling Example (Python)

import time, requests

def poll_until_done(inquiry_id, api_key, interval=5, max_wait=300):
    headers = {"X-API-Key": api_key}
    elapsed = 0
    while elapsed < max_wait:
        resp = requests.get(
            f"https://be.jedify.com/api/inquiry/{inquiry_id}/status",
            headers=headers,
        )
        data = resp.json()
        status = data["status"]["general"]
        if status != "processing":
            return data  # Terminal — done, failed, no_data, etc.
        time.sleep(interval)
        elapsed += interval
    raise TimeoutError(f"Inquiry did not complete within {max_wait}s")

​
Status Values

Check status.general to determine inquiry state:
ValueTerminal?Meaning
processingNoQuery is being processed
doneYesCompleted successfully — answer and data available
failedYesProcessing failed
timeoutYesProcessing timed out server-side
stoppedYesQuery was stopped by the user
out_of_domainYesQuestion is outside your data domain
out_of_scopeYesQuestion cannot be answered with available data
no_dataYesQuery executed but returned no results

​
Wait for Result

Long-polling endpoint that waits for an inquiry to complete before returning. The server holds the HTTP connection open, polling internally until the inquiry reaches a terminal status or the timeout is reached. This is the recommended way to get results — simpler than polling /status yourself. 
GET /api/inquiry/{inquiry_id}/result
Path Parameters: Query Parameters:
ParameterTypeDefaultRangeDescription
timeoutinteger30010–900Max seconds to wait
poll_intervalinteger52–30Seconds between internal status checks
Example: 
curl "https://be.jedify.com/api/inquiry/inquiry_xyz789/result?timeout=120" \
  -H "X-API-Key: YOUR_API_KEY"
Response (200): Same shape as Get Inquiry Status. Only returned once the inquiry reaches a terminal status. Timeout Response (408): 
{
  "detail": "Inquiry inquiry_xyz789 did not complete within 120 seconds"
}
Handling 408: The inquiry is still processing — it wasn’t cancelled. Call /result again to keep waiting, or switch to polling /status for more control. Important: Set your HTTP client timeout to exceed the timeout parameter. If you request timeout=120, your client should wait at least 130 seconds.