API Index

This guide walks you through the new API Index type of source, that allows you to send content via API unlocking full control over your indexes

Introduction

Use the API Index to push documents directly via API using your Index UID and an API Key. This gives you full control over what goes into your index and when it changes.

Base route:
```
https://api.raffle.ai/v2/indexes/
```
Index UID: the unique id of your index (visible in the product UI). 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:

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

Check the Document Schema section below.

Prerequisites

Create an API Key in API Keys (the secret is shown only once).

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.
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/indexes/{index_uid}/documents

Query parameters

Parameter	Type	Description
`limit`	int	Number of results (default: 10)
`after-uid`	string	Pagination cursor

Response

{
  "documents": [
    {
      "uid": "document-123",
      "title": "Example Document",
      "content": "<p>Content here</p>"
    }
  ]
}

PUT

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

PUT https://api.raffle.ai/v2/indexes/{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

Parameter	Type	Description
`document_uid`	string	Stable unique document identifier

Request body

Field	Type	Required
`title`	string	Required
`content`	string (HTML)	Required
`source_url`	string	Required
`last_modified`	string (ISO 8601)	Optional

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 204 No Content

DELETE

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

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

Path parameters

Parameter	Type	Description
`document_uid`	string	Unique document identifier

Document Schema

Field	Type	Notes
`uid`	string	Unique document id
`title`	string	Required
`content`	string (HTML)	Required
`source_url`	string	Optional
`last_modified`	string (ISO 8601)	Optional

Errors

Standardized error payload:

{
  "code": 401,
  "message": "Invalid API Key"
}

Read more about Api-Index in the API Reference.

Guides