# Operations and trust — the concept Vectros is the secure data, document, search, and AI back-end that applications are built on. Once your application is in production, three operational concerns move to the foreground: **knowing what happened** (webhooks and the activity log), **knowing what it costs** (usage and billing), and **being able to take data back out or tear it down** (teardown and erasure). This area covers those concerns and the trust posture that underpins them. The companion document, [compliance.md](compliance.md), goes deeper on the trust story — the way sensitive data is handled, how history is retained, how tenants are isolated, and an honest account of what the platform does *not* yet do. This page is the mental model; the [how-to guide](how-to.md) shows the runnable calls; the [reference](reference.md) is the exhaustive field-and-limit catalog. ## The shape of the operational surface Everything in this area is reached through the **developer portal API** (`/developer/*`, the self-serve console surface) or the **partner API** (`/v1/*`, the application data plane). The Node SDK groups these calls under sub-clients by area — `client.auth.getUsage()`, `client.auth.getAdminLogs()` — and the developer portal exposes the same operations through a console UI for the human-in-the-loop cases (signing the agreement, registering a webhook, watching usage). Three pillars: - **Webhooks** let your application *react* to events that happen inside Vectros — asynchronously, after the fact, without polling. When a document finishes indexing or a record write completes, Vectros signs and POSTs a small envelope to an HTTPS endpoint you control. - **Usage and billing** give you a single, reconcilable view of what your account has consumed in the current period: a monthly credit allowance for the data plane and a separate pre-paid balance for inference. - **Teardown and erasure** are about removing data. Per-customer and per-context hard-delete is a first-class, implemented operation. End-subject right-to-erasure — the controller-driven "erase everything about this one person" workflow — is a reserved contract, not yet a live engine; the distinction matters and is drawn explicitly below. ## Webhooks: events, not polling A webhook in Vectros is a **registered HTTPS endpoint plus a list of event types you care about**. When something of interest happens, Vectros builds a small JSON envelope, signs it, and delivers it to your endpoint with at-least-once semantics and a bounded retry schedule. The events available today are tied to the asynchronous indexing pipeline — the moment a document or record finishes (or fails) indexing: - `document.indexed` / `document.failed` - `record.indexed` / `record.failed` That is deliberately a narrow, honest surface: webhooks fire when the platform finishes the asynchronous work that your synchronous API call kicked off. Indexing is the work that happens *after* `200 OK` — embedding a document, building its search representation — so a webhook is how your application learns "that document you ingested two seconds ago is now searchable" without polling. Three design choices define the webhook trust model, and each exists for a reason: 1. **Endpoints must live under a verified domain.** You cannot register a webhook URL whose hostname you have not proven you control. This closes the door on a malicious or careless registration pointing event traffic — which can carry identifiers — at an endpoint the registrant does not own. 2. **Every delivery is signed.** Each POST carries an HMAC-SHA256 signature over a current timestamp and the body. Your receiver recomputes the signature with the shared secret and rejects anything that does not match, or whose timestamp is stale. This is how you know a delivery genuinely came from Vectros and was not replayed. 3. **Delivery targets are re-validated at send time.** Even though the domain was verified at registration, the destination IP is re-resolved and re-checked immediately before every POST, so a DNS record that is flipped to an internal address after registration is caught before any bytes leave. This is the anti-SSRF gate, and it is the *real* security boundary — registration-time checks exist mostly to give you fast feedback on a bad URL. Webhook registrations are **per environment**: your live tenant and your test tenant carry separate registrations, so you can route test-mode events to a staging receiver and live-mode events to production. The envelope itself carries a `livemode` flag so a single receiver can tell them apart if you prefer to consolidate. If your endpoint keeps failing, Vectros retries on a widening backoff and, after a run of consecutive failures, **auto-disables** the registration so a dead endpoint does not accumulate an unbounded retry backlog. You re-enable it explicitly once you have fixed the receiver, which also resets the failure counter. ## Usage and billing: two axes, one report Vectros meters usage on **two independent axes**, and a single usage report shows both: - **A monthly credit allowance** covers data-plane work — record writes, document ingests, and searches. It resets each calendar month. The report tells you how much of the period's allowance you have consumed. - **A pre-paid inference balance** covers AI calls (chat, RAG, and document-ask). It is a ledger, denominated in cents, that draws down as you make inference calls and is topped up out of band. It does not reset monthly the way the credit allowance does. Keeping these separate is intentional: data-plane work and model inference have very different cost structures, and conflating them into one number would make neither legible. The usage report keeps them in distinct sections so you can reason about each. The report is also **broken down per environment**. Your partner-level totals are the sum of your live tenant and your test tenant, each reported separately — so you can see what production is costing versus what your test traffic is costing, and the two reconcile up to the partner total. A subtle but important property: **reads are free of the per-tenant business rate limit and do not draw down the monthly credit allowance** — only writes and searches count against it. Metering is keyed at the partner and tenant level and ticks as operations dispatch, so the counts you read are near-real-time, eventually consistent with in-flight settlement. Access to the usage report is itself scoped. A token needs the `billing:r` permission to read it; a token without that permission is rejected. This means you can hand a read-only billing view to an internal dashboard without granting it any data access. ## Teardown and erasure: two different operations This is the distinction the rest of the platform's trust story rests on, so it gets stated plainly. **Per-customer / per-context hard-delete is implemented and is a real operation.** When you delete a context (the isolation boundary that holds one customer's or one application's records, documents, folders, and schemas), the platform runs an owner-filtered cascade that removes the data under that boundary. Tenant-level teardown — decommissioning an entire test or live tenant — is likewise a first-class lifecycle operation. If you need to remove *a whole customer's footprint* because they have offboarded, this is the mechanism, and it works today. **End-subject right-to-erasure is a separate thing, and its engine is not yet live.** The "erase everything about this one individual across all the contexts they appear in" workflow — the data-controller obligation under privacy regimes — has a **reserved API contract** but no execution engine behind it yet. The request and response shapes are frozen so that applications integrating against the SDK get a stable contract that will not break when the engine ships, but calling the endpoint today returns a "not implemented" response. It also requires your root account credential, never a scoped one, because erasure is an irreversible, account-wide operation. Do not conflate the two. "We can delete a customer's context" is true and shippable. "We offer turnkey per-individual erasure" is not yet true, and this documentation will not claim it until the engine lands. ## How this fits the rest of the platform The operational surface sits on top of the same isolation and access primitives the data plane uses. Webhook registrations, usage records, and teardown are all **tenant-scoped**: there is no request shape that lets you read another tenant's deliveries, another tenant's usage, or trigger another tenant's teardown. The activity log derives the tenant from your credential, not from a request parameter — there is simply no input channel to point it at someone else's tenant. The deeper trust mechanisms — how sensitive fields are destroyed before they are persisted, how audit and version history are retained, how the edge is hardened — are the subject of [compliance.md](compliance.md). Read that next if you are evaluating Vectros for a regulated workload. ## Where to go next - [how-to.md](how-to.md) — register and verify a webhook against a synthetic endpoint, and read your usage report, with runnable calls. - [reference.md](reference.md) — the exhaustive field, limit, envelope, and error catalog for webhooks, usage, the activity log, and teardown. - [compliance.md](compliance.md) — the full trust posture: the three sensitive-data mechanisms, audit and version retention, tenant isolation, edge security, and an honest list of what is reserved or not covered.