Data & usage

nvoken operates the runtime at nvoken.com. Your application does not run its workers, database, queues, migrations, or service health checks.

You still decide how long product conversations should live, which records need to be copied into your own system, and how model usage affects customer billing.

Inspect work from the dashboard

The App dashboard shows recent Invocations, Sessions, API keys, provider keys, and usage. Use it to answer the first practical questions: Was the turn accepted? Is it still running or waiting? Which model and provider key did it use? What did it write to the Session?

The API returns a request_id with errors. Keep it in application logs and support reports. Also log invocation_id, session_id, and tool_call_id when they are available. Those durable IDs are more useful than copying prompts or provider errors into logs.

Usage is evidence, not a billing ledger

Each Invocation reports normalized model usage and an estimated standard cost when nvoken knows the model's price. GET /v1/usage/daily groups durable evidence by UTC day, provider, and model. A stored provider key also has a usage read showing how many Invocations used it.

These values help with support and reconciliation. They are not a customer billing ledger. Session deletion removes the Invocation records underneath usage reports, so historical totals can shrink.

If your product charges for model use, write a settlement record in your own database keyed by invocation_id. Your billing history should not depend on a conversation remaining in nvoken forever.

Session retention

Sessions remain until you delete them unless you create one with an idle retention window. The window resets when work is admitted or settled, and it never expires a Session underneath an active turn.

Compaction is separate. It summarizes older context for future model calls but does not remove canonical messages from the Session transcript.

Deleting a Session

DELETE /v1/sessions/{session_id} erases the Session and its runtime subtree, including messages, Invocations, results, ToolCalls, checkpoints, and usage records tied to those Invocations.

Deletion can also stop active work without leaving a final cancellation record. If that record matters to your product, cancel the active Invocation, observe its terminal state, and then delete the Session.

Deletion from the live service does not imply immediate removal from every encrypted backup. Align any customer-facing deletion promise with nvoken's current service terms rather than inferring a deadline from the API response.

Secret lifetime

nvoken API keys are stored as verifiers. Their raw secret appears only when a key is issued or rotated.

Stored provider keys are encrypted. One-turn provider keys and protected MCP headers are also encrypted for recovery, then cleared after the Invocation settles. Revoking a provider key destroys its live secret material while retaining safe metadata needed to explain older Invocations.

Keep nvoken API keys in your backend secret manager. Do not put them in browser code, URLs, logs, prompts, tool results, or Session metadata.