> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getinteract.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API quickstart

> Use the Interact API to trigger agent jobs and retrieve results programmatically.

## 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** |

<Warning>
  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**.
</Warning>

## Getting your API key

<Steps>
  <Step title="Go to Settings → API">
    In the left sidebar, navigate to **Settings** and click **API**.
  </Step>

  <Step title="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 |
  </Step>

  <Step title="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).
  </Step>
</Steps>

## Your first API call: trigger a job

The most common API use case is triggering an agent job. Here's how:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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.

<Card title="Turntwo Interact API" icon="code" href="/api-reference/turntwo-interact-api">
  Full endpoint documentation generated from the OpenAPI specification.
</Card>