API Index

Introduction

Use an API source to push documents directly via API, using the source’s UID and an API Key. This gives you full control over what goes into the source and when it changes. In the API, a source is called an index.

• Base route:

  https://api.raffle.ai/v2/sources/
  

• Source UID: the unique id of your API source, shown on the source’s Docs page in the Raffle web app. You will reference it in every endpoint as {index_uid}.

For the most up to date technical documentation, refer to the API Reference.

Available parameters

You can set different parameters:

1. title, that will be the title displayed in search result
2. content, a section of the content will be displayed as the search result description
3. source_url, where the search results links to
4. last_modified, a date you can use to influence the result ranking (optional)

Check the Document Schema section below.

Prerequisites

1. Create an API Key in Workspace → API (the key is shown only once). Only Account Admins can create keys. See API keys.

   Note

   The API Key is displayed a single time. Make sure to copy it and store it safely. If you lose the key, generate a new one and delete the previous one.

2. Use the header on every request:

   X-API-Key: <your-api-key>
   

Endpoints

GET

/documents — List documents {#get-documents}

GET https://api.raffle.ai/v2/sources/{index_uid}/documents

Documents are returned sorted by their uid. To fetch the next page, pass the uid of the last document you received as after-uid.

Query parameters

Response

{
  "documents": [
    {
      "uid": "document-123",
      "title": "Example Document",
      "content": "<p>Content here</p>",
      "source_url": "https://example.com/document-123",
      "last_modified": "2026-01-31T12:00:00Z"
    }
  ]
}

/documents/{document_uid} — Get a document {#get-document}

GET https://api.raffle.ai/v2/sources/{index_uid}/documents/{document_uid}

Returns a single document, with the same fields as in the list above. If the document doesn’t exist, the API answers 404.

PUT

/documents/{document_uid} — Upsert (create or update) {#put-document}

PUT https://api.raffle.ai/v2/sources/{index_uid}/documents/{document_uid}

Purpose

This endpoint both creates new documents and updates existing ones based on the document_uid you provide.

Path parameters

Request body

A missing or empty required field, or a value over its limit, is rejected with 400.

Why upsert?

Most teams already maintain content in a database or external system. Reusing your system’s stable id keeps mapping trivial. When creating, pass a stable id as document_uid — e.g., your DB entity id, a UUID you generate, or the source_url. One of those should be used as the id you send.

Response

HTTP/1.1 200 OK

The response has no body.

DELETE

/documents/{document_uid} — Delete a document {#delete-document}

DELETE https://api.raffle.ai/v2/sources/{index_uid}/documents/{document_uid}

Path parameters

Document Schema

Errors

Standardized error payload:

{
  "code": 404,
  "message": "The specified index does not exist"
}

• A missing, empty or invalid X-API-Key header is answered with 400; a key that isn’t authorized is answered with 401.
• An unknown source UID or document UID is answered with 404.

Read more about Api-Index in the API Reference.