Skip to main content
This guide takes you from credentials to your first search result. By the end you will have listed your datasets, run a query, and read the response envelope that every search returns.

​
Prerequisites

  • A Splendor API token and your tenant ID. Both are available from the console under your workspace settings.
  • At least one dataset that has finished ingesting. New to ingestion? See Datasets & schema.
Export your credentials once so the examples below run as-is:
export SPLENDOR_TOKEN="your-api-token"
export SPLENDOR_TENANT_ID="your-tenant-id"

​
Steps

1

List your datasets

Confirm your credentials work and find a dataset to query.
curl https://api.withsplendor.com/v1/datasets \
  -H "Authorization: Bearer $SPLENDOR_TOKEN" \
  -H "X-Splendor-Tenant-Id: $SPLENDOR_TENANT_ID"
Pick a dataset_id from the response to use in the next step.
2

Run a search

Search the dataset for a keyword. The request 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": ["your-dataset-id"],
    "limit": 10
  }'
3

Read the response envelope

Every search — text, SQL, or semantic — returns the same shape. The fields tell you what came back and whether more exists.
{
  "search_id": "srch_8f2c...",
  "mode": "text",
  "datasets": ["your-dataset-id"],
  "returned": 10,
  "limit": 10,
  "total": { "value": 1240, "relation": "eq" },
  "has_more": true,
  "next_cursor": "eyJvZmZ...",
  "route": "hot",
  "wall_ms": 183.4,
  "results": [
    {
      "id": "rec_01H...",
      "body": "connection timeout after 30s",
      "snippets": ["connection <em>timeout</em> after 30s"],
      "score": 12.4,
      "score_kind": "bm25",
      "provenance": { "dataset_id": "your-dataset-id", "source": "app-logs", "line": 4821 }
    }
  ]
}
Keep the search_id. It is a handle you can use to page deeper, export the full result set, or save the query as a view — without re-sending the query body.
If results is non-empty and you have a search_id, your integration is working end to end.

​
Next steps

Search model

Compare text, SQL, and semantic search and when to use each.

Handles & cursors

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

Views

Save a query or materialize a result set for repeatable analysis.

Authentication

Understand tokens, the tenant header, and roles.