Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the spec; this section supplies intent, ordering, side effects, and safety.
| operation_id | Goal |
|---|
SetCallbackSecurity | Configure how Vitu authenticates itself when delivering to the caller's callback URL. |
Subscribe | Register/update the caller's HTTPS callback URL to receive MVR notifications. |
GetSubscription | Retrieve the caller's currently registered callback URL. |
Unsubscribe | Cancel the caller's subscription; stop deliveries. |
OAuth token (oneVituOauth, scope oneapi:access)
- SetCallbackSecurity [independent; recommended before Subscribe]
- Subscribe [requires resolvable https callback URL]
│ └── GetSubscription [meaningful only after Subscribe]
│ └── Unsubscribe [meaningful only after Subscribe]
- GetSubscription / Unsubscribe (no-op or empty if never subscribed)
OPERATION: SetCallbackSecurity
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS: REQUIRED — caller controls the callback endpoint that will honor the chosen mechanism(s)
SIDE_EFFECTS: REQUIRED — replaces callback-security config; affects authentication of all future deliveries
SUCCESS_SIGNAL: REQUIRED — success response per spec; subsequent deliveries authenticate as configured
AGENT_NOTE: Mechanisms in CallbackSecuritySettingsDTO are combinable.
OPERATION: Subscribe
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS: REQUIRED — callbackUrl is https and publicly resolvable
SIDE_EFFECTS: REQUIRED — creates or REPLACES the caller's single subscription (not additive)
SUCCESS_SIGNAL: REQUIRED — GetSubscription returns the newly registered callbackUrl
AGENT_NOTE: Configure SetCallbackSecurity first so first delivery is authenticated.
OPERATION: GetSubscription
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS: OPTIONAL — none; returns current state
SIDE_EFFECTS: none (read-only)
SUCCESS_SIGNAL: REQUIRED — response contains the registered callbackUrl
OPERATION: Unsubscribe
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS: OPTIONAL — a subscription should exist to have effect
SIDE_EFFECTS: REQUIRED — deletes the caller's subscription; deliveries stop
SUCCESS_SIGNAL: REQUIRED — GetSubscription no longer returns an active callbackUrl
| operation_id | Classification |
|---|
GetSubscription | safe (read-only) |
SetCallbackSecurity | mutating (replaces config) |
Subscribe | mutating (replaces subscription) |
Unsubscribe | irreversible for current registration (re-subscribe required to restore) |
ON_FAILURE_AUTH (401):
MEANING: token missing/expired/invalid
RETRY: yes, once, after obtaining a fresh token
STOP: if still failing after refresh — credential/config error
ON_FAILURE_FORBIDDEN (403):
MEANING: authenticated but lacks entitlement/scope
RETRY: no
STOP: immediately; escalate to Vitu
ON_FAILURE_VALIDATION (400):
MEANING: malformed request (e.g. non-https callbackUrl)
RETRY: no (until request corrected)
STOP: inspect Error[].message; fix and resend
ON_FAILURE_RATE_LIMIT (429):
MEANING: rate limit exceeded
RETRY: yes, after window reset
BACKOFF: exponential with jitter
STOP: after a bounded max-attempt ceiling
ON_FAILURE_SERVER (500):
MEANING: server-side error
RETRY: yes
BACKOFF: exponential with jitter
STOP: after bounded max attempts; escalate
RECIPE: Begin receiving notifications
1. SetCallbackSecurity (configure delivery auth)
2. Subscribe (register https callbackUrl)
3. GetSubscription (confirm callbackUrl registered)
4. [endpoint] verify inbound deliveries using configured mechanism
RECIPE: Rotate callback endpoint
1. SetCallbackSecurity (if new endpoint uses new credentials)
2. Subscribe (new callbackUrl — replaces prior)
3. GetSubscription (confirm)
RECIPE: Stop notifications
1. Unsubscribe
2. GetSubscription (confirm no active registration)