prompter API

Overview

prompter exposes a small REST API. You send a prompt and a platform, prompter calls that platform, and returns the unmodified answer. It never summarizes or invents data: if a platform cannot answer, the response says so.

Base URL

https://api.prompter.searchestra.com

Conventions

• All request and response bodies are application/json.
• Successful reads return a top level data field. Errors return a top level error field (see Errors).
• Every /v1/* endpoint requires the X-API-Key header. /healthz does not.
• Timestamps are UTC, ISO 8601 (for example 2026-08-16T13:47:09Z).

Quickstart

Send your first query. Replace pr_your_key with the API key issued to your tenant (see Authentication).

curl -X POST https://api.prompter.searchestra.com/v1/collect \
  -H "X-API-Key: pr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "perplexity",
    "promptText": "which dishwasher detergent is best, briefly",
    "countryCode": "tr",
    "language": "tr"
  }'

{
  "data": {
    "rawText": "Finish and Fairy are among the most preferred...",
    "rawHtml": "",
    "citations": [
      { "url": "https://example.com/review", "title": "Best detergent", "position": 1 }
    ],
    "textLinks": [],
    "collectedAt": "2026-08-16T13:47:09Z"
  }
}

Authentication

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

X-API-Key: pr_your_key

The server stores only a SHA-256 hash of the key. The raw value is shown once, at creation, and cannot be recovered. If a key is lost, issue a new one. A tenant can hold several keys; revoking one does not affect the others.

Query a platform

Sends one prompt to one platform and returns the raw answer. The flow: validate promptText, confirm the platform is registered, then make a real upstream request.

Request body

Response data

List platforms

Returns the fixed list of registered platforms. A platform whose credentials are not configured still appears here; it only fails on a real /v1/collect call. Fetch this once and cache it on your side.

{
  "data": [
    { "code": "chatgpt", "unsupportedCountries": [] },
    { "code": "perplexity", "unsupportedCountries": null }
  ]
}

unsupportedCountries is either an empty array or null; both mean "no restriction". Treat them the same way.

Health check

Liveness probe for container orchestration. No authentication. Returns 200 when the service is up.

Platforms

Nine platforms have a real integration. citations are native only on the three sourced platforms; the six LLM platforms surface links through textLinks instead.

Errors

Errors return an error object with a code and a message.

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

Rate limits and quotas

prompter applies four independent guards. The first two are per API key and return 429; the next two are per tenant and platform and return 422; the last is shared across all tenants and returns 503.

Limits scale with your plan. The circuit breaker opens after a platform fails repeatedly and closes automatically after a cooldown.