Semarize
Start building

API Reference

Base URL: https://api.semarize.com|All endpoints require Authorization: Bearer <api_key>

Authentication

All API requests require a Bearer token in the Authorization header. API keys follow the format smz_live_* (production) or smz_test_* (sandbox).

Authorization header
Authorization: Bearer smz_live_your_api_key_here

Key details

Keys are hashed before storage - you cannot retrieve a key after creation.

Keys are scoped to a workspace. All runs created with a key belong to that workspace.

Keys can optionally have an expiration date. Expired keys return 401.

Runs

A Run executes a Kit against a conversation and produces structured output. Create runs with POST /v1/runs. By default runs are async (202 → poll). Add "mode": "sync" to block until completion.

POST/v1/runs

Create a run

Create a run. Default mode is async (returns 202 immediately, poll for results). Set mode to sync to block until completion (returns 200 or 202 fallback).

Bearer token (API key)

Headers

AuthorizationrequiredBearer <api_key>
Content-Typerequiredapplication/json
Idempotency-KeyoptionalClient-generated unique key (max 254 chars). Prevents duplicate runs.
X-Request-IdoptionalOptional request tracking ID.

Request body

kit_codestringrequiredThe 8-character Kit code identifying which Kit to run.
kit_version_idstringoptionalUUID of a specific Kit version. Overrides kit_code if provided.
inputobjectrequiredThe conversation data. Shape depends on the Kit configuration (typically includes a transcript field).
typestringoptionalRun type. Defaults to "api". Options: api, sandbox.
modestringoptionalExecution mode. Defaults to "async". Options: async, sync. Sync mode blocks until the run completes or times out.
cURL
curl -X POST https://api.semarize.com/v1/runs \
-H "Authorization: Bearer smz_live_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: unique-request-id-123" \
-d '{
"kit_code": "A1B2C3D4",
"input": { "transcript": "..." }
}'
Response 202
{
"run_id": "uuid",
"status": "queued",
"run_type": "api",
"created_at": "2026-02-24T12:00:00.000Z"
}
GET/v1/runs

List runs

List runs for the authenticated workspace. Ordered by most recent first.

Bearer token (API key)

Query parameters

limitintegerNumber of runs to return. Range: 1–100. Default: 50.
cURL
curl https://api.semarize.com/v1/runs?limit=10 \
-H "Authorization: Bearer smz_live_your_key"
Response 200
[
{
"run_id": "uuid",
"status": "succeeded",
"run_type": "api",
"created_at": "2026-02-24T12:00:00.000Z"
}, ...
]
GET/v1/runs/:runId

Get run details

Retrieve the full details of a run including output (when succeeded), error information, and duration.

Bearer token (API key)
Response 200 - succeeded
{
"run_id": "uuid",
"status": "succeeded",
"run_type": "api",
"duration_ms": 1200,
"error_code": null,
"error_message": null,
"output": {
"kit_code": "A1B2C3D4",
"kit_version_id": "uuid",
"bricks": {
"pain_is_specific": {
"value": 64,
"confidence": 0.95,
"reason": "Pain identified but not quantified",
"evidence": ["losing 3 hours a week"]
}
}
}
}

Brick output fields

Each Brick is keyed by its unique key (e.g. pain_is_specific). Output fields are configurable per Brick - not every Brick will return all fields.

valueThe typed result (boolean, number, string, or category). Always present.
confidenceConfidence score from 0 to 1. Present when enabled for the Brick.
reasonShort explanation of why this value was returned. Present when enabled for the Brick.
evidenceArray of text spans from the conversation. Present when enabled for the Brick.
GET/v1/runs/:runId/usage

Get run usage

Retrieve token usage and credit consumption for a completed run. Useful for monitoring and optimization.

Bearer token (API key)
Response 200
{
"run_id": "uuid",
"token_usage": { "prompt": 1200, "completion": 340 },
"credits_consumed": 8
}

Sync mode details

Add "mode": "sync" to your POST /v1/runs request body. The API attempts to execute the run inline and return the result directly.

Response behavior

200Run completed inline. Response has the same shape as GET /v1/runs/:runId. Inspect status - HTTP 200 means the request cycle completed, not necessarily that the run succeeded.
202Run didn't complete in time. Response includes sync_fallback: true and waited_ms. Fall back to polling with the returned run_id. Includes Retry-After header.
cURL - sync mode
curl -X POST https://api.semarize.com/v1/runs \
-H "Authorization: Bearer smz_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"kit_code": "A1B2C3D4",
"mode": "sync",
"input": { "transcript": "..." }
}'
Response 200 - sync completed
// Same shape as GET /v1/runs/:runId
{
"run_id": "uuid",
"status": "succeeded",
"duration_ms": 1200,
"output": {
"bricks": {
"pain_is_specific": {
"value": 64,
"confidence": 0.95,
"reason": "...",
"evidence": ["..."]
}
}
}
}
Response 202 - sync fallback
// Run didn't complete in time - poll with run_id
{
"run_id": "uuid",
"status": "running",
"sync_fallback": true,
"waited_ms": 60000,
"created_at": "2026-02-24T12:00:00.000Z"
}
// Retry-After header included in response

Kits & Bricks

Introspect Kit output schemas and Brick metadata. Useful for validating integrations and understanding what fields each Brick returns before creating runs.

GET/v1/kits/:kitId/schema

Get Kit output schema

Returns the output schema for a Kit, including all Bricks and their configured output fields. Use this to understand what fields each Brick will return before creating a run.

Bearer token (API key)
Response 200
{
"kit_id": "uuid",
"kit_code": "A1B2C3D4",
"bricks": [
{
"brick_key": "pain_is_specific",
"fields": {
"value": true,
"confidence": true,
"reason": true,
"evidence": true
}
}, ...
]
}
GET/v1/kits/schema

Get Kit output schema by query

Alternative to the path-based schema endpoint. Look up a Kit schema by kit_code, kit_id, or kit_version_id query parameter.

Bearer token (API key)

Query parameters

kit_codestringThe 8-character Kit code.
kit_idstringThe Kit UUID.
kit_version_idstringA specific Kit version UUID.
Provide one of the three query parameters. Response shape is the same as GET /v1/kits/:kitId/schema.
GET/v1/bricks

Get Brick metadata

Retrieve metadata for one or more Bricks by their IDs. Useful for mapping brick keys to names and types.

Bearer token (API key)

Query parameters

idsstringrequiredComma-separated list of Brick IDs (max 100).
cURL
curl "https://api.semarize.com/v1/bricks?ids=uuid1,uuid2" \
-H "Authorization: Bearer smz_live_your_key"

Webhooks

Receive push notifications when runs reach terminal state instead of polling. Workspace-level, at-least-once delivery with HMAC-SHA256 signatures. v1 supports one endpoint per workspace.

POST/v1/webhooks

Create or update webhook

Register a webhook endpoint for the authenticated workspace. v1 supports one endpoint per workspace - calling this again replaces the existing endpoint (upsert).

Bearer token (API key)

Request body

urlstringrequiredHTTPS URL to receive webhook events. Must be public-routable.
cURL
curl -X POST https://api.semarize.com/v1/webhooks \
-H "Authorization: Bearer smz_live_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://yourapp.com/webhooks/semarize"}'
Response 201
{
"id": "wh_uuid",
"url": "https://yourapp.com/webhooks/semarize",
"secret": "whsec_...",
"created_at": "2026-02-24T12:00:00.000Z"
}
GET/v1/webhooks

List webhooks

List webhook endpoints for the authenticated workspace.

Bearer token (API key)
DELETE/v1/webhooks/:id

Delete webhook

Remove a webhook endpoint. Events will no longer be delivered to this URL.

Bearer token (API key)

Events and delivery

Semarize sends a POST request to your endpoint when a run reaches terminal state.

Terminal events

run.succeededRun completed successfully - output is available
run.failedRun failed - check error_code and error_message
run.cancelledRun was cancelled before completion

Signing headers

Every webhook delivery includes these headers for verification and deduplication:

Semarize-Event-IdUnique event ID. Stable across retries.
Semarize-Delivery-IdUnique per delivery attempt. Recommended for deduplication.
Semarize-Event-TypeEvent type (e.g. run.succeeded).
Semarize-TimestampUnix timestamp of the event.
Semarize-SignatureHMAC-SHA256 signature: v1=<hex>. Verify using your webhook secret.

Payload

The payload data field contains the same shape as GET /v1/runs/:runId. If the payload exceeds the size limit, Semarize sends a thin event with only run_id, status, error_code, and duration_ms - fetch full details via GET /v1/runs/:runId.

Retries

Delivery uses exponential backoff (1m, 2m, 4m, 8m, ...) capped at 1 hour. Up to 10 attempts within a 24-hour window. After that, the delivery is marked dead. Dedupe on Semarize-Delivery-Id (recommended) or Semarize-Event-Id.

Webhook payload example
{
"id": "evt_uuid",
"delivery_id": "dlv_uuid",
"type": "run.succeeded",
"created_at": "2026-02-24T12:05:00.000Z",
"workspace_id": "ws_uuid",
"data": {
"run_id": "uuid",
"status": "succeeded",
"run_type": "api",
"duration_ms": 1200,
"output": { ... }
}
}

Errors

The API uses standard HTTP status codes. Error responses include a structured body.

400
Bad RequestMissing or invalid parameters.
401
UnauthorizedMissing, invalid, or expired API key.
403
ForbiddenInsufficient permissions for this resource.
404
Not FoundResource does not exist or is not accessible.
409
ConflictDuplicate idempotency key with different parameters.
422
Unprocessable EntityValid JSON but invalid field values.
429
Too Many RequestsRate limit exceeded. Retry after the indicated interval.
500
Internal Server ErrorUnexpected error. Contact support if persistent.
Error response shape
// Flat error envelope
{
"error": "invalid_run_mode"
}

Next steps

Ready to integrate? Start with the quickstart guide or explore real-world examples.

QuickstartAutomationsSecurity