Skip to main content

​
What can you do with the API?

The Interact REST API lets you integrate Interact into your own systems and workflows. Common use cases:
  • Trigger an agent job after a data pipeline finishes loading new data
  • Fetch job results to display them in an internal dashboard
  • List chat sessions for a specific agent or job for audit purposes

​
Authentication

Every API request requires two headers:
HeaderValue
X-API-KeyYour API key, created in Settings → API
X-Organization-IdYour organisation ID, visible in Settings → Organisation
Keep your API key secret. Anyone with your key and organisation ID can trigger agent jobs on your behalf. If a key is compromised, revoke it immediately from Settings → API.

​
Getting your API key

1

Go to Settings → API

In the left sidebar, navigate to Settings and click API.
2

Create a new key

Click Create API key, give it a descriptive name (e.g. “Data pipeline trigger”), and select the permissions:
PermissionWhat it allows
agent_jobs_triggerTrigger agent job runs via the API
3

Copy the key

The full key is shown only once immediately after creation. Copy it and store it securely (e.g. as an environment variable or in your secrets manager).

​
Your first API call: trigger a job

The most common API use case is triggering an agent job. Here’s how: 
curl -X POST https://interact.turntwo.com/api/agents/jobs/{job_id}/trigger \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-Id: YOUR_ORG_ID"
Replace {job_id} with the ID of the job you want to trigger. You can find the job ID in the job’s settings page URL in Interact. Successful response: 
{
  "success": true,
  "chat_id": "chat_abc123",
  "job_id": "job_xyz456"
}
The chat_id in the response is the ID of the new chat session created by this run. You can use it to retrieve results later.

​
Fetch a chat and its results

Once a job run completes, retrieve the full chat including any documents (tables, charts) it produced: 
curl https://interact.turntwo.com/api/agents/chats/{chat_id} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-Id: YOUR_ORG_ID"
Response includes:
  • Full message history
  • Documents produced by the agent (query results, charts)
  • Run metadata (status, timestamps)

​
List all chats for an agent

curl "https://interact.turntwo.com/api/agents/chats?agentId={agent_id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-Id: YOUR_ORG_ID"
You can also filter by job ID to get all runs of a specific job: 
curl "https://interact.turntwo.com/api/agents/chats?jobId={job_id}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Organization-Id: YOUR_ORG_ID"

​
Full API reference

Explore all available endpoints, request parameters, and response schemas in the auto-generated API reference below.

Turntwo Interact API

Full endpoint documentation generated from the OpenAPI specification.