zenture Developer Docs
Build against the public API with server-side tokens, generated route contracts, explicit async operation handling, and SDK helpers when direct HTTP is too low-level.
curl -sS "https://api.zenture.app/v1/helloworld"Base URL
Production endpoint for every public V1 request.
https://api.zenture.app/v1OpenAPI version
Published contract version used for these docs.
1.0.0-rc.3Quickstart
Start with the production base URL, token auth, and the first safe requests.
Production traffic uses one public V1 base URL:
Production base URL
Copy this endpoint for every public V1 request.
https://api.zenture.app/v1Use API-token routes only from trusted server-side code:
Mutating async routes require Idempotency-Key:
Chat Then Evaluate
POST /v1/chat creates or continues a zenture chat. Poll the returned operation_id with GET /v1/operations/{operation_id}. A succeeded single-model chat operation returns safe ids such as:
To continue the same chat, send the previous chat_id:
To evaluate that zenture chat answer, fetch the chat turn text and evaluate the AI-answer id. model_response_id is the answer id; it is not the user-message id. chat_id and turn_id are optional correlation fields, but if either is sent, model_response_id is required.
When the evaluation operation succeeds, poll GET /v1/evaluations/<EVALUATION_ID> for detailed results. Completed detail responses can include amount_billed, zenture_summary, zenture_suggestion, zenture_kpi_details, results, and sources. Source rows report statuses such as unavailable, plus fields such as httpStatus and verdict when available.
To evaluate an answer from your own app or another AI system, omit all zenture chat ids, including model_response_id. This creates an external evaluation-only record and does not add the message to normal chat history:
The committed OpenAPI artifact is the machine-readable contract. Generated artifacts under docs/generated/ are derived from it for later developer-docs consumption.
Authentication
Use server-side API tokens and keep credentials out of client code.
API-token routes use:
API tokens are server-side credentials only. Store them in a secret manager or protected server environment. Do not use them in browsers, mobile apps, client-side JavaScript, public repositories, logs, notebooks with shared output, or customer-visible error reports.
Create and manage user API tokens in the zenture app profile: <https://ai.zenture.app/profile?tab=api-tokens>.
Current auth modes:
none: public unauthenticated route, currentlyGET /v1/helloworld.api_token: personal API token presented withAuthorization: Bearer <ZENTURE_API_TOKEN>.
If a token is exposed, revoke it immediately and rotate any dependent automation to a new token.
API Token Policies
Expiry, rotation, revocation, and least-privilege scope expectations.
V1 supports personal user-bound tokens only. Tokens are scoped to the user who created them and are evaluated by backend-owned authorization and billing rules.
Policy summary:
- Default expiry: 90 days.
- Maximum expiry: 365 days.
- Maximum active tokens: 10 active tokens per user.
- Token secret display: one-time reveal at creation or rotation.
- Token names: encrypted at rest.
- Expiry reminder: 7-day expiry notification through the internal zenture notification system.
- Revocation: after revocation is accepted, the token cannot create new jobs, poll operations, or read billing/usage.
- Rotation: create or rotate to a new token, deploy the replacement secret server-side, then revoke the old token.
Use the smallest required scope set. Keep token names descriptive but non-sensitive; do not include customer data, prompts, access tokens, or incident details in names.
API token management is handled in the zenture web app profile. These public docs only cover unauthenticated checks and API-token server-to-server requests.
Endpoints
The public V1 route contract.
The request example shows the headers, query parameters, idempotency key, and JSON body shape expected by the route. The response example shows the successful body returned by the API, including async operation wrappers for work that must be polled.
The server remains authoritative for authentication, scopes, model availability, billing, rate limits, and validation. Use the response body as the integration shape, then handle public error envelopes and terminal operation statuses separately in client code.
/v1/chatCreates a new chat turn or continues an existing zenture chat through an async operation. Use it for server-side chat workflows where the API should return an operation id for polling instead of blocking on model work.
- Auth
- api_token
- Scopes
- chat:write
- Idempotency
- required
curl -sS "https://api.zenture.app/v1/chat" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>" \ -H "Idempotency-Key: <STABLE_UNIQUE_REQUEST_KEY>" \ -H "Content-Type: application/json" \ -d '{"message":"Summarize this support update.","mode":"single"}'Response 202
{ "error": null, "operation_id": "op_example", "result": null, "status": "queued"}/v1/chatsLists chats available to the API token. Use it to page through chat records before selecting a specific conversation or message history.
- Auth
- api_token
- Scopes
- chat:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/chats?limit=20" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "chats": [ { "chat_id": "chat_example", "created_at": null, "title": null, "updated_at": null } ], "next_cursor": null}/v1/chats/{chat_id}Returns metadata for a single chat. Use it to confirm the chat exists and inspect high-level state before fetching its messages.
- Auth
- api_token
- Scopes
- chat:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/chats/chat_example" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "chat": { "chat_id": "chat_example", "created_at": null, "title": null, "updated_at": null }, "latest_turns": [ { "created_at": null, "model_answer": "example", "model_response_id": null, "model_response_ids": [ "example" ], "turn_id": "turn_example", "user_message": "How should we respond?" } ]}/v1/chats/{chat_id}/messagesLists messages for a specific chat in chronological API form. Use it to retrieve turn content needed for follow-up prompts, audits, or evaluations.
- Auth
- api_token
- Scopes
- chat:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/chats/chat_example/messages" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "chat_id": "chat_example", "next_cursor": null, "turns": [ { "created_at": null, "model_answer": "example", "model_response_id": null, "model_response_ids": [ "example" ], "turn_id": "turn_example", "user_message": "How should we respond?" } ]}/v1/evaluateStarts an async evaluation for a zenture chat answer or an external answer supplied by your application. Use it when you need structured quality signals and should poll the returned operation until completion.
- Auth
- api_token
- Scopes
- evaluation:run
- Idempotency
- required
curl -sS "https://api.zenture.app/v1/evaluate" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>" \ -H "Idempotency-Key: <STABLE_UNIQUE_REQUEST_KEY>" \ -H "Content-Type: application/json" \ -d '{"ai_answer":"Offer a concise next step.","external_id":"case-123","user_message":"How should we respond?"}'Response 202
{ "error": null, "operation_id": "op_example", "result": null, "status": "queued"}/v1/evaluationsLists evaluation records available to the API token. Use it to browse completed or pending evaluations before loading full detail for a selected record.
- Auth
- api_token
- Scopes
- evaluation:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/evaluations?limit=20" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "evaluations": [ { "amount_billed": "example", "created_at": null, "evaluation_id": "eval_example", "results": null, "score": null, "sources": null, "status": "active", "zenture_kpi_details": null, "zenture_suggestion": null, "zenture_summary": null } ], "next_cursor": null}/v1/evaluations/{evaluation_id}Returns detailed results for a completed or in-progress evaluation. Use it to read summaries, suggestions, KPI details, result rows, and source status after an operation succeeds.
- Auth
- api_token
- Scopes
- evaluation:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/evaluations/eval_example" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "amount_billed": { "amount": "123.45", "unit": "credits" }, "created_at": null, "evaluation_id": "eval_example", "results": null, "score": null, "sources": null, "status": "active", "zenture_kpi_details": null, "zenture_suggestion": null, "zenture_summary": null}/v1/helloworldReturns a public health-style hello world response without authentication. Use it as the safest first request to verify networking, base URL selection, and client setup.
- Auth
- none
- Scopes
- none
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/helloworld"Response 200
# zenture Public API Base URL: `https://api.zenture.app/v1` Developer docs: `https://www.zenture.app/developers` Python SDK: [zenture95/zenture-sdk](https://github.com/zenture95/zenture-sdk)/v1/input-wizardStarts an async input-wizard run for transforming rough notes into a structured prompt or answer input. Use it when your integration needs zenture to prepare user-facing input before a chat or evaluation workflow.
- Auth
- api_token
- Scopes
- input_wizard:run
- Idempotency
- required
curl -sS "https://api.zenture.app/v1/input-wizard" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>" \ -H "Idempotency-Key: <STABLE_UNIQUE_REQUEST_KEY>" \ -H "Content-Type: application/json" \ -d '{"mode":"prompt_improvement","prompt":"Draft a customer-facing answer from these notes."}'Response 202
{ "error": null, "operation_id": "op_example", "result": null, "status": "queued"}/v1/limitsReturns rate-limit information for the current API token. Use it to inspect quota windows and adapt polling or request pacing before hitting enforced limits.
- Auth
- api_token
- Scopes
- rate_limits:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/limits" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "operation_statuses": [ "example" ], "routes": {}}/v1/modelsLists public models available to the API token and selected mode. Use it to choose backend-authoritative model ids instead of guessing provider names in client code.
- Auth
- api_token
- Scopes
- models:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/models?mode=single" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "models": [ { "capabilities": [ "chat" ], "cost_class": "standard", "display_name": "Public Single", "id": "model_public_single", "is_available": true, "is_default": true, "max_input_tokens": 8192, "modes": [ "single" ], "provider_display_name": "Example Provider" } ]}/v1/operations/{operation_id}Returns the current state and result payload for an async operation. Use it to poll chat, evaluation, and input-wizard work until the status reaches a terminal state.
- Auth
- api_token
- Scopes
- none
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/operations/op_example" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "error": null, "operation_id": "op_example", "result": null, "status": "succeeded"}/v1/usageReturns usage information for the API token or selected API scope. Use it to display consumption, reconcile automation costs, and detect unusual activity.
- Auth
- api_token
- Scopes
- usage:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/usage?scope=api" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "operation_count": 1, "scope": "api"}/v1/walletReturns wallet and credit information associated with the API token context. Use it to check whether an integration has enough balance before starting billable async work.
- Auth
- api_token
- Scopes
- wallet:read
- Idempotency
- not required
curl -sS "https://api.zenture.app/v1/wallet" \ -H "Authorization: Bearer <ZENTURE_API_TOKEN>"Response 200
{ "credits_available": { "amount": "123.45", "unit": "credits" }, "current_period_end": null, "plan": "free", "status": "active"}Errors
Stable public error envelopes and retry guidance.
Error responses use a stable public envelope:
Do not parse internal exception text. Use error.code, HTTP status, and documented headers.
| Code | Retry | Recommended client action |
|---|---|---|
unauthorized | No | Check Authorization: Bearer <ZENTURE_API_TOKEN>, token expiry, and revocation state. |
forbidden | No | Request the missing scope or use a token with least-privilege access to the route. |
rate_limited | Yes | Retry after Retry-After; also honor RateLimit-Reset. |
validation_failed | No | Fix request shape, path ids, headers, or body size before retrying. |
missing_idempotency_key | No | Send an Idempotency-Key header for mutating async routes. |
insufficient_credits | No | Add credits or change wallet plan before starting paid AI operations. |
dependency_unavailable | Yes | Retry with backoff; the backend dependency is unavailable. |
capacity_unavailable | Yes | Retry with backoff or reduce request rate. |
internal_error | Yes | Retry with backoff; include request_id when contacting support. |
idempotency_conflict | No | Reuse the same body for the same key or create a new Idempotency-Key. |
operation_expired | No | Create a new operation; polling TTL has elapsed. |
Current documented error statuses include 400, 401, 402, 403, 413, 422, 429, 431, and 503.
Rate Limits
Headers, reset semantics, and polling discipline.
Rate limits are applied by route policy and cost class. Current cost classes are free_public, polling_read, and expensive_mutation.
Successful public responses include:
RateLimit-LimitRateLimit-RemainingRateLimit-Reset
When the limit is exceeded, the API returns 429 with error.code rate_limited and:
Retry-AfterRateLimit-LimitRateLimit-RemainingRateLimit-ResetX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset
RateLimit-Reset is seconds until reset. Legacy X-RateLimit-Reset is retained for compatibility.
Polling discipline:
- Poll
GET /v1/operations/{operation_id}with backoff. - Slow down as
RateLimit-Remainingapproaches zero. - On
429, wait at leastRetry-Afterseconds. - Do not run tight polling loops.
Async Operations
Create async work, poll operations, and stop on terminal statuses.
Mutating async routes return operation objects instead of final domain results. Current async mutation routes are:
/v1/chat/v1/evaluate/v1/input-wizardPoll the operation with:
Operation polling is token-bound. A token can poll operations created for that token; another token must not assume access to the same operation id.
Polling TTL is 24 hours. After expiry, the public API returns operation_expired.
Statuses:
queued: accepted but not started.running: accepted and in progress.succeeded: terminal success; inspect the safe result projection.failed: terminal failure; inspecterror.code.cancelled: terminal cancellation.expired: terminal expiry.
Client behavior:
- Poll with backoff.
- Honor
Retry-AfterandRateLimit-Resetwhen rate limited. - Stop polling on terminal statuses.
- Do not treat
runningas success. - Do not send prompts, model answers, provider payloads, or tokens in operation ids or idempotency keys.
Completed chat and evaluation operation results include amount_billed when the billing ledger debit is available. The value is a user-facing zenture credit amount, for example {"amount":"4.41","unit":"credits"}; internal ledger subunit names are not exposed.
Operation endpoint:
GET /v1/operations/{operation_id}uses auth modeapi_token.
Evaluation operations:
POST /v1/evaluaterequiresuser_messageandai_answer.- New external evaluations may include
external_idand boundedmetadatafor safe caller correlation. - External evaluations must omit
chat_id,turn_id, andmodel_response_id. - Internal zenture chat-answer evaluations must include the AI-answer
model_response_id. chat_idandturn_idare optional internal correlation fields, but if either is supplied,model_response_idis required.- Invalid internal targets return
422 validation_failedbefore an operation is created or credits are checked. - To evaluate a zenture chat answer, create or continue a chat, poll the chat operation, keep the returned
chat_id,turn_id, and AI-answermodel_response_id, then send those ids with the sameuser_messageandai_answertext toPOST /v1/evaluate. - To evaluate an answer produced outside zenture, omit
chat_id,turn_id, andmodel_response_id; the evaluation is stored as an external evaluation-only record and does not appear in chat history. - Use
GET /v1/evaluations/{evaluation_id}after completion for detailed evaluation fields:zenture_summary,zenture_suggestion,zenture_kpi_details,results, andsources. sourcesis grouped by model. Source rows can includestatus/retrievalStatusvalues such asavailable,limited,unavailable, andunverified, plushttpStatus,verdict,url,hostname,securityLabel,accessibilityScore, andresponseTimeMswhen available.
Internal zenture chat-answer evaluation:
External answer evaluation:
Local smoke includes an explicit POST /v1/evaluate check only when ZENTURE_SMOKE_ENABLE_EVALUATE=true is set, because live evaluation scheduling can create billable evaluation usage.
SDK
Use the Python SDK when you want typed client helpers instead of direct HTTP calls.
The zenture SDK wraps the same public V1 contract shown here for server-side integrations. Use the GitHub repository for installation details, typed helper APIs, release notes, and implementation guidance that stays close to the SDK source.
SDK