AI Agent Reference

Compact reasoning layer for automated agents. The agent reads params, schemas, enums, and status codes directly from the OpenAPI spec; this section supplies only what the spec cannot express.

Operation Intent Table

operation_id	Goal
`createInquiry`	Submit a VIN to start an NMVTIS lookup; returns an inquiry identifier.
`LoadInquiryById`	Retrieve an inquiry's status/metadata by server-assigned inquiry ID.
`LoadInquiryByRefNumber`	Retrieve an inquiry's status/metadata by client-supplied reference number.
`LoadInquiryRecord`	Retrieve the structured history record for a processed inquiry.
`GetReport`	Retrieve the PDF report for a processed inquiry.

Prerequisite / Dependency Tree

Valid OAuth token (scope: oneapi:access)
- createInquiry
  - inquiry exists (has inquiryId + refNumber)
    - LoadInquiryById / LoadInquiryByRefNumber  (any time after creation)
    - inquiry processed (processedDate set, error empty)
      - LoadInquiryRecord
      - GetReport

Per-Operation Reasoning Contracts

OPERATION: createInquiry
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS:
  - REQUIRED: valid token
  - REQUIRED: unique refNumber (UUID) generated by caller
  - REQUIRED: vin
  - OPTIONAL: x-location-id, x-on-behalf-user-id headers
SIDE_EFFECTS: Creates a new inquiry; triggers async NMVTIS processing.
SUCCESS_SIGNAL: Response body contains inquiryId (InquiryIdResponseDTO). Creation != completion.
AGENT_NOTE: Persist your refNumber as the correlation key.

OPERATION: LoadInquiryById
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS:
  - REQUIRED: an inquiry created via createInquiry
  - REQUIRED: inquiryId
SIDE_EFFECTS: None (read-only).
SUCCESS_SIGNAL: 2xx with InquiryResponseDTO. Completion = processedDate populated AND error empty.

OPERATION: LoadInquiryByRefNumber
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS:
  - REQUIRED: an inquiry created with this refNumber
  - REQUIRED: refNumber
SIDE_EFFECTS: None (read-only).
SUCCESS_SIGNAL: 2xx with InquiryResponseDTO. Completion = processedDate populated AND error empty.

OPERATION: LoadInquiryRecord
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS:
  - REQUIRED: inquiry processed successfully (processedDate set, error empty)
  - REQUIRED: inquiryId
SIDE_EFFECTS: None (read-only).
SUCCESS_SIGNAL: 2xx with InquiryRecordDTO. Missing sub-sections = no data reported, NOT failure.
AGENT_NOTE: Calling before processing completes may yield empty/partial data.

OPERATION: GetReport
AUTH: REQUIRED — oneVituOauth, scope oneapi:access
PRECONDITIONS:
  - REQUIRED: inquiry processed successfully
  - REQUIRED: inquiryId
SIDE_EFFECTS: None (read-only).
SUCCESS_SIGNAL: 2xx with application/pdf binary body.

Safety Classification Table

operation_id	Classification
`createInquiry`	mutating (creates resource; triggers external processing)
`LoadInquiryById`	safe (read-only)
`LoadInquiryByRefNumber`	safe (read-only)
`LoadInquiryRecord`	safe (read-only)
`GetReport`	safe (read-only)

No irreversible operations are defined.

Failure-Handling Rules

ON_FAILURE_AUTH (not-authenticated class):
  MEANING: token missing/expired/invalid.
  RETRY: yes, once, after obtaining a fresh token.
  STOP_CONDITION: second consecutive auth failure -> treat as credential/config error; stop.

ON_FAILURE_AUTHZ (not-authorized class):
  MEANING: valid token, insufficient permission.
  RETRY: no.
  STOP_CONDITION: immediate; escalate to credential owner.

ON_FAILURE_VALIDATION (bad-request class):
  MEANING: malformed/invalid input; details in Errors[].field/message.
  RETRY: no (not without changing the request).
  STOP_CONDITION: immediate; surface field-level messages.

ON_FAILURE_NOT_FOUND:
  MEANING: referenced inquiry not found (or not yet visible) for the given id/refNumber.
  RETRY: conditional — if immediately after createInquiry, brief retry for consistency; else no.
  STOP_CONDITION: after bounded retries, stop.
  AGENT_NOTE: spec does not declare a distinct 404 body; may surface via bad-request or empty result.

ON_FAILURE_RATE_LIMIT (too-many-requests class):
  MEANING: request throttled.
  RETRY: yes.
  STRATEGY: honor retry header if present; else exponential backoff with jitter.
  STOP_CONDITION: max attempts/time budget exceeded.

ON_FAILURE_SERVER (server-error class):
  MEANING: server-side failure.
  RETRY: yes, bounded.
  STRATEGY: exponential backoff with jitter; idempotent for read ops. For createInquiry, reuse the same refNumber to avoid duplicate inquiries.
  STOP_CONDITION: max attempts exceeded -> escalate.

Workflow Recipes

RECIPE: Lookup via polling

1. createInquiry {vin, refNumber} -> capture inquiryId
2. LOOP: LoadInquiryById(inquiryId)
   - - until processedDate populated (success) OR error populated (fail)
   - - backoff between polls
3. IF success: LoadInquiryRecord(inquiryId)
4. OPTIONAL: GetReport(inquiryId)

RECIPE: Lookup via callback (pending callback-URL confirmation)

1. createInquiry {vin, refNumber, callback destination}
2. RECEIVE transactionCompleted callback -> match by refNumber
3. IF callback.error empty: LoadInquiryRecord(inquiryId)
4. OPTIONAL: GetReport(inquiryId)
FALLBACK: if callback mechanism unconfirmed/unavailable, use polling recipe.

RECIPE: Retrieve report for an already-processed inquiry

1. LoadInquiryById(inquiryId) -> confirm processedDate set, error empty
2. GetReport(inquiryId)