API

Access comprehensive documentation, guides, and resources for integrating Raffle’s API into your projects.
page icon

API Index

Getting Started with API Index
page icon

Guides

Implementation guides for Raffle API
page icon

Latest

Comprehensive API documentation and guides
page icon

V1

Comprehensive API documentation and guides

API Overview

The Raffle API lets you build your own search experience on top of Raffle, and push your own content into Raffle. All endpoints live under https://api.raffle.ai/.

This page explains how the API fits together: which endpoints need a key, where keys come from, and which limits apply. For the full request and response schemas, see the API Reference. The previous version is at /api/v1/.

Two kinds of endpoints

Search endpoints: called with a widget UID

These endpoints power a search experience. They are called with the UID of an API widget and no API key:

Endpoint What it does
GET /v2/search Search results for a query
GET /v2/summary An AI-generated summary of the results, with references
GET /v2/autocomplete Query suggestions while the user types
GET /v2/top_questions The questions users ask most
POST /v2/feedback Tells Raffle that a user clicked a search result
POST /v2/support Tells Raffle that a user was sent to support

The UID is passed as the uid parameter (in the request body for /support). These endpoints are meant to be called from a browser, so the UID is visible in your website’s code. Treat it as public.

To find the UID, go to Widgets, open your API widget, click Install and copy the UID. If you don’t have an API widget yet, create one first.

Document endpoints: called with an API key

The endpoints under /v2/sources/ manage the documents of an API source: list, get, create or update, and delete. They need an API key in the X-API-Key header. See API Index.

API keys

API keys are managed in Workspace → API, on the API Keys page. Only users with the Account Admin role can open it.

  • Click Add new API key, give the key a name and confirm.
  • The key is shown once, right after you create it. Copy it and store it safely. If you lose it, create a new key and delete the old one.
  • A key belongs to the whole account and stays valid until you delete it.

API keys are only used by the document endpoints. Keep them on your server and never put them in code that runs in a browser.

Search and summary

  • Moderation: queries can be screened by content moderation. /search answers a rejected query with 400 Bad Request.
  • Loading: a summary is written by an AI model and takes longer than a search, so show a loading state while you wait for it.
  • No relevant results: when /summary can’t answer a query, it returns status: "no-relevant-results" with an empty summary. A reference only has a url if its source has one.
  • Reference format: /summary takes an optional reference_format, either html (the default) or markdown.
  • Origin URL: /search takes an optional origin-url, the URL of the page where the search started. It must be an http or https URL.
  • Session ID: /search requires a session-id, which groups a user’s searches into a session. A random ID generated per visit works.

Other endpoints

  • POST /v2/support: when your interface sends a user to support outside Raffle, call this endpoint with the widget uid and the url the user was on, so the event shows up in your analytics.

Guides