API documentation | Synderesis Catholic AI

Authentication

Send exactly one of these headers with Content-Type: application/json:

Authorization: Bearer <SYNDERESIS_API_KEY>
X-API-Key: <SYNDERESIS_API_KEY>

The plaintext key is shown once when you create it. After that, Account lists only the prefix, status and limits. All keys on an account share one allowance. You can keep up to ten active customer or extension keys.

Models

Use synderesis-spark for everyday answers or synderesis-pro for deeper reasoning. Omitting model on chat completions defaults to Synderesis Spark. List the public aliases with GET /v1/models.

Answers

POST /v1/answers is the product answer endpoint. Pass a question. Grounding in official Church sources is on unless you set grounding to false. The earlier name retrieve_sources still works the same way. If both are sent, grounding is used.

curl https://www.synderesis.eu/v1/answers \
  -H "Authorization: Bearer $SYNDERESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Why must AI systems respect human dignity?",
    "model": "synderesis-spark",
    "grounding": true,
    "max_tokens": 320
  }'

The frontend-safe text is answer. Parsed citations and qualifications are under structured_answer. Usage tokens are returned without internal supplier-cost fields.

Chat completions

POST /v1/chat/completions accepts an OpenAI-compatible messages array:

curl https://www.synderesis.eu/v1/chat/completions \
  -H "X-API-Key: $SYNDERESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "synderesis-spark",
    "messages": [{"role": "user", "content": "Give a short answer about human dignity."}],
    "max_tokens": 320
  }'

Grounding and usage

GET /v1/sources/search?query=…&limit=6 or POST /v1/sources/search with JSON query and optional limit (1–20) and source_ids.
GET /v1/usage returns account-wide usage for the current period.

Errors and metering

Errors are JSON. error.type and error.code are the same stable code, error.message says what went wrong and how to fix it, and error.request_id identifies the request. Responses do not include stack traces or internal model ids.

400 invalid_request — the JSON body is missing or malformed, or larger than 65536 bytes (921600 bytes for chat completions). Send an object with question for answers, or messages for chat completions.
400 unsupported_model — that model is not available. Choose an id from GET /v1/models.
401 unauthorized — the API key is missing or invalid. Send Authorization: Bearer or X-API-Key from your server.
402 free_allocation_exhausted — the one-time free allocation is used up. Subscribe from Account.
404 not_found — that path does not exist.
405 method_not_allowed — that method is not allowed for this path. OPTIONS is included, because this API does not use CORS.
429 quota_exceeded — the account has reached its plan limit. Check Account, then try again after the limit resets.
429 rate_limited — too many requests. Wait and try again.
503 service_unavailable — the service is temporarily unavailable. Try again later.