Quickstart

This is the fastest path from nothing to a working search. You’ll create a source, push a few records straight over HTTP, and search them — no files, no infrastructure. When you’re ready for real data, Add your data covers file uploads and your own S3 bucket.

Prerequisites

A tenant API key (spltk.v1.…) and your tenant ID, both from the console: open the API Keys panel and create a key. The key is shown once.
An admin role in the tenant — minting a key, and creating a source, both require admin. (Minting the key is the one step that must be done by a signed-in admin in the browser; see Authentication for why, and for the platform-key model if you run many tenants.)

Creating the key in the console is the only step here that needs a browser — every call below is plain HTTP you can run yourself or hand to an agent.

Export your credentials once so the examples run as-is:

export SPLENDOR_TOKEN="spltk.v1...."   # your tenant API key
export SPLENDOR_TENANT_ID="your-tenant-id"

Steps

Create a source

A source is where data lands and which dataset it feeds. Create one hosted source for this quickstart.

curl https://api.withsplendor.com/v1/admin/hosted-sources \
  -H "Authorization: Bearer $SPLENDOR_TOKEN" \
  -H "X-Splendor-Tenant-Id: $SPLENDOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "source_key": "quickstart",
    "name": "Quickstart",
    "dataset_id": "quickstart",
    "source_type": "hosted"
  }'

Note the numeric source_id in the response — you need it for the next step.

Mint an ingest token

An ingest token authorizes pushing data to this one source. It carries the source and tenant itself, so ingest calls need no tenant header. The plaintext token is shown once.

curl -X POST https://api.withsplendor.com/v1/admin/sources/$SOURCE_ID/ingest-token \
  -H "Authorization: Bearer $SPLENDOR_TOKEN" \
  -H "X-Splendor-Tenant-Id: $SPLENDOR_TENANT_ID"

Export it for the push step:

export SPLENDOR_INGEST_TOKEN="sit_live_..."

Push a few records

Send a small batch of records as a JSON array. Splendor accepts it and indexes it asynchronously, returning 202 Accepted.

curl https://api.withsplendor.com/v1/ingest/sources/quickstart/logs \
  -H "Authorization: Bearer $SPLENDOR_INGEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {"level": "error", "message": "connection timeout after 30s", "service": "checkout"},
    {"level": "info",  "message": "payment captured", "service": "checkout"},
    {"level": "warn",  "message": "retrying upstream call", "service": "search"}
  ]'

Wait until it's searchable

Indexing takes a moment. Poll the dataset’s readiness until text search is ready.

curl https://api.withsplendor.com/v1/datasets/quickstart/readiness \
  -H "Authorization: Bearer $SPLENDOR_TOKEN" \
  -H "X-Splendor-Tenant-Id: $SPLENDOR_TENANT_ID"

Search it

Query the dataset. The body selects the datasets, the query text, and how many results to return.

curl https://api.withsplendor.com/v1/search \
  -H "Authorization: Bearer $SPLENDOR_TOKEN" \
  -H "X-Splendor-Tenant-Id: $SPLENDOR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"text": "timeout", "datasets": ["quickstart"], "limit": 10}'

import os, httpx

client = httpx.Client(
    base_url="https://api.withsplendor.com",
    headers={
        "Authorization": f"Bearer {os.environ['SPLENDOR_TOKEN']}",
        "X-Splendor-Tenant-Id": os.environ["SPLENDOR_TENANT_ID"],
    },
)
envelope = client.post(
    "/v1/search",
    json={"text": "timeout", "datasets": ["quickstart"], "limit": 10},
).json()
for result in envelope["results"]:
    print(result["score"], result["body"][:120])

You get back the response envelope — the same shape for every kind of search:

{
  "search_id": "srch_8f2c...",
  "mode": "text",
  "returned": 1,
  "total": { "value": 1, "relation": "eq" },
  "has_more": false,
  "results": [
    {
      "id": "rec_01H...",
      "body": "connection timeout after 30s",
      "snippets": ["connection <em>timeout</em> after 30s"],
      "score": 12.4,
      "provenance": { "dataset_id": "quickstart", "source": "quickstart", "line": 1 }
    }
  ]
}

Keep the search_id — it’s a handle you can use to page, export, or save the query as a view, without re-sending it.

If results is non-empty and you have a search_id, you’re working end to end — from an empty workspace to a search result.

What to do next

See what you can build

Real patterns: search by meaning, search by image, one search backend per customer.

Add your real data

Upload files, stream events, or read from your own S3 bucket.

Search model

Text, SQL, and semantic search — and when to use each.

Handles & cursors

Page through results, export, and re-run queries from a handle.

Get started

Core concepts

Guides

Build a platform

Roles, permissions & plans

Platform reference

Prerequisites

Steps

What to do next

See what you can build

Add your real data

Search model

Handles & cursors

​Prerequisites

​Steps

​What to do next

See what you can build

Add your real data

Search model

Handles & cursors

Prerequisites

Steps

What to do next