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

# How the Ingest API works

> Send conversations and tables from your own systems into Rippit when there is no built-in integration for them.

The Ingest API is for data Rippit doesn't have a dedicated [integration](https://docs.rippit.com/plg/data-integrations.md) for: chats from your own product, an internal ticket system, a call transcript export, or a table in your database or warehouse. You send it with an API token, and it lands in Rippit as a table you can query, report on, and point Agent Apps at, the same as integrated data.

You don't have to write the code yourself. Drop the [Bulk Ingest API skill](https://docs.rippit.com/ingest-api/rippit-bulk-ingest-api.md) into your assistant and it walks you through every step below, then writes and runs the upload script for you.

> [!NOTE]
>
> The Ingest API is for bulk uploads, not a streaming real-time ingest (i.e. a webhook per conversation or row). Data shows up in Rippit after each upload is processed, so run it on a schedule (hourly or daily) to keep Rippit current. A real-time streaming API is coming soon.

## What you can send

There are two types of upload. Pick the one that matches your data.

| | Type 1: Conversations | Type 2: Tables |
| - | - | - |
| **What it is** | Back-and-forth messages between two sides: customer and agent, user and bot, buyer and sales rep | Flat rows, one per record: accounts, orders, subscriptions, product usage, custom attributes |
| **One row is** | One conversation and all of its messages | One record |
| **File format** | JSON Lines | Parquet (recommended) or JSON Lines |
| **In Rippit** | One table per conversation source, with your own fields as columns | One table per dataset |
| **Re-sending a record** | Updates it, matched on your conversation ID | Updates it, matched on the primary key you choose |
| **Guide** | [Conversations guide](https://docs.rippit.com/ingest-api/conversations.md) | [Tables guide](https://docs.rippit.com/ingest-api/tables.md) |
| **For your assistant** | [bulk\_conversations.md](https://integrations.maestroqa.com/api/v2/guides/bulk_conversations.md) | [bulk\_datasets.md](https://integrations.maestroqa.com/api/v2/guides/bulk_datasets.md) |

Tables join to conversations on a `conversation_id` column, so you can send ticket metadata or the orders a customer placed alongside the conversation itself.

Because re-sending a record updates it instead of duplicating it, the same upload is safe to run every hour or every day.

## Before you start

The Ingest API has to be enabled for your workspace. If it isn't, every request returns `403`; ask your Rippit contact to turn it on.

You need to be a workspace admin to create an API token.

## Get an API token

1. In Rippit, open **Tables**, click **Add table**, then **Add API Table**. You can also ask Rippit in chat to connect via API.
2. Click **Create API token**, or **Copy** next to an existing one.

Send the token in an `apitoken` header on every request. Treat it like a password: keep it out of scripts and out of chats with your assistant. The skill stores it in a private file only you can read.

## How an upload works

1. **Name the destination once.** A conversation source (such as `in-app chat`) or a dataset (such as `accounts`). Doing this again with the same name is safe.
2. **Ask for an upload slot.** Rippit returns a one-time upload link, valid for one hour.
3. **Upload one file** to that link, up to 128 MB.
4. **Mark the upload finished.** Processing starts right away.
5. **Check the job** until it says `done`. Rows that failed come back with their line number and the reason, while the rest are written.

Start with a small test upload, such as 10 conversations or 1,000 rows, and check the result in Rippit before sending everything.

## Limits

These are the free tier limits. Need more? Contact your Rippit point of contact, or ask in the [Rippit Community](https://docs.rippit.com/community.md), and we can raise them for your workspace.

| Limit | Free tier |
| - | - |
| File size | 128 MB per upload |
| Uploads | 10 per minute, 100 per hour, 100 per day |
| Messages per conversation | 10,000 |
| Columns per dataset | 500 |

Going over the upload limit returns `429` with a `Retry-After` header. Wait that many seconds and try again.

## Next steps

* [Drop in the Bulk Ingest API skill](https://docs.rippit.com/ingest-api/rippit-bulk-ingest-api.md)
* [API schema (OpenAPI)](https://integrations.maestroqa.com/api/v2/openapi.json)
* [How data integrations work](https://docs.rippit.com/plg/data-integrations.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.