AI Agent Reference
Compact reasoning layer for automated consumers. The agent reads params, schemas, types, and status codes directly from the spec; this section supplies only intent, ordering, safety, and failure logic.
Operation intent table
| operation_id | Goal |
|---|---|
decodeVin | Decode a VIN into structured vehicle attributes, returning both jurisdiction-neutral (raw) and state-normalized views. |
Prerequisite / dependency tree
decodeVin
- requires: valid OAuth client-credentials token (scope oneapi:access)
- requires: Vitu-issued client_id / client_secret (Key Management)
No inter-resource dependencies exist; each call is independent and stateless.
Per-operation reasoning contract
OPERATION: decodeVin
AUTH: REQUIRED — oneVituOauth, scope oneapi:access (bearer token on Authorization)
PRECONDITIONS: REQUIRED — valid, unexpired access token
REQUIRED — vin conforms to spec pattern (17 chars, restricted charset)
OPTIONAL — state; defaults to CA if omitted
OPTIONAL — x-location-id header (effect undocumented; see KNOWN_ISSUE)
SIDE_EFFECTS: NONE — read-only, stateless
SUCCESS_SIGNAL: Response body present as VinDecoded with populated rawValues and/or
stateValues arrays. Presence of the object — not merely a 2xx — is the
signal. Missing individual fields are "unknown," not failure.
AGENT_NOTE: raw view and state view are NOT field-parallel; same attribute may be
free text in one and a coded LookupValueDTO in the other.
Safety classification table
| operation_id | Classification |
|---|---|
decodeVin | safe (read-only) |
Failure-handling rules
ON_FAILURE_AUTH (unauthenticated class):
MEANS: token missing, expired, or invalid.
RETRY: yes — once, after acquiring a fresh token.
BACKOFF: none needed for the token refresh itself.
STOP: if failure persists with a fresh token → escalate as permissions issue.
ON_FAILURE_FORBIDDEN (forbidden class):
MEANS: authenticated but lacks permission for the resource.
RETRY: no.
STOP: immediately; requires credential/scope change via Vitu.
ON_FAILURE_VALIDATION (bad-request class):
MEANS: malformed VIN, invalid state, or other input violation.
RETRY: no (not without correcting input).
STOP: fix request per spec constraints; validate VIN pattern before resend.
ON_FAILURE_RATE_LIMIT (too-many-requests class):
MEANS: rate limit exceeded.
RETRY: yes.
BACKOFF: exponential with jitter; retry after window resets.
(No numeric limit or retry-timing header defined in spec — do not hardcode.)
STOP: after bounded max attempts → escalate.
ON_FAILURE_SERVER (server-error class):
MEANS: server-side failure.
RETRY: yes, cautiously.
BACKOFF: exponential with jitter.
STOP: after bounded max attempts → escalate to [email protected].
Workflow recipes
RECIPE: Jurisdiction-neutral decode
1. Acquire token (client-credentials, scope oneapi:access).
2. decodeVin(vin).
3. Read rawValues view.
RECIPE: State-normalized decode
1. Acquire token.
2. decodeVin(vin, state).
3. Read stateValues view; resolve LookupValueDTO fields via code+description.
RECIPE: Token lifecycle
1. Cache token until near expiry; reuse across decode calls.
2. On ON_FAILURE_AUTH → acquire new token, retry the call once.
3. No refresh-token step (client-credentials grant).