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.

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

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.

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 }}"
}