REST API version

The public REST API is versioned in the URL path. Current public endpoints live under /v1 on https://api.semarize.com. The path version is the compatibility boundary for external clients.

The OpenAPI info.version identifies the document version, not a replacement for the /v1 path contract.

Public base URL

https://api.semarize.com/v1

Compatibility rules

Clients should ignore unknown response fields because additive fields can appear without a path-version change.
Documented fields under the public /v1 surface are the client contract.
Do not rely on hidden internal app, admin, billing, knowledge base, MCP, or Stripe webhook routes.
Do not rely on internal Kit composition, prompt text, retrieval chunks, or hidden execution context.

Kit versions

API versioning and Kit versioning solve different problems. /v1 describes the REST shape. kit_version_id pins which Kit version should execute or be inspected for one request.

Identifier	Use
kit_code	Stable published Kit lookup for most production integrations.
kit_id	Workspace-scoped Kit lookup when your system stores Semarize IDs.
kit_version_id	Pin a specific Kit version for a rollout, validation, or integration test.

OpenAPI updates

The OpenAPI document is the machine-readable description of the public API surface. Agents, SDK generators, and integration tests should fetch /openapi.json and compare only documented public paths and schemas.

Use operationId values for generated client names when your tooling supports them.
Use documented examples as examples, not as a complete list of possible response fields.
Validate important integration paths against POST /v1/test before running production conversations.

Deprecations

Semarize avoids removing or changing documented public /v1 behavior without updating developer documentation. Additive fields and documentation clarifications can ship without breaking clients.

The safest client strategy is strict request validation on your side and tolerant response parsing on Semarize responses.

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.

Status

Use status signals, incident retry behavior, and escalation details in production.

Versioning