Base URL & Auth
All project-scoped `/v1` endpoints require `X-API-Key` and `X-Project-Id` headers.
https://app.sepurux.dev/api/backendX-API-Key: <project_api_key>
X-Project-Id: <project_uuid>
Content-Type: application/jsonCore Endpoints
These are the public integration endpoints most teams need first. Administrative and destructive management routes stay inside the authenticated product workspace.
| Endpoint | Purpose |
|---|---|
| POST /v1/traces | Upload trace payloads from SDK or custom instrumentation. |
| POST /v1/campaigns | Create campaign definitions for replay and mutation execution. |
| PATCH /v1/campaigns/{id}/eval-set | Register real-world traces as the CI scenario pool and configure min_scenarios gate. |
| POST /v1/runs | Queue run execution for a trace and campaign pair. |
| GET /v1/runs/{run_id} | Fetch run status, summary, and scoring context. |
| GET /v1/runs/{run_id}/policy-events | Inspect policy decisions recorded during execution. |
| GET /v1/runs/{run_id}/security-events | Inspect security actions and risk context by attempt. |
| POST /v1/ci/runs | Create a CI evaluation run (or batch when eval-set traces are registered). |
| GET /v1/ci/runs/{run_id} | Poll single CI run pass/fail decision and dashboard URL. |
| GET /v1/ci/batch/{batch_id} | Aggregate pass/fail verdict across a batch of scenario runs. |
Request Examples
Start from these examples and expand payloads based on your workflow semantics.
Create trace
from sepurux import SepuruxClient
client = SepuruxClient.from_env()
with client.trace("refund_flow", {"ticket_id": "t-101"}) as trace:
trace.model_step("triage", {"text": "process refund"})
trace.tool_call("payments.refund", {"amount": 4200})
trace.tool_result("payments.refund", {"status": "queued"})
print(trace.trace_id)Start run
import time
from sepurux import SepuruxClient
client = SepuruxClient.from_env()
run_id = client.start_run(
trace_id="<trace_uuid>",
campaign_id="<campaign_uuid>",
)
# Poll until terminal
while True:
run = client.get_run(run_id)
if run["status"] in {"completed", "failed"}:
break
time.sleep(5)
print(run["status"], run.get("summary", {}).get("pass_rate"))Eval-Set & Batch CI
Register a pool of real-world traces against a campaign. CI runs then replay every registered trace in parallel and gate on the aggregated verdict.
Register trace pool
# Register real-world traces as the scenario pool for a campaign.
# CI runs against this campaign will replay every registered trace.
curl -X PATCH https://app.sepurux.dev/api/backend/v1/campaigns/<campaign_uuid>/eval-set \
-H "Content-Type: application/json" \
-H "X-API-Key: $SEPURUX_API_KEY" \
-H "X-Project-Id: $SEPURUX_PROJECT_ID" \
-d '{
"add_trace_ids": ["<trace_uuid_1>", "<trace_uuid_2>"],
"min_scenarios": 3
}'Batch run + poll
# When the campaign has an eval-set, POST /v1/ci/runs creates one run
# per registered trace and returns a shared batch_id.
POST /v1/ci/runs
{
"campaign_id": "<campaign_uuid>",
"thresholds": { "min_pass_rate": 0.85, "max_unsafe": 0, "max_failures": 0 }
}
# → { "run_id": "...", "run_ids": ["...", "..."], "trace_count": 3, "ci_batch_id": "..." }
# Poll the aggregated verdict — pass only when ALL scenario runs pass.
GET /v1/ci/batch/<batch_uuid>
# → {
# "status": "done",
# "decision": "pass",
# "pass_rate": 0.91,
# "scenario_coverage_pct": 100.0,
# "trace_count": 3
# }add_trace_ids / remove_trace_ids
Incrementally build or trim the scenario pool. Accepts arrays of trace UUIDs.
min_scenarios
CI submission is rejected (422) if the registered pool falls below this count. Prevents gating against a trivially small scenario set.
scenario_coverage_pct
Returned by the batch endpoint: completed runs / total traces × 100. Use this to verify full coverage before acting on the verdict.
Schema & Explorer
Public docs stay focused on the core integration surface. Full interactive explorer access is available inside the authenticated product workspace.