Quickstart

Make your first Cludo API search call in minutes by setting up authentication, picking your region, and running a sample query against an engine.

This guide walks you through making your first search API call using the v4 API.

Prerequisites: You need a Cludo account with at least one engine configured. Sign in to MyCludo to get your credentials.

Step 1: Find your region

Your region is determined by your customer ID:

Customer ID	Region	Base URL
Below 10,000,000	EU	https://api.cludo.com
10,000,000+	US	https://api-us1.cludo.com

Step 2: Get your credentials

Log in to MyCludo API settings and find the following values:

Value	Where to find it
Customer ID	Dashboard → Account Settings
Engine ID	Dashboard → Engines → select your engine
API Key	MyCludo API settings

Step 3: Build your auth token

Unless an endpoint says otherwise, use Basic (API Key) authentication for Cludo API requests:

# Format: base64(customerId:apiKey)
echo -n "3:c8fk2L9mK4pQ" | base64
# Output: MzpjOGZrMkw5bUs0cFE=

SiteKey authentication is available for public-facing search where you do not want to expose your API key. See the Authentication guide for SiteKey token format.

Try it: build your token

Use the tool below to generate a Basic or SiteKey authorization header and a ready-to-run cURL command. Basic authentication is the default choice unless you are building a public client-side search integration.

Step 4: Make your first search

Keep Basic API keys private. Use the Basic examples from a trusted backend, script, or local test. For browser code, use SiteKey authentication instead.

cURL Basic (EU)

curl -X POST "https://api.cludo.com/api/v4/3/6/search" \
  -H "Authorization: Basic MzpjOGZrMkw5bUs0cFE=" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "*",
    "page": 1,
    "perPage": 10
  }'

curl -X POST "https://api-us1.cludo.com/api/v4/3/6/search" \
  -H "Authorization: Basic MzpjOGZrMkw5bUs0cFE=" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "*",
    "page": 1,
    "perPage": 10
  }'

curl -X POST "https://api.cludo.com/api/v4/3/6/search" \
  -H "Authorization: SiteKey Mzo2OlNlYXJjaEtleQ==" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "*",
    "page": 1,
    "perPage": 10
  }'

import requests
import base64

# Build Basic token: base64(customerId:apiKey)
token = base64.b64encode(b"3:c8fk2L9mK4pQ").decode()

# Use https://api-us1.cludo.com for US region
url = "https://api.cludo.com/api/v4/3/6/search"
headers = {
    "Authorization": f"Basic {token}",
    "Content-Type": "application/json"
}
payload = {
    "query": "*",
    "page": 1,
    "perPage": 10
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

// Build Basic token: base64(customerId:apiKey)
const token = btoa("3:c8fk2L9mK4pQ");

// Use https://api-us1.cludo.com for US region
const response = await fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "*",
    page: 1,
    perPage: 10,
  }),
});

const data = await response.json();
console.log(data);

// Build Basic token: base64(customerId:apiKey)
const token = btoa("3:c8fk2L9mK4pQ");

// Use https://api-us1.cludo.com for US region
fetch("https://api.cludo.com/api/v4/3/6/search", {
  method: "POST",
  headers: {
    "Authorization": `Basic ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "*",
    page: 1,
    perPage: 10,
  }),
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Step 5: Understand the response

{
  "typedDocuments": [
    {
      "fields": {
        "Title": "Getting Started Guide",
        "Description": "Learn how to set up Cludo search...",
        "Url": "https://example.com/getting-started"
      },
      "highlight": {
        "Title": "<b>Getting</b> <b>Started</b> Guide"
      },
      "id": "doc_123",
      "score": 15.7
    }
  ],
  "totalDocument": 42,
  "facets": {},
  "banners": [],
  "suggestions": [],
  "fixedQuery": null,
  "queryId": "abc-123-def",
  "generativeAnswerAvailable": true
}

Field	Description
typedDocuments	Array of search results with field values and highlights
totalDocument	Total number of matching documents
facets	Facet counts for filtering
fixedQuery	Spell-corrected query (if applicable)
queryId	Unique identifier for this search request
generativeAnswerAvailable	Whether AI Chat can answer this query

What’s next?

Search API (v4)

Complete search endpoint reference.

Analytics

Track searches and clicks.

Pushing Content

Push custom content to your search index.

Search Tools

Manage banners, rankings, quicklinks, and synonyms.