API quickstart - Interact

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:

Header	Value
`X-API-Key`	Your API key, created in Settings → API
`X-Organization-Id`	Your 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

Go to Settings → API

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

Create a new key

Click Create API key, give it a descriptive name (e.g. “Data pipeline trigger”), and select the permissions:

Permission	What it allows
`agent_jobs_trigger`	Trigger agent job runs via the API

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.

​What can you do with the API?

​Authentication

​Getting your API key

​Your first API call: trigger a job

​Fetch a chat and its results

​List all chats for an agent

​Full API reference

Turntwo Interact API

What can you do with the API?

Authentication

Getting your API key

Your first API call: trigger a job

Fetch a chat and its results

List all chats for an agent

Full API reference