Prompt Universe API

Overview

The API is small and workspace-scoped. Every response is wrapped in a { data, meta } envelope; errors return a top level error object (see Errors). Builds run asynchronously on a worker, so creation returns immediately and you poll for progress.

Base URL

https://api.universe.searchestra.com

Conventions

• All request and response bodies are application/json.
• Successful responses carry a top level data field, optionally with meta. Errors carry a top level error field.
• Every /v1/* endpoint requires the X-API-Key header. /healthz and /metrics do not.
• Identifiers are UUIDs; versions are semantic (MAJOR.MINOR.PATCH, for example 1.0.0).
• Timestamps are UTC, ISO 8601 (for example 2026-08-19T13:47:09Z).

Lifecycle

A universe moves through a fixed lifecycle. Each build produces candidate queries, selects a representative subset with full intent coverage, and, once you are satisfied, gets locked into an immutable version.

create universe  ──▶  build (async pipeline)  ──▶  status: ready
     │                                                  │
     │                                            lock version ──▶  1.0.0 (immutable)
     │                                                  │
  refresh ◀───────────  new build  ◀── scheduled_review │ structural_market_change
                                                         ▼
                                        read manifest + queries (by intent)

A locked version never changes. To evolve a universe you trigger a refresh, which starts a new build that locks a new version, preserving the old one for historical comparison.

Quickstart

Create a universe, wait for the build, lock it, then read the queries. Replace un_your_key with the key issued to your workspace (see Authentication).

1 · Start a build

curl -X POST https://api.universe.searchestra.com/v1/universes \
  -H "X-API-Key: un_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "project management software",
    "market": "TR",
    "language": "tr",
    "requested_query_count": 120
  }'

{
  "data": {
    "id": "b3f1c2a4-...",
    "universe_id": "9a71e0d2-...",
    "status": "queued",
    "requested_query_count": 120,
    "created_at": "2026-08-19T13:47:09Z"
  }
}

2 · Poll the build

curl https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../builds/b3f1c2a4-.../status \
  -H "X-API-Key: un_your_key"

{
  "data": {
    "status": "running",
    "progress": { "stage": 4, "total_stages": 7, "percentage": 57 },
    "queries_target": 120,
    "queries_selected": 0,
    "candidates_generated": 210
  }
}

3 · Lock the version

curl -X POST https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../builds/b3f1c2a4-.../lock \
  -H "X-API-Key: un_your_key"

{
  "data": {
    "version": "1.0.0",
    "build_id": "b3f1c2a4-...",
    "universe_id": "9a71e0d2-...",
    "query_count": 120,
    "taxonomy_version": "1.0.0",
    "baseline": { "reset_required": false, "compatible_with_previous": null },
    "locked_at": "2026-08-19T13:59:41Z"
  }
}

4 · Read the queries

curl "https://api.universe.searchestra.com/v1/universes/9a71e0d2-.../versions/1.0.0/queries?intent=recommendation" \
  -H "X-API-Key: un_your_key"

Authentication

Every /v1/* request must carry an API key in the X-API-Key header. Keys begin with the un_ prefix and identify a workspace, not a user.

X-API-Key: un_your_key

Keys are provisioned per workspace by the workspaceinit command. The raw value is shown once, at creation, and cannot be recovered; the server stores only a hash. A workspace can hold several keys, and revoking one does not affect the others.

Create a universe

Creates a new universe and starts its first build asynchronously. Returns 201 with the build; the pipeline continues on a worker. Poll build status for progress.

Request body

Build status

Returns the build's progress. Poll this until status reaches a terminal state (for example ready or failed).

{
  "data": {
    "status": "ready",
    "progress": { "stage": 7, "total_stages": 7, "percentage": 100 },
    "queries_target": 120,
    "queries_selected": 120,
    "candidates_generated": 240
  }
}

To inspect the universe and its builds together, call GET /v1/universes/{id}. A per-build health summary is available at .../builds/{build_id}/health.

Lock a version

Freezes a ready build into an immutable, semantically versioned universe. After locking, the version's manifest and queries can never change.

If a universe has exactly one active build, the alias POST /v1/universes/{id}/lock locks it without a build id. Locking a build that is not ready, or a universe with multiple active builds via the alias, returns 409 conflict.

Get the manifest

Returns the version's Universe Manifest: the immutable description of how this universe was sampled — taxonomy, intent distribution, coverage and provenance. This is the reference a measurement run pins to.

The alias GET /v1/universes/{id}/manifest returns the manifest of the latest locked version. Intent coverage is also summarised at GET /v1/universes/{id}/coverage.

List queries

Returns the queries of a locked version. Every query carries complete, stable intent metadata, so you can segment measurement per intent.

Query parameters

The alias GET /v1/universes/{id}/queries lists queries from the latest locked version.

Refresh a universe

Triggers a new build to evolve the universe. The old version stays locked and comparable; the new build locks a new version.

Evidence datasets

Optional. Create a dataset of observed demand (real questions seen in the wild), then ingest items into it. When a build uses intent_policy: observed_weighted, these datasets ground the sampling so proportions reflect what the market actually asks.

curl -X POST https://api.universe.searchestra.com/v1/evidence/datasets \
  -H "X-API-Key: un_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "TR PM search logs Q3", "source_summary": "anonymised site search" }'

Ingest items with POST /v1/evidence/datasets/{id}/items, then reference the dataset id in a universe's control_plane.evidence_dataset_ids.

Intents

Every query is classified into exactly one intent. Coverage across all four is planned on purpose, not left to chance.

Versioning & baseline

Versions are immutable and semantic. A measurement run references a specific version, which guarantees historical comparability: the exact question set behind last quarter's numbers still exists, unchanged.

• Immutable: once locked, a version's manifest and queries never change.
• Baseline disclosure: a lock reports whether it is compatible_with_previous. When reset_required is true, measurement must begin a new baseline and not merge across the boundary.
• Refresh: evolving a universe means a new version, never an edit to an old one.

Errors

Errors return an error object with a code, a message and optional details.

{ "error": { "code": "unauthorized", "message": "X-API-Key required." } }

Budgets & limits

Because a build calls LLMs, each build runs under explicit guards, so a universe cannot cost or run without bound.

Budgets scale with your plan. Exact defaults (query count, cost, duration) are set per deployment.