Ingest API

Programmatically add knowledge sources to your assistant’s libraries by providing a URL or raw text content. Ideal for automating content sync from CMS, documentation platforms, Slack exports, webhooks, or N8N workflows.

List Libraries

Before ingesting, you need the target library’s ID. Use the library listing endpoint to discover available libraries and check embedding compatibility:

curl https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

# Response:
{
  "libraries": [
    {
      "id": "lib-uuid-...",
      "name": "Product Docs",
      "embeddingProvider": "openai",
      "embeddingModel": "text-embedding-3-large",
      "compatible": true,
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

Libraries marked compatible: true use the same embedding model as your organization’s current settings. Ingesting into incompatible libraries still works, but those sources won’t appear in search results until the models are aligned.

If your API key is restricted to a single library, only that library’s endpoints will accept it. Which visitors can retrieve what you ingest is governed separately by audience labels.

Ingest Endpoint

Send a POST request with the URL of the file to ingest, or raw text content for text-native sources:

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/docs/guide.pdf",
    "fileName": "guide.pdf",
    "externalId": "guide-v2"
  }'

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# #general - May 27\n\n**Alice:** Has anyone seen the Northwind brief?\n**Bob:** Yes, shared it in #northwind-internal...",
    "contentType": "text/markdown",
    "fileName": "#general - May 27 2026",
    "externalId": "slack-C01234-2026-05-27"
  }'

Request Body

Field	Type	Required	Description
url	string	One of	HTTPS URL of the file to download and ingest.
content	string	One of	Raw text content to ingest directly without downloading a file.
contentType	string	No	MIME type for content. Defaults to text/plain. Text-only values are allowed.
fileName	string	No	Display name for the source. Inferred from URL or content type if omitted.
externalId	string	No	Caller-provided identifier for upsert semantics. Max 255 chars.
latitude	number	No	Optional source latitude in WGS84 decimal degrees.
longitude	number	No	Optional source longitude in WGS84 decimal degrees.

Coordinates are optional, but when you provide them you must send both latitude and longitude together. Ragtime copies these values to the stored chunks so later retrieval can filter by location.

Upsert with externalId

When you provide an externalId, the API uses upsert semantics: if a source with the same externalId already exists in the target library, the old source and all its chunks are deleted and replaced with the new content. This applies to both URL-based and inline content ingest.

Without externalId, standard content-hash deduplication applies — uploading the exact same file returns 409 Conflict.

Supported File Types

MIME Type	Extension
application/pdf	.pdf
text/plain	.txt
text/markdown	.md
text/csv	.csv
text/html	.html
application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
application/vnd.ms-excel.sheet.macroEnabled.12	.xlsm
application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
application/vnd.openxmlformats-officedocument.presentationml.slideshow	.ppsx
application/vnd.ms-powerpoint.presentation.macroEnabled.12	.pptm

Spreadsheets are converted to Markdown tables, one section per visible sheet, with the column header repeated on every chunk. Workbooks over 20,000 data rows (counted across all sheets) are rejected — the source is marked failed with an explanatory message.

Presentations are converted to one Markdown section per visible slide, headed by the slide number and title, including tables and speaker notes. Slides whose content is only imagery yield no text; if a whole deck is image-based it is rejected — export it to PDF and upload that instead, so the text is read via OCR.

Responses

// 201 Created — queued for processing
{
  "sourceId": "a1b2c3d4-...",
  "status": "queued",
  "message": "Source queued for processing"
}

// 409 Conflict — duplicate content
{
  "sourceId": "e5f6g7h8-...",
  "status": "duplicate",
  "message": "File already exists in this library"
}

Status	Meaning
201	Source accepted and queued for processing.
400	Invalid request (missing URL/content, bad format, blocked URL, invalid contentType, or remote URL unreachable/timed out).
401	Missing or invalid API key.
403	Key doesn’t match the project or lacks ingest scope.
404	Library not found or not linked to the project.
409	Duplicate content already exists (when no externalId).
413	File or inline content exceeds the maximum size (default: 1 MB for content).
415	Unsupported file type.
429	Rate limit exceeded. Check Retry-After header.
503	Storage not configured for this organization.

Rate Limiting

The ingest endpoint is rate-limited per API key. Default: 30 requests per minute. Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per window.
X-RateLimit-Remaining	Remaining requests in current window.
X-RateLimit-Reset	Unix timestamp when the window resets.
Retry-After	Seconds to wait (only on 429).

Completion Webhook

Subscribe to the source_ingested webhook event to be notified when a source finishes processing. Configure this in Dashboard → Assistant → Webhooks.

Location-aware RAG

Location-aware RAG lets you attach optional GPS coordinates to ingested sources and use the chat user’s location at retrieval time. This is useful for branch finders, regional support, delivery coverage, and any assistant where proximity matters as part of the answer.

When to use it

Use this feature when:

• your knowledge varies by region, branch, store, campus, or service area
• you want the assistant to prefer nearby sources over distant ones
• you need a hard location filter, but still want semantic relevance to matter

If the assistant does not have Require GPS location enabled in the dashboard, any location payload sent by the client is ignored and the chat will not request browser location permission.

Ingestion coordinates

When you ingest a source, you can optionally attach:

• latitude
• longitude

Both values must be provided together and use WGS84 decimal degrees.

Chat request payload

When Require GPS location is enabled, the chat client sends the user’s location with each request:

{
  "location": {
    "latitude": 52.3702,
    "longitude": 4.8952
  },
  "radius": 25000,
  "radiusUnit": "km"
}

• location is the user’s current GPS position.
• radius is optional; the assistant falls back to the dashboard default when omitted.
• radiusUnit accepts km or miles.
• The browser must grant geolocation permission before the assistant can use this data.

Dashboard settings

The Interaction settings expose four geo controls:

• require_geolocation: turn on browser GPS requests and location-aware retrieval.
• geo_radius_default: default radius used when the chat request does not include one.
• geo_radius_unit: default radius unit.
• prioritize_by_distance: blend proximity into ranking instead of using proximity as a hard filter only.

Behavior

With location enabled, retrieval filters knowledge to the configured radius and can optionally favor closer matches when prioritize_by_distance is on. Without it, Ragtime behaves like standard semantic retrieval.

Batch Ingest

To ingest multiple files at once, send an items array instead of a single url. Up to 20 items per request:

curl -X POST https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "url": "https://example.com/docs/guide.pdf", "externalId": "guide-v2" },
      {
        "content": "# Weekly sync\n\n- Slack thread summary",
        "contentType": "text/markdown",
        "fileName": "weekly-sync.md",
        "externalId": "slack-C01234-2026-05-27"
      },
      { "url": "https://example.com/docs/changelog.md" }
    ]
  }'

Each item in the array accepts the same fields as a single ingest request (url, content, contentType, fileName, externalId, latitude, longitude). The response includes a result for every item:

{
 "queued": 2,
 "failed": 1,
 "total": 3,
 "results": [
  {
   "sourceId": "a1b2c3d4-...",
   "status": "queued",
   "message": "Source queued for processing",
   "url": "https://example.com/docs/guide.pdf"
  },
  {
   "sourceId": "e5f6g7h8-...",
   "status": "queued",
   "message": "Source queued for processing",
   "fileName": "weekly-sync.md",
   "contentType": "text/markdown"
  },
  {
   "url": "https://example.com/docs/changelog.md",
   "status": "error",
   "error": "File already exists in this library"
  }
 ]
}

Batch requests return 201 if at least one item was queued, or 422 if all items failed. Individual item errors (duplicates, unsupported types, etc.) are reported in the results array without failing the entire batch.

Source Status

After ingesting a source, poll its processing status to track progress:

curl https://your-ragtime-instance.com/api/v1/projects/{projectId}/sources/{sourceId} \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

// Processing in progress
{
  "sourceId": "a1b2c3d4-...",
  "libraryId": "lib-uuid-...",
  "name": "guide.pdf",
  "type": "application/pdf",
  "status": "processing",
  "progress": { "current": 12, "total": 45 },
  "fileSize": 2048576,
  "externalId": "guide-v2",
  "createdAt": "2026-03-25T12:00:00Z",
  "updatedAt": "2026-03-25T12:00:05Z"
}

// Completed successfully
{
  "sourceId": "a1b2c3d4-...",
  "status": "completed",
  "progress": { "current": 45, "total": 45 },
  ...
}

// Completed with warnings
{
  "sourceId": "a1b2c3d4-...",
  "status": "partial",
  "warnings": ["Some chunks could not be processed"],
  ...
}

// Failed
{
  "sourceId": "a1b2c3d4-...",
  "status": "failed",
  "error": "Unsupported file encoding",
  ...
}

Status	Description
pending	Source uploaded, waiting in queue.
processing	Worker is extracting and embedding chunks. Check progress for details.
completed	All chunks processed successfully.
partial	Completed with warnings — some chunks could not be processed. See warnings array.
failed	Processing failed entirely. See error field.

Using with N8N

Use an HTTP Request node to post file URLs or raw text content to the ingest endpoint. Combine with a Schedule trigger or Webhook trigger to automate content sync:

// N8N HTTP Request node configuration:
// Method: POST
// URL: https://your-ragtime-instance.com/api/v1/projects/{projectId}/libraries/{libraryId}/ingest
// Authentication: Header Auth
//   Header Name: Authorization
//   Header Value: Bearer rt_live_YOUR_KEY_HERE
// Body (JSON):
// URL-based ingest:
{
 "url": "{{ $json.fileUrl }}",
 "fileName": "{{ $json.fileName }}",
 "externalId": "{{ $json.docId }}"
}

// Inline content ingest:
{
 "content": "{{ $json.markdown }}",
 "contentType": "text/markdown",
 "fileName": "{{ $json.title }}",
 "externalId": "{{ $json.docId }}"
}