Access is strictly read-only. Velatir retrieves data on a schedule and never sits in the path of a live request, so an integration cannot affect your users’ experience.
Resources
Velatir consumes four independent resource types. Implement those your system supports; apart from identifiers and timestamps, all fields are optional.1. Conversations
One record per AI interaction: a conversation, or a single request and response exchange for stateless systems. This is the content Velatir’s compliance agents review.The custom assistant used, if any. See Assistants.
The system prompt in effect. Provide
systemPromptHash instead where the text cannot be shared.2. Usage and cost
Aggregated, time-bucketed usage, for adoption and cost reporting.3. Assistants
Where your product allows customers to configure their own assistants, agents, or custom GPTs, one record per assistant describing its configuration.The assistant’s instructions. Provide
instructionsHash instead where the text cannot be shared.4. Events
One record per notable action, forming an audit trail. Your native event type is preserved verbatim; the normalised fields are best-effort.Authentication, Access, Configuration, DataMovement, ResourceLifecycle, Integration, Policy, or Other.Access and synchronisation
Transport. A read-only REST/JSON API is recommended and the simplest to integrate. An MCP server, a scheduled export, or webhooks are equally acceptable; the resource shapes above are what is normative. Authentication. A single credential (bearer token or API key) per customer, scoped to that customer’s data only. Per-resource scopes, for exampleread:usage or read:conversations, allow a customer to share usage metrics without exposing conversation content.
Synchronisation. Velatir retrieves data by polling on a schedule. The following are recommended rather than required; where they are absent, Velatir performs a full re-pull.
- Stable identifiers. A stable
idon every record allows Velatir to update records in place rather than duplicate them on re-sync. - Timestamps. RFC 3339, UTC.
updatedAtandoccurredAtallow Velatir to request only records that changed since the previous poll. - Pagination. Lists that return
{ data[], hasMore, nextCursor }with an opaque, retry-safe cursor allow Velatir to page through large histories reliably. - Incremental retrieval. Filtering lists by
updatedSince(conversations, assistants) andoccurredAfter(events) avoids re-reading the full history on each poll. - Forward compatibility. Fields and enum values may be added at any time. Velatir ignores unknown fields and never discards an unrecognised event
type.