MVR — AI Agent Reference | Vitu Production Developer Portal

AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, types, and status codes directly from the OpenAPI spec. This section supplies only intent, ordering, side effects, and safety.

Operation intent

operation_id	Goal
`CreateInquiry`	Submit a state-specific vehicle-record inquiry; returns an inquiry ID. Processing is async.
`LoadInquiryById`	Retrieve the inquiry (and state-specific fields) by server inquiry ID.
`LoadInquiryByRefNumber`	Retrieve the inquiry by client UUID `refNumber`.
`LoadUnifiedInquiryRecord`	Retrieve the normalized cross-state vehicle record for an inquiry.
`GetPrintout`	Retrieve the inquiry result as a PDF.

Prerequisite / dependency tree

Valid OAuth token (oneVituOauth, scope oneapi:access)
  └─ CreateInquiry  → yields inquiryId + refNumber
        ├─ LoadInquiryById            (needs inquiryId)
        ├─ LoadInquiryByRefNumber     (needs refNumber)
        ├─ LoadUnifiedInquiryRecord   (needs inquiryId; meaningful after processing)
        └─ GetPrintout                (needs inquiryId; meaningful after processing)

Per-operation reasoning contracts

OPERATION: CreateInquiry
  AUTH: oneVituOauth / oneapi:access                         [REQUIRED]
  PRECONDITIONS:
    - Valid token                                            [REQUIRED]
    - Body matches StateInquiryDTO variant for `state`       [REQUIRED]
    - State-specific required fields present per variant     [REQUIRED]
    - callbackUrl for async notification                     [OPTIONAL]
    - context headers (location id, on-behalf user id)       [OPTIONAL]
  SIDE_EFFECTS:
    - Creates a persistent inquiry resource                  [REQUIRED]
    - May trigger a billable lookup (see `charged`)          [REQUIRED]
    - Initiates async processing against a state authority   [REQUIRED]
  SUCCESS_SIGNAL:
    - Response returns an inquiryId (InquiryIdResponseDTO).
    - NOTE: not completion. Completion = inquiry.processedDate set
      and inquiry.error empty on a subsequent load.
  AGENT_NOTE: Do not treat create-response as final result.

OPERATION: LoadInquiryById
  AUTH: oneVituOauth / oneapi:access                         [REQUIRED]
  PRECONDITIONS:
    - Existing inquiryId from a prior CreateInquiry          [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL:
    - Returns the inquiry. Check processedDate / error to
      determine whether the result is ready.

OPERATION: LoadInquiryByRefNumber
  AUTH: oneVituOauth / oneapi:access                         [REQUIRED]
  PRECONDITIONS:
    - Known refNumber (UUID) for an existing inquiry         [REQUIRED]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL:
    - Returns the inquiry; inspect processedDate / error.

OPERATION: LoadUnifiedInquiryRecord
  AUTH: oneVituOauth / oneapi:access                         [REQUIRED]
  PRECONDITIONS:
    - Existing inquiryId                                     [REQUIRED]
    - Inquiry processing complete (else record may be empty) [OPTIONAL/advisory]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL:
    - Returns MVRBaseRecordDTO. Sections are individually
      optional; treat all as null-safe.

OPERATION: GetPrintout
  AUTH: oneVituOauth / oneapi:access                         [REQUIRED]
  PRECONDITIONS:
    - Existing inquiryId                                     [REQUIRED]
    - Processing complete for a meaningful document          [OPTIONAL/advisory]
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL:
    - Returns application/pdf binary.

Safety classification

operation_id	Classification
`CreateInquiry`	mutating (creates resource; may be billable / trigger external lookup)
`LoadInquiryById`	safe (read-only)
`LoadInquiryByRefNumber`	safe (read-only)
`LoadUnifiedInquiryRecord`	safe (read-only)
`GetPrintout`	safe (read-only)

No delete/irreversible operations are defined. CreateInquiry is not reversible via this API (no cancel/void operation exists) — classify its billing/lookup side effect as effectively irreversible once submitted.

Failure-handling rules

ON_FAILURE_AUTH_UNAUTHENTICATED:
  MEANS: token missing/expired/invalid.
  RETRY: yes, once, after acquiring a fresh token.
  BACKOFF: none for the refresh; single retry.
  STOP: if failure repeats post-refresh → credential/config error; stop.

ON_FAILURE_AUTH_FORBIDDEN:
  MEANS: authenticated but not permitted.
  RETRY: no.
  STOP: immediately; escalate (entitlement/scope issue).

ON_FAILURE_VALIDATION:
  MEANS: bad request; likely wrong StateInquiryDTO variant or
         missing state-required field. Detail in Errors[].message.
  RETRY: no (not without changing the request).
  STOP: immediately; correct request against the state variant.

ON_FAILURE_RATE_LIMIT:
  MEANS: shared TooManyRequests response.
  RETRY: yes, after the window resets.
  BACKOFF: exponential + jitter (no documented Retry-After header).
  STOP: after capped attempts; escalate.

ON_FAILURE_SERVER:
  MEANS: server-side error (Errors schema).
  RETRY: yes.
  BACKOFF: exponential + jitter.
  STOP: after capped attempts; escalate.

ON_INQUIRY_LEVEL_ERROR:
  MEANS: HTTP success but inquiry.error is populated (state
         lookup failed). Not a transport failure.
  RETRY: no automatic retry; treat as a business-level failure.
  STOP: surface inquiry.error to caller.

Workflow recipes

RECIPE: Fetch unified vehicle record (polling)

1. CreateInquiry(body per StateInquiryDTO[state]) → inquiryId
2. LOOP: LoadInquiryById(inquiryId)
   - - UNTIL processedDate set OR error set OR poll cap reached
   - - (backoff between polls)
3. IF error set → ON_INQUIRY_LEVEL_ERROR
4. LoadUnifiedInquiryRecord(inquiryId) → MVRBaseRecordDTO

RECIPE: Fetch unified vehicle record (callback)

1. CreateInquiry(..., callbackUrl) → inquiryId, refNumber
2. AWAIT CallbackDTO on callbackUrl
   - - correlate via refNumber or inquiryId
3. IF CallbackDTO.error → ON_INQUIRY_LEVEL_ERROR
4. LoadUnifiedInquiryRecord(inquiryId)

RECIPE: Produce PDF

1. CreateInquiry → inquiryId
2. Confirm completion (poll or callback)
3. GetPrintout(inquiryId) → PDF binary