Operations and trust — reference

The exhaustive catalog for the operational surface: webhook configuration and delivery, the event envelope, the usage report, the activity log, and teardown. For the conceptual model see explanation.md; for runnable recipes see how-to.md. For the raw endpoint/parameter listing, see the generated API reference (the OpenAPI/Scalar spec) — this page documents behavior, fields, limits, and limitations, not the wire schema.


Webhooks

Configuration object

A webhook registration is per environment (live and test tenants are registered separately). Fields, as returned by the developer-portal webhook endpoints:

FieldTypeNotes
idstringThe webhook configuration id.
urlstringFull HTTPS endpoint. Must use https://; plain HTTP is rejected.
domainstringHostname extracted from url, stored for the delivery-time check.
eventsstring[]Subscribed event types. Must be non-empty.
statusstringACTIVE or DISABLED.
disabledReasonstring | nullconsecutive_failures, manual, ssrf_blocked, or domain_unverified when disabled. domain_unverified means the webhook's domain is no longer verified for your account; re-verify the domain, then re-enable the webhook.
consecutiveFailuresintRunning count of consecutive delivery failures; reset to 0 on any success or on re-enable.
apiVersionstringPayload format version. Defaults to 2024-01.
tenantIdstringThe tenant (live or test) the registration belongs to.
createdAtnumberCreation timestamp (epoch millis).
secretstringReturned only in the create response. 64-char hex (32 random bytes). Never returned by GET/list.

Operations

OperationMethod / pathNotes
RegisterPOST /developer/webhooks201; returns the secret once.
Get oneGET /developer/webhooks/{id}200; secret omitted.
ListGET /developer/webhooks?tenantId=...200; tenantId query param required; secret omitted.
UpdatePUT /developer/webhooks/{id}Change url, events, apiVersion, or status.
DeleteDELETE /developer/webhooks/{id}204. There is no in-place secret rotation — delete and re-create.
List deliveriesGET /developer/webhooks/{id}/deliveries200; delivery records, payload bodies omitted.
Retry a deliveryPOST /developer/webhooks/{id}/deliveries/{deliveryId}/retryRe-queues a FAILED delivery.

Registration validation rules

Enforced at POST (and re-run on PUT when the URL changes):

  • url is required and must start with https://.
  • events must be present and non-empty.
  • tenantId is required and must be one of your own tenants (live or test) — otherwise 403.
  • The URL hostname must resolve, and every resolved IP must be publicly routable. A hostname resolving to any private, loopback, link-local, any-local, multicast, CGNAT, IPv6 unique-local-address or special-purpose range (listed under the delivery-time gate below) is rejected with 400. This includes the cloud metadata address.
  • The hostname's domain must be verified for your account, or the registration is rejected with 403.

The delivery-time SSRF gate

The registration-time DNS check is defense-in-depth and fast feedback; the real security boundary is re-validation at delivery. Immediately before each POST, the destination hostname is re-resolved and every resolved IP must pass the same public-routability predicate. The predicate rejects:

  • Loopback (127.0.0.0/8, ::1)
  • IPv4 private ranges (RFC 1918 site-local)
  • Link-local (169.254.0.0/16, fe80::/10) — including the cloud metadata IP
  • Any-local and the 0.0.0.0/8 "this network" block
  • Multicast
  • CGNAT 100.64.0.0/10 (RFC 6598)
  • IPv6 unique-local fc00::/7 (RFC 4193)
  • Other special-purpose blocks that are never a public destination: IPv4 192.0.0.0/24, the three documentation TEST-NET blocks, 192.88.99.0/24, 198.18.0.0/15 and the reserved 240.0.0.0/4; IPv6 NAT64 (64:ff9b::/96, 64:ff9b:1::/48), 6to4 2002::/16, Teredo 2001::/32, the documentation blocks 2001:db8::/32 and 3fff::/20, 2001:2::/48, the ORCHID blocks 2001:10::/28 and 2001:20::/28, 5f00::/16, 100::/64 and the IPv4-translated ::ffff:0:0:0/96. NAT64, 6to4, Teredo and IPv4-translated addresses are refused whole, whatever IPv4 address they carry.
  • IPv4-mapped/compatible IPv6 forms are unwrapped to their IPv4 address first, so a private IPv4 cannot hide inside an IPv6 wrapper.

The connection is then made to exactly the addresses that passed this check, with no second lookup of the hostname between the check and the connect, so a name that answers differently the second time cannot redirect the delivery. TLS server-name indication and certificate verification still use your hostname.

If delivery-time resolution returns a non-public IP, the delivery is failed and the webhook is auto-disabled with disabledReason = ssrf_blocked — a DNS-rebinding attempt takes the registration offline rather than merely dropping one delivery. A null or unresolvable address fails closed (treated as non-public). The same predicate guards domain registration, the endpoint of a provider config and the fetch of an issuer's key set.

The event envelope

The body delivered to your endpoint:

KeyTypeNotes
idstringUnique delivery id; also sent as the X-Vectros-Delivery header.
versionstringEnvelope version, currently 2024-01.
typestringThe event type (see below).
creatednumberUnix seconds at envelope build time.
tenantIdstringThe tenant the event belongs to.
livemodebooleantrue for the live tenant, false for test.
dataobjectEvent-type-specific fields.

data for document.* events: id (document id), status, indexMode, and optionally userId, scopes, folderId when present. The document title is intentionally excluded — it is the filename, a top-level (non-typed) value that the field-masking machinery does not cover, so it is never egressed in an envelope. Retrieve the title via GET /v1/documents/{id}, where reveal-scope and tenant/scope enforcement apply.

data for record.* events: id (record id), typeName, indexStatus, and optionally userId, scopes when present (scopes is the same <namespace>:<value> array as the REST response — org:.../client:... or a namespace you registered).

indexFailure on document.failed / record.failed: both event types carry an indexFailure object explaining the failure — whenever the platform recorded a classification — so you can act on the event itself rather than calling back to find out why. It is omitted when no reason was recorded, so treat it as optional. It has a stable code and a human-readable message:

codeMeaning
SOURCE_UNAVAILABLEThe underlying item could not be loaded and may have been deleted.
TEXT_INDEX_FAILEDKeyword indexing failed; the content may still be findable by semantic search.
EMBEDDING_FAILEDSemantic indexing failed; the content may still be findable by keyword search.
INDEXING_FAILEDNo index leg is serving this content, so it is not findable by search at all.
VECTOR_LIMIT_EXCEEDEDYour vector storage limit was reached, so semantic indexing was skipped; keyword search is still serving this content.
INTERNALAn error on our side; retry, and contact support if it persists.

Branch on code — message wording may change between releases. The object is present only on failure events; success deliveries omit it entirely.

LOCATION_NOT_INDEXED on an indexed item. A record or document response (for example GET /v1/records/{id} or GET /v1/documents/{id}) also carries indexFailure with code LOCATION_NOT_INDEXED when indexStatus is INDEXED but a value in one of its geo fields is not a valid point: the item was indexed without that location, so it is not found by distance search ($near), while every other search still finds it. Write a valid {"lat": ..., "lon": ...} to clear it. This code never appears with FAILED and is not sent on webhook deliveries, so do not treat the mere presence of indexFailure as a failure: check indexStatus.

The per-tenant semantic (vector) capacity limit is 5,000,000 vectors by default — well above what the overwhelming majority of use cases need. It is a per-tenant limit, not shared across customers, and it can be raised for larger use cases (contact us). Past it, new content still gets keyword-indexed and stays findable via TEXT/HYBRID search; only its semantic indexing is skipped (VECTOR_LIMIT_EXCEEDED above).

The webhook data field names match the public REST API surface exactly — typeName and userId are the same keys the REST request/response uses, so a consumer can share models across both surfaces without remapping.

Event types:

EventFires when
document.indexedA document finishes indexing successfully.
document.failedA document fails indexing.
record.indexedA record finishes indexing successfully.
record.failedA record fails indexing.
trigger.failedAn async trigger execution fails terminally — the platform has stopped retrying it. Not per attempt: a retryable failure that later succeeds sends nothing. The payload mirrors a GET /v1/trigger-failures record.

Adding new fields to data is a non-breaking, no-version-bump change; removing or renaming a field would require a version bump. Pin apiVersion on the registration if you need the envelope structure frozen.

Delivery headers

HeaderValue
Content-Typeapplication/json
X-Vectros-DeliveryThe delivery id.
X-Vectros-TimestampUnix seconds at signing time.
X-Vectros-Signaturesha256=<hex> — HMAC-SHA256 of "<timestamp>.<body>" keyed by the hex-decoded secret.

Signing and verification contract

  • The signature is computed over the literal string <timestamp>.<body>, where <body> is the exact bytes of the JSON payload and <timestamp> is the value in the X-Vectros-Timestamp header.
  • The secret is hex; decode it to its 32 raw bytes before using it as the HMAC key.
  • The signature is recomputed fresh on every attempt (including retries) so the timestamp is always current. Receivers should reject a delivery whose timestamp is more than 300 seconds from now — this is the replay window.
  • Use a constant-time comparison when checking the signature.

Delivery, retry, and auto-disable

  • Delivery is at-least-once. Your receiver must be idempotent — dedupe on the delivery id.
  • The HTTP POST uses a 5-second connect timeout and a 30-second response timeout. A 2xx response marks the delivery DELIVERED; anything else (non-2xx, timeout, connection error) is a failure. A redirect (3xx) is reported as a failure and is not followed.
  • Retry backoff after the first attempt fails: 30s → 5m → 30m → 2h → 8h. After the fifth retry delay is exhausted the delivery is marked FAILED and not retried automatically (you can re-drive it manually).
  • Each consecutive failure increments the webhook's consecutiveFailures; a success resets it to 0. At 10 consecutive failures the webhook is auto-disabled with disabledReason = consecutive_failures. Re-enable via PUT {"status":"ACTIVE"}, which resets the counter.
  • A webhook is also disabled, with disabledReason = domain_unverified, when its domain loses verification (a periodic re-verification of the domain keeps failing, or the delivery-time check finds the domain unverified). Re-verify the domain first; a re-enable (PUT {"status":"ACTIVE"}) requires the domain to be currently verified and returns 403 otherwise, whatever the original disabledReason was.
  • Delivery records have a 7-day TTL while unresolved. Once a delivery reaches DELIVERED it switches to a 30-day retention window instead — long enough to review in the portal, but no longer retained indefinitely. A tenant teardown deletes delivery rows explicitly (they may carry event identifiers) rather than waiting on either TTL.

Delivery record fields (history view)

GET /developer/webhooks/{id}/deliveries returns a paginated envelope: {"data": [...], "nextCursor": "..."}. Each entry in data carries: id, webhookId, eventType, sourceId, sourceType, status (PENDING / DELIVERED / FAILED), attempts, nextRetryAt, createdAt, newest first. limit caps the page size (default 50, max 200); pass a previous page's nextCursor back as the startFrom query parameter to continue — treat the cursor as opaque, and null means there is no further page. The envelope payload is never returned by this endpoint — it may carry identifiers.

Notes & limits — webhooks

  • Events are limited to the five listed above — the four indexing events, plus trigger.failed for a terminally failed async trigger execution. There is no webhook for synchronous CRUD operations, deletes, search, inference, identity, or billing.
  • Registration is per environment; there is no account-wide registration spanning live and test.
  • No in-place secret rotation — delete and re-create to roll the secret.
  • No payload customization, header injection, or per-event endpoint routing — one registration receives all of its subscribed event types at one URL.
  • Manual retry only applies to deliveries in FAILED status.

Response versioning (Vectros-Version)

Any request to /v1/* may carry a Vectros-Version request header that pins the shape of the response you get back — field names, the envelope, pagination shape, enum values, and error-body structure. It never changes behavior: authorization, tenant isolation, quota enforcement, and security fixes are identical no matter which version you send.

  • Sending nothing changes nothing. An unversioned request is served exactly as it is today. Adopting the header is entirely opt-in.
  • Responses echo Vectros-Version, so you can confirm which shape you were actually served.
  • 2026-08-01 is the only published version today — it describes the API exactly as it behaves right now. A version remains supported for 12 months after a successor is published; once deprecated, responses served under it carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers ahead of its retirement.
  • An unpublished or expired version is a 400, with errorCode: "UNSUPPORTED_WIRE_VERSION" (see Activity log below — this is the code you'll see there if a client sends a bad value) and a message naming the versions currently supported.
  • The SDKs do not send this header. With no header, resolution falls back to the calling credential's own wire_version_pin — stamped onto it at mint time from your tenant's setting at that moment, not read fresh from your account on every call — and only then to the platform floor. A call made through the Node SDK therefore resolves through that fallback rather than pinning a version explicitly. If you need to pin a shape today, set the header yourself on a direct HTTP call.
  • Some surfaces ignore it. The streaming POST /v1/rag, POST /v1/chat and POST /v1/runs endpoints, and the POST /v1/documents/{id}/ask sub-resource, ignore Vectros-Version and always serve the current shape — note that this is narrower than "all of documents": ingesting and managing documents through the rest of /v1/documents does honor the header, it's specifically the ask sub-resource that doesn't.
  • This is a different axis from two other things this page mentions "version" about: the webhook envelope's own apiVersion (above, under Configuration object) versions the webhook payload shape on a per-registration basis, and your SDK's package version moves on any API-surface change — including purely additive ones. Upgrading your SDK does not change the response shape you're served; Vectros-Version does, and only when an existing response shape changes in a breaking way.

Usage and billing

getUsage — the report

client.auth.getUsage() (GET /v1/usage). Not enveloped — returns the report object directly. Requires billing:r on a scoped token (a root key always passes). With no arguments returns the current calendar period; { year, month } selects a specific period.

A token confined to a single app context sees only that context's usage. The top-level totals — credits, search, documents, records, identity, inference, readAccess, and tenants — narrow to your context alone, and the environment (tenants.live/tenants.test) your context is not bound to reads null rather than the other environment's real totals. Only a token with cross-context reach (a root key, or a scoped credential with the cross-context wildcard) sees your full account-wide totals; for it, contextId continues to work as a display-only filter on the contexts breakdown, and your top-level totals are unaffected by it. If your integration reads top-level usage totals from a context-confined token, those numbers now reflect only that context — read contexts[] for the full picture, or use a credential with cross-context reach.

execution narrows like the other per-context charge fields — a token confined to a single app context sees only that context's executions. Like every other top-level section it is not filtered by the contextId query parameter, which stays a display-only filter on contexts. One caveat specific to it: its credits carry sub-credit remainders forward across your whole account for the period, so for a confined credential compare execution.creditsMilli against your account-wide figure rather than recomputing it from that one context's billableMillis.

Two narrower exceptions — do not read this as "everything narrows": reads.calls.used and reads.dataOut.bytes (the raw call-count and egress-byte counters) have no per-context breakdown to narrow to at all — they're metered per account, not per context — so a context-confined token sees 0 for both rather than a narrowed figure. Don't read reads.calls.used == 0 as "this credential made no calls this period"; it means "this dimension isn't visible at context granularity." The corresponding charge fields (reads.calls.overageCredits, reads.dataOut.overageCredits) do narrow correctly, since overage is charged per context. Separately, credits.limit continues to reflect your whole plan's ceiling regardless of confinement — only credits.used/credits.remaining narrow, so credits.remaining may overstate a context-confined credential's true remaining room.

FieldTypeNotes
periodstringYYYY-MM.
credits.usednumberCredits consumed this period, rounded down to whole credits.
credits.usedMillinumberExact consumption in milli-credits (1 credit = 1000 milli-credits; use this for reconciliation).
credits.limitnumber?The period allowance, when applicable.
credits.admissionLimitnumber?The credit level at which requests stop this period: limit plus what your overage budget or agreement allows, or limit without overage. Null when the account has no monthly limit; not reported to a token confined to some app contexts.
credits.includedCreditsnumber?The credits included in the period's price; usage above it is overage. Equals limit unless an overage agreement sets another amount. Null when the account has no monthly limit; not reported to a token confined to some app contexts.
credits.overagenumber?Overage credits for the period, as billed so far; zero without overage. Not reported to a token confined to some app contexts.
search.queries.text.countnumberTEXT searches this period.
search.queries.semantic.countnumberSEMANTIC searches this period.
search.queries.hybrid.countnumberHYBRID searches this period.
documents.ingest.text.countnumber?Inline-text document ingests.
documents.ingest.file.countnumber?File-upload document ingests.
records.writes.countnumber?Record writes this period.
records.writes.indexCountnumber?Logical index credits maintained (ownership + externalId + schema lookups; an equality index counts 1, a range-enabled index 3).
inference.balanceCentsMillinumberPre-paid inference balance, an integer in milli-cents (thousandths of a cent; 1 cent = 1000). It can go below zero when a settled call costs more than the amount held for it.
inference.endpoints.chat.callsnumberChat calls this period.
inference.endpoints.rag.callsnumberRAG calls this period.
inference.endpoints.ask.callsnumberDocument-ask calls this period.
inference.endpoints.<chat|rag|ask>.inputTokens / .outputTokensnumberInput and output tokens across that endpoint's calls this period.
inference.endpoints.<chat|rag|ask>.cacheReadTokens / .cacheCreateTokensnumberInput tokens the model provider served from, or wrote to, its prompt cache this period (0 when none). They are counted apart from inputTokens, which they do not add to. The platform does not ask the provider to cache on these endpoints, so they are non-zero only when a provider caches on its own (for example a model reached through a providerAlias). inference.totals carries the same counts across all three endpoints.
identity.users / identity.entitiesobjectWrite + storage activity for the two identity surfaces (users, and identity entities across every namespace). Reported as an account-level rollup, not narrowed per-namespace.
readAccess.storageBytes / readAccess.rowsobject / number?PHI read-access-log storage and logged-read count. Present only when read-access logging is enabled on a schema or context.
reads.calls.used / reads.dataOut.bytesnumberThe per-call and data-out (egress) read-metering axes — see the context-narrowing note above for the two exceptions.
credits.breakdown.scriptExecutionnumberCredits consumed by script execution time (trigger firings and POST /v1/scripts/execute alike) beyond the allowance your billable operations earned. Present alongside the other credits.breakdown categories; scriptExecutionMilli is the exact figure.
execution.executionsnumberTrigger-script executions metered this period. Counts every execution that ran your script, including those that ended in an error and those that owed no charge; excludes firings refused before your script ran, which are never metered.
execution.totalMillisnumberTotal measured wall-clock time across those executions.
execution.includedMillisnumberExecution time included at no charge and actually applied this period. The allowance CONSUMED, not the allowance earned — an execution that finished well inside its included time contributes only what it used, and an execution we do not charge for at all (an internal platform error, say) has its whole duration absorbed here. Both are what make the arithmetic below exact.
execution.billableMillisnumberThe portion actually charged, after the per-execution platform baseline and the included time above.
execution.credits / execution.creditsMillinumberCredits charged for execution time. The milli figure is exact; a small charge usually rounds to 0 whole credits.
tenants.liveobjectSame shape (credits / search / inference) scoped to the live tenant. null if your token is confined to a context in the test environment.
tenants.testobjectSame shape scoped to the test tenant. null if your token is confined to a context in the live environment.
contextsarrayPer-app-context breakdown, one entry per context with activity. Filtered to a single context when ?contextId= is supplied on a cross-context-reach token.

The two-axis model

  • Monthly credit allowance — covers data-plane work (record writes, document ingests, searches, read and data-out overage, script execution time (trigger and synchronous), and the platform fees of inference calls and agent runs), resets each calendar month, reported by credits.
  • Pre-paid inference balance — covers chat / RAG / document-ask and the model calls of agent runs, denominated in milli-cents (thousandths of a cent), drawn down by the exact cost of each inference call and topped up out of band, reported by inference.balanceCentsMilli. A call you route to your own model provider (providerAlias) is billed to you by that provider and does not draw down this balance.
  • The balance is held before the model is called. A balance-billed call first reserves its estimated maximum cost from the balance, then settles to the actual cost when the call ends and refunds the unused part; a call that fails on the platform's side before delivering any output is refunded in full. The reservation step has three outcomes, and only the first is a shortage:
    • 402 — the balance is short. Top it up.
    • 429 with errorCode BALANCE_BUSY and a Retry-After header — your balance is momentarily busy with other concurrent requests of yours, so the call did not start. It is not a shortage and not a rate-limit breach: do not top up; retry after the seconds in Retry-After.
    • 503 with errorCode BALANCE_UNAVAILABLE and a Retry-After header — a temporary service fault interrupted the balance step. It is not a shortage either: do not top up; retry after the seconds in Retry-After.
  • A chat, RAG or document-ask call is billed on the provider's reported usage. The platform does not currently stop the model call when the client disconnects, so a call you abandon can still run to completion and be billed.

Metering semantics

  • Counts are tracked at the account level and broken down per tenant; the account total reconciles to tenants.live + tenants.test.

  • Reads do not draw down the credit allowance within your plan's included read and data-out allowances; past those, overage does, and it is reported under reads and in the credits.breakdown reads / dataOut categories.

  • Trigger-script execution time draws the same credit allowance, reported by the execution section and the credits.breakdown.scriptExecution category — trigger firings and synchronous POST /v1/scripts/execute calls are summed together. It is charged on the measured span of each execution — the whole execution, not only your script's own run time: resolving the rule's identity, preparing the sandbox, running your code, and recording the outcome are all inside it, so totalMillis is legitimately larger than what your own instrumentation would report. From that span it subtracts the execution time the execution's billable operations earned, and adds a fixed per-execution platform baseline. Verify a charge like this:

    billableMillis = totalMillis + (baseline × executions) − includedMillis
    creditsMilli   = billableMillis ÷ (milliseconds per milli-credit)
    

    The report gives you every term but two: the per-execution baseline and the rate. Those are published as numbers on the Vectros pricing page and in the execution schema of the API reference — deliberately not here, since this page does not pin numeric prices and a stale one must never ship from it. Sub-credit remainders carry forward within the period rather than being rounded away, so compare creditsMilli against your period-to-date total, not against a single execution.

  • A firing refused before your script ran is never metered at all — a rate limit, a credit ceiling, a concurrency limit, a rule whose principal or grant does not resolve, a deleted rule, an unresolvable script. None of them appears in execution.executions or execution.totalMillis; there is no duration to report, because nothing of yours ran.

  • An execution that did run your script is metered, and separately decided to be chargeable or not. A failure we attribute to ourselves — an internal platform error — is metered but not charged, and its whole duration is absorbed into includedMillis, so the identity above stays exact rather than being thrown off by the executions least likely to be your fault.

  • ⚠️ An execution that started and then failed is charged, including for reasons that look like refusals. Your script throwing, a timeout, a resource or write-buffer limit, an optimistic-lock conflict on a record another writer touched — and, the two most easily mistaken for pre-flight refusals, a call outside the rule's declared manifest and a permission denial. Those last two are decided while your script runs, and a script that probes, recovers, and then runs for minutes is reported under them: the wall clock was spent either way. Do not read the never-charged list above as covering permission problems generally — it covers a rule that could not be started, not a call your running script was refused.

  • Counters tick as operations dispatch (e.g. a document ingest ticks at dispatch, before indexing completes; a chat call ticks after the stream finalizes), so the report is near-real-time and eventually consistent with in-flight settlement.

  • The inference endpoint section always carries all three keys (chat, rag, ask) even at zero — defaulting is per-endpoint.

  • The all-three inference keys are present on both the account-level and per-tenant sections.

Notes & limits — usage

  • The report is read-only and observability-oriented; it is not an invoice or a line-item transaction export.
  • Rounding: credits.used rounds the account total, which can differ from the sum of the already-rounded per-tenant values by up to one cent — reconcile on usedMilli, not used.
  • Pricing rates, plan allowances, and overage policy are not part of this surface; this documentation does not state numeric prices.
  • Execution time is not attributed per trigger rule or per script. The execution section is an account rollup over the period, and there is no per-rule figure and no execution block inside the per-context contexts[] entries — so if you run several trigger rules, the report cannot tell you which script's execution time you are looking at. If you need that separation today, run the script in its own app context and read that context's credits.usedMilli (which includes the charge), or query with a credential confined to it. If a charge looks wrong and you cannot account for it, raise it with support promptly — the finer-grained evidence behind it is retained for a limited window.

Activity log

client.auth.getAdminLogs(params) (GET /v1/admin/logs). Requires logs:r on a scoped token (a root key always passes). The tenant is derived from the credential — there is no request channel to query another tenant.

Parameters

ParameterTypeNotes
startTimeISO-8601 stringStart of the query window. Required.
endTimeISO-8601 string?End of the window; defaults to now. An endTime not after startTime returns 400.
limitint?Caps returned entries: 1 to 500, default 200. Outside that range is a 400.
errorsOnlyboolean?When true, only entries with status >= 400.
resourcestring?Allow-list-validated resource filter. Accepted values are the data-plane resources (documents, records, search, schemas, folders, usage, models, rag, chat, ask, export, erasure-requests, auth, ping, issuers, scripts, triggers, agents, runs) and the identity surfaces entities, namespaces and users. An unlisted value, including clients and orgs, is rejected with 400.
methodstring?Allow-list-validated HTTP method filter: GET, POST, PUT or DELETE. Anything else is rejected with 400.
keyIdstring?Filter to entries authored by one key.
contextIdstring?Filter to entries of one app context. A credential confined to one app context sees only that context's entries, and naming another context is refused.

Response

FieldTypeNotes
entriesarrayLog entries, newest first.
truncatedbooleanTrue if the query returned limit entries, so the window may hold more.
queryDurationMsnumberBackend query latency.
tenantIdstringThe tenant the query ran against (credential-derived).

Each entry: timestamp (ISO-8601), method, resource, status, and optionally keyId, contextId, durationMs, path, requestId, errorCode, delegationChain. contextId is the app context the call operated under (* for a root or cross-context caller). delegationChain is present only when the call was made with a key minted through the delegate-mint capability, and records who delegated it.

requestId is the call's correlation id — the same value returned as requestId in an error response body. Quote it when contacting support to have a specific call traced. It is recorded for successful calls too.

For a failed call, the entry also carries errorCode when the failure had a typed code — an uppercase token such as RATE_LIMITED, VERSION_CONFLICT or SCRIPT_ERROR.

The set is open and grows as the platform gains new typed failures, so treat any list you see as examples rather than an enumeration: branch on the specific codes you handle and fall back to generic handling for anything else. The codes a given call can return are documented on that endpoint's own error responses; POST /v1/scripts/execute additionally reports the name of its failure category, listed in the data-model reference. See Response versioning above for what raises UNSUPPORTED_WIRE_VERSION specifically.

Branch on the errorCode, not the message text. It is null on successful calls, on failures that carry only a message, and on calls recorded before the field existed that are still inside the retention window — so read an absent errorCode as "not recorded", not as "no error". Request and response bodies are never logged, so no further failure detail is available here by design.

Notes & limits — activity log

  • The resource and method filters are allow-list validated at the boundary; an out-of-allow-list value is rejected, not silently dropped.
  • There is a short ingestion lag (seconds) between a request completing and its entry becoming queryable.
  • This is an operational API call log, not the compliance audit/version history (which is a separate, retained data-layer mechanism — see compliance.md).

Teardown and erasure

Per-customer / per-context hard-delete — implemented

  • Context delete runs an owner-filtered cascade that removes the records, documents, folders, and schemas under a context (the isolation boundary). It is the mechanism for removing one customer's or one application's footprint. Its audit history, including the audit payloads stored outside the database, is removed too; deleting those payloads is asynchronous, so it may finish slightly after the context delete does.
  • Tenant teardown decommissions an entire live or test tenant, cascading across its contexts and tenant-level config (including webhook registrations and delivery rows, which are deleted explicitly because they may carry identifiers). Its audit history and stored audit payloads are removed as well, and the teardown does not report complete until the payloads are gone. The tenant's API key records are deleted, not left behind revoked.
  • What "complete" means for search. A tenant teardown reports complete when no data of the tenant is accessible: its search records are gone and every document still in the search index has no search record behind it, so the product no longer returns it. It does not wait for the search index to physically delete the documents. That deletion is scheduled with the index and is applied when the index rewrites the tenant's data, about a week later, so document text from a torn-down tenant can remain in the search index, typically for about a week and at most 30 days after the teardown reports complete. A daily check by Vectros operations looks for a torn-down tenant whose documents are still in the index past that window and raises an operational alert if it finds one. A context delete and an end-subject erasure leave the same kind of residual for the search documents they erase, with the same bound, and the daily check covers them too.
  • These operations are irreversible and are control-plane actions.

End-subject right-to-erasure

  • POST /v1/erasure-requests submits an asynchronous erasure of one subject (subjectType user, or an ownership namespace such as org or client, including a custom namespace) and returns 202 with a request id; GET /v1/erasure-requests/{id} polls until the job is completed or failed. A completed job carries a certificate: the contexts swept, per-context deletion counts, the number of shared rows skipped (retained because they carry another owner), a count of references to the subject taken before the sweep, the audit disposition requested, and identityRetained (present and true only when the subject's identity was kept because the request did not cover every context).
  • Name the subject with exactly one of subjectId or externalId; sending both or neither is rejected with 400. contextScope lists the contexts to sweep; a context id that does not exist is rejected with 400 before anything is erased. Omit contextScope, or leave it empty, to sweep every context in your account, whether or not the subject holds data there. The subject's identity is account-wide, so it (and, for a user subject, the access profiles in contexts you did not list) is deleted only when the request covers every context of your account; an entity that belongs to a single context (a context-owned namespace) is data of that context, so listing that context deletes it and identityRetained is not set. Otherwise a request that lists only some contexts erases exactly those (including the subject's access profiles in them), keeps the identity and every unlisted context, and sets identityRetained: true; the subject still resolves, so send further requests, and finish with one that has no contextScope. auditDisposition is retain-redacted (default) or purge; it governs only the audit trail, and the subject's solely-owned records, documents, folders and record schemas are erased. A row that also carries another owner is retained and counted (for a user subject, any row with an additional owner scope).
  • The endpoint requires the root API key; a scoped credential (ssk_* / st_*) is rejected with a uniform 403.
  • An end user of your app can delete their own account without the root key, through /v1/me/erasure with their own user token, once you switch it on for the app context. That request erases the user from that one app context only, after a grace period they can cancel, and shows up in this endpoint's polling as accepted (while it waits) or failed with failureCode: cancelled (if they cancel it; nothing was erased, so do not resubmit it). See Let users delete their own account.
  • Limits: purge is supported for user, org and client subjects only (any other subject type is rejected with 400 before anything is erased). It removes the audit records of the rows the request erased, never the history of a row that was retained because another owner shares it, the audit payloads held in the retention-locked audit store for those rows, and, when the identity is deleted, the subject's own identity history. Deleting the stored payloads is asynchronous: the request completes when the audit records are gone and the payloads follow shortly after (a delete that cannot complete is retried and raised to Vectros operations), so completed does not by itself prove every payload is already gone. purge finds history through the owner each version carried when it was written, so it is a primitive, not a completeness guarantee: versions written while the row belonged to a different owner are not found, and the history of an already-deleted row that another owner shared is removed together with the erased owner's. purge does not consult your compliance-retention setting. The reference count is taken before the sweep and only sees references held in a schema reference field that has a reverse index, in the schemas of the contexts swept, so a count of 0 does not prove nothing references the subject.
  • A job can end as failed. A failure before the identity is deleted (the data sweeps, or removing the audit history of the swept contexts) leaves the subject in place, so the request can be resubmitted (it is idempotent). Removing the subject's own identity history is the last step and runs after the identity is deleted: it is retried a few times automatically, and if it still fails the job is marked failed with the identity already gone, so the request can no longer be resubmitted; contact Vectros support.
  • Backups and recovery copies: an erased subject can remain in access-controlled recovery stores (point-in-time recovery, backups and object versions) for a bounded window whose contractual ceiling is set out in the Business Associate Agreement. Where Vectros restores data from a recovery store, it re-applies every erasure recorded in the erasure records available at the time of the restore before the restored data serves production traffic, uses commercially reasonable efforts, taking into account the circumstances of the incident, to identify and re-apply any other erasure, and notifies you if a restore may not have re-applied every erasure; this is performed as a documented manual procedure.
  • This is distinct from context/tenant hard-delete, which decommissions a customer's context or a whole tenant. A data export endpoint (POST /v1/admin/export) is reserved and returns 501 {"error":"not_implemented"} today.

Notes & limits — teardown

  • Right-to-erasure is live but bounded by the limits listed above; export is reserved.
  • Read-access logging / accounting-of-disclosures is available but off by default (opt-in per context or per schema); its admin accounting endpoint is live, and what it covers (including version-history reads) and its limits (tombstone reads are not logged; logging is best-effort) are in compliance.md.
  • Compliance-retention duration and disposition (delete / retain / retain-redacted) are controller-configurable per tenant, with an optional per-context override, via the developer portal only — not the Vectros /v1/* API. Either level left unset falls back to the platform default (~7 years / retain-redacted). Purge runs through the same orchestrated, policy-aware path, never by time-to-live expiry, and retention is anchored as of write: shortening the setting later does not shorten retention already in force for rows already written — except a row written under indefinite retention, which carries no anchor; moving off indefinite to a finite duration later falls that row back to the platform floor (whichever is longer of the new setting or ~7 years), not its original "never expires" promise. A delete disposition also removes the payload stored outside the database for each expired history row, at the controller's window and even when it is shorter than the object store's default lock (asynchronously, shortly after the row delete).

Where to go next

  • explanation.md — the concepts behind everything cataloged here.
  • how-to.md — runnable recipes for webhooks, usage, and the activity log.
  • compliance.md — the trust posture, the three sensitive-data mechanisms, retention, and the full reserved list.