Source of truth
The documented public API surface is the contract for Semarize REST integrations. Use the API reference, OpenAPI document, and these implementation guides together. Do not depend on internal app routes, admin routes, billing internals, hidden Kit composition, prompt text, retrieval chunks, or knowledge base internals.
The production REST base URL is https://api.semarize.com. Public REST endpoints are versioned under /v1 and authenticated with a Semarize API key in Authorization: Bearer <key>.
- Use /openapi.json for endpoint, schema, parameter, and response details.
- Use /developers/api for endpoint examples and request bodies.
- Use these guides for runtime behavior: retries, polling, errors, rate limits, status, and compatibility.
Recommended build order
| Step | Use | Why it matters |
|---|---|---|
| 1 | POST /v1/test | Confirm the output shape for a Kit without executing AI, persisting a run, or consuming credits. |
| 2 | GET /v1/kits/schema | Map Brick keys and enabled output fields before wiring CRM, BI, QA, or automation destinations. |
| 3 | POST /v1/runs | Create a real run with a stable Idempotency-Key when retries are possible. |
| 4 | GET /v1/runs/{runId} | Poll async runs until the run reaches succeeded, failed, or cancelled. |
| 5 | Webhooks | Use terminal event delivery when polling every run is inefficient or when downstream systems need push updates. |
Production checklist
- Store Semarize API keys in your secret manager and send them only in the Authorization header.
- Use Idempotency-Key on run creation for retry-safe network and 5xx handling.
- Follow Retry-After on 202 and 429 responses. If the JSON body includes retry_after_seconds, use it as the retry delay.
- Treat output.bricks as the public output boundary for completed runs.
- Ignore unknown additive fields so clients remain compatible with non-breaking API additions.
- Log run_id, request id, status, and error code for support and replay workflows.
Guide map
Each guide covers one runtime behavior so implementation details stay easy to cite from agents, docs, and code reviews.
| Guide | Covers |
|---|---|
| Async runs | Create runs, poll safely, handle sync fallback, and use webhooks for terminal events. |
| Idempotency | Use Idempotency-Key so retrying run creation does not create duplicate work. |
| Errors | Map HTTP status codes, flat error envelopes, and terminal run failure fields. |
| Rate limits | Respect Retry-After, slow polling loops, and build controlled batch workers. |
| Versioning | Understand /v1 stability, additive changes, and Kit version pinning. |
| Status | Use status signals, incident retry behavior, and escalation details in production. |
Related guides
Async runs
Create runs, poll safely, handle sync fallback, and use webhooks for terminal events.
Idempotency
Use Idempotency-Key so retrying run creation does not create duplicate work.
Errors
Map HTTP status codes, flat error envelopes, and terminal run failure fields.
Rate limits
Respect Retry-After, slow polling loops, and build controlled batch workers.
Versioning
Understand /v1 stability, additive changes, and Kit version pinning.
Status
Use status signals, incident retry behavior, and escalation details in production.