Endpoints Reference

Quick Reference

Endpoint	Method	Purpose
`/session/new`	POST	Create a new conversation session
`/session/{session_id}/inquiry/agent`	POST	Submit a question to a session
`/inquiry/{inquiry_id}/status`	GET	Get current status and answer
`/inquiry/{inquiry_id}/result`	GET	Wait 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:

session_id (required): From Create Session

Request Body:

Field	Type	Required	Description
`query`	string	Yes	The natural language question
`dimensions`	object	No	Dimension 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:

inquiry_id (required): From Submit Query

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:

Value	Terminal?	Meaning
`processing`	No	Query is being processed
`done`	Yes	Completed successfully — answer and data available
`failed`	Yes	Processing failed
`timeout`	Yes	Processing timed out server-side
`stopped`	Yes	Query was stopped by the user
`out_of_domain`	Yes	Question is outside your data domain
`out_of_scope`	Yes	Question cannot be answered with available data
`no_data`	Yes	Query 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:

inquiry_id (required): From Submit Query

Query Parameters:

Parameter	Type	Default	Range	Description
`timeout`	integer	300	10–900	Max seconds to wait
`poll_interval`	integer	5	2–30	Seconds 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.

​Quick Reference

​Create Session

​Submit Query

​Get Inquiry Status

​Polling Example (Python)

​Status Values

​Wait for Result

Quick Reference

Create Session

Submit Query

Get Inquiry Status

Polling Example (Python)

Status Values

Wait for Result