Skip to main content
Velatir gives organisations a single view of how AI is used across their business: oversight, compliance, and insight. To include your product in that view, Velatir connects to your system and retrieves a defined set of data describing how their people use its AI features. This specification defines the data Velatir consumes and the shape it expects. The transport is your choice; the data model is what is normative.
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.
​
id
string
Stable, unique identifier for the interaction.
​
conversationId
string
Thread identifier, where the interaction is part of a multi-turn conversation.
​
startedAt
timestamp
When the interaction began. RFC 3339, UTC.
​
updatedAt
timestamp
When the record was last modified.
​
deletedAt
timestamp
Present when the interaction has been deleted.
​
user
object
The person who ran the interaction.
​
assistant
object
The custom assistant used, if any. See Assistants.
​
model
string
Model used, for example gpt-4o.
​
modelProvider
string
Underlying LLM vendor, for example openai.
​
parameters
object
Sampling configuration: temperature, topP, maxTokens, and similar.
​
systemPrompt
string
The system prompt in effect. Provide systemPromptHash instead where the text cannot be shared.
​
messages
object[]
The turns of the interaction.
​
tools
object[]
Tools or skills invoked during the interaction.
​
attachments
object[]
Files exchanged during the interaction.
​
usage
object
Token counts and cost: inputTokens, outputTokens, totalTokens, cost.
​
status
string
Outcome of the interaction.
​
metadata
object
Any additional provider-specific fields, preserved as received.

​
2. Usage and cost

Aggregated, time-bucketed usage, for adoption and cost reporting.
​
startAt
timestamp
Start of the bucket.
​
endAt
timestamp
End of the bucket.
​
granularity
enum
hour or day.
​
dimensions
object
The grouping keys present in the bucket, any subset of the following.
​
metrics
object
The measured values for the bucket.

​
3. Assistants

Where your product allows customers to configure their own assistants, agents, or custom GPTs, one record per assistant describing its configuration.
​
id
string
​
name
string
​
description
string
​
status
string
For example active or archived.
​
createdAt
timestamp
​
updatedAt
timestamp
​
owner
object
The user who owns the assistant.
​
visibility
enum
private, team, organisation, or public.
​
model
string
Default model.
​
parameters
object
Default sampling configuration.
​
instructions
string
The assistant’s instructions. Provide instructionsHash instead where the text cannot be shared.
​
skills
object[]
Tools or skills installed on the assistant.
​
connectors
object[]
Integrations and data sources connected to the assistant.
​
knowledge
object[]
Attached knowledge or reference files.
​
usage
object
Rollup: conversationCount, userCount, lastUsedAt.

​
4. Events

One record per notable action, forming an audit trail. Your native event type is preserved verbatim; the normalised fields are best-effort.
​
id
string
​
occurredAt
timestamp
​
type
string
Your native event type.
​
actor
object
Who performed the action.
​
category
enum
Authentication, Access, Configuration, DataMovement, ResourceLifecycle, Integration, Policy, or Other.
​
action
enum
Created, Updated, Deleted, Enabled, Disabled, Exported, Shared, and similar.
​
target
object
What the action affected.
​
payload
object
The raw event body, preserved as received.

​
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 example read: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 id on every record allows Velatir to update records in place rather than duplicate them on re-sync.
  • Timestamps. RFC 3339, UTC. updatedAt and occurredAt allow 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) and occurredAfter (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.

​
Reference API

A minimal REST implementation consists of the following read-only endpoints: 
GET /usage          ?startAt&endAt&granularity&groupBy
GET /assistants     ?updatedSince&cursor
GET /assistants/{id}
GET /conversations  ?updatedSince&startedAfter&cursor
GET /conversations/{id}
GET /events         ?occurredAfter&category&cursor
An example conversation record: 
{
  "id": "conv_8f21a0",
  "conversationId": "thread_5521",
  "startedAt": "2026-07-03T09:15:00Z",
  "updatedAt": "2026-07-03T09:16:12Z",
  "user": { "id": "u_204", "email": "user@company.com", "department": "Operations" },
  "assistant": { "id": "asst_44", "name": "Support Assistant" },
  "model": "gpt-4o",
  "modelProvider": "openai",
  "parameters": { "temperature": 0.4, "maxTokens": 1024 },
  "systemPrompt": "You are a helpful assistant that ...",
  "messages": [
    { "id": "m1", "role": "user", "content": "How do I process this request?", "createdAt": "2026-07-03T09:15:00Z" },
    { "id": "m2", "role": "assistant", "content": "First, you ...", "createdAt": "2026-07-03T09:15:04Z" }
  ],
  "tools": [{ "id": "search", "name": "Knowledge search", "type": "builtin" }],
  "usage": { "inputTokens": 320, "outputTokens": 210, "totalTokens": 530 }
}