Your interface.
TableArth’s analysis.

1. Configure authentication

Ask your tenant administrator for an API key assigned to an active TableArth agent. Send the apiKey header on each request and configure the allowed origin or server IP for your integration. Keep service credentials on your server.

apiKey: <YOUR_API_KEY>
Origin: https://your-app.example.com

The base URL is your configured tenant deployment. It is not a universal api.tablearth.ai/v1 endpoint. Requests and quotas depend on your plan.

2. Initialize a session

Choose a stable remoteSessionId for a dataset and account. Reuse it to resume the same analysis; change it when the dataset or relevant filters change.

curl "$TABLEARTH_BASE_URL/emp/1/api/tableai/init" \
  -H "apiKey: $TABLEARTH_API_KEY" \
  -H "Origin: https://your-app.example.com" \
  -H "remoteSessionId: report:sales:account-123:2026-09" \
  -H "pt: 50" -H "pn: 0"

Read sessionData.sessionId and sessionData.fileAvailable from the response. Check both the HTTP status and application error fields before continuing.

3. Provide the data

If the session has no available data, upload the file using multipart form data. Use the session ID returned by initialization.

curl -X POST "$TABLEARTH_BASE_URL/emp/1/api/tableai/upload" \
  -H "apiKey: $TABLEARTH_API_KEY" \
  -H "Origin: https://your-app.example.com" \
  -H "sessionId: $TABLEARTH_SESSION_ID" \
  -F "file=@sales.csv"

Do not manually set a multipart boundary. Data ingestion and dashboard generation may finish asynchronously; honor the status returned by your deployment before querying or showing a dashboard.

4. Ask a question

The API-key chat body is flat: sessionId , query , and stream . The widget uses a different authenticated surface and wraps its payload.

curl -N -X POST "$TABLEARTH_BASE_URL/emp/1/api/tableai/chat" \
  -H "apiKey: $TABLEARTH_API_KEY" \
  -H "Origin: https://your-app.example.com" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream, application/json" \
  --data '{"sessionId":"YOUR_SESSION_ID","query":"Which region has the highest revenue?","stream":true}'

Replace YOUR_SESSION_ID with the initialization response. For a JSON response instead of a stream, set stream to false .

5. Handle streaming events

Each SSE event contains a JSON payload in a data: line. Buffer until a complete event is received; transport chunks are not event boundaries.

data: {"contentType":"STATUS","content":"Analyzing your data…"}

data: {"contentType":"TEXT","content":"The leading region is…"}

data: {"contentType":"CHART","data":{"chartConfig":"{…}","chartData":"{…}"}}

data: {"contentType":"DONE"}

STATUS is transient, TEXT appends answer text, and CHART carries chart configuration and data as JSON strings. Stop on DONE or ERROR . Ignore unrecognized event types so your client can handle protocol additions.

6. Retrieve a dashboard

Request the dashboard specification after it becomes ready. Fetch widget data separately when the specification requires it.

POST /emp/1/api/dashboard/spec
{ "sessionId": "YOUR_SESSION_ID" }

POST /emp/1/api/dashboard/widget/data
{ "sessionId": "YOUR_SESSION_ID", "widgetId": "WIDGET_ID", "offset": 0, "limit": 50 }

Identity and error handling

The init/v2 , upload/v2 , and chat/v2 routes additionally support the documented ssoToken header for per-user attribution. Confirm the JWT contract with your administrator; a service-wide key alone does not establish a user identity.

• Handle 401/403 for credentials, origins, agent status, and plan access.
• Handle 429 with bounded retry and backoff.
• Check application error fields such as s, ed, and msg even for a JSON response.
• Show ingestion, query, and stream failures explicitly; do not treat an interrupted response as a complete answer.