AI Agent Reference

Compact reasoning layer for automated agents. The agent is assumed to read the OpenAPI spec directly for params, schemas, types, and status codes. This section supplies intent, ordering, side effects, safety, and failure handling only.

Operation Intent Table

operation_id	Goal
`CreateTransaction`	Submit a new state-specific title/registration transaction (async).
`UpdateTransaction`	Revise an existing transaction before commit (async; semantics unspecified).
`CancelTransaction`	Cancel an existing transaction (async).
`CommitTransaction`	Finalize/submit a transaction; requires shipping details (async).
`GetTransactionStatus`	Read current, type-specific transaction status.
`GetTransactionFees`	Read jurisdiction-calculated fees for a transaction.
`GetTransactionForms`	List documents produced by a transaction.
`DownloadTransactionForms`	Download produced documents as PDF, optionally by recipient target.
`DownloadTransactionDocument`	Download one document by ID, optionally blank.
`DownloadTransactionCoversheet`	Download shipping coversheet; may report not-ready.
`GetTransactionIdByRefNumber`	Resolve a reference UUID to the numeric transaction ID.

Prerequisite / Dependency Tree

valid client-credentials token (scope oneapi:access)
- CreateTransaction
    - transaction (addressable by id or refNumber)
      - GetTransactionIdByRefNumber   (needs refNumber from create)
      - UpdateTransaction             (needs uncommitted transaction)
      - GetTransactionFees            (needs processing to have produced fees)
      - GetTransactionForms           (needs processing to have produced forms)
              │     └── DownloadTransactionForms / DownloadTransactionDocument (needs listed docs)
      - GetTransactionStatus
      - CommitTransaction             (needs uncommitted transaction + shipping)
              │     └── DownloadTransactionCoversheet (needs shipping docs assigned)
      - CancelTransaction

Per-Operation Reasoning Contracts

OPERATION: CreateTransaction
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: valid token (REQUIRED); state-specific body matching `state` discriminator (REQUIRED); callbackUrl (OPTIONAL, HTTPS); own reference number (OPTIONAL, recommended)
SIDE_EFFECTS: creates a transaction resource; may trigger async processing and later callbacks
SUCCESS_SIGNAL: acknowledgement accepted; TRUE success only when status/universalStatus reflects progress via GetTransactionStatus or a success callback — NOT the HTTP acknowledgement itself
AGENT_NOTE: async; do not assume fees/forms exist immediately after this returns

OPERATION: UpdateTransaction
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing, uncommitted transaction (REQUIRED); full state-specific body (REQUIRED)
SIDE_EFFECTS: mutates transaction; may recompute fees/forms; may trigger callbacks
SUCCESS_SIGNAL: subsequent status/fees/forms reflect the change

OPERATION: CancelTransaction
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (REQUIRED); cancellation message (OPTIONAL)
SIDE_EFFECTS: cancels the transaction; may trigger callbacks
SUCCESS_SIGNAL: status reflects a cancelled/void state
AGENT_NOTE: treat as effectively irreversible — see safety table

OPERATION: CommitTransaction
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing, reviewed, uncommitted transaction (REQUIRED); finalize body with shipping (REQUIRED); plate destination / signer info (OPTIONAL per state)
SIDE_EFFECTS: submits the filing for final processing; assigns shipping; may trigger callbacks
SUCCESS_SIGNAL: status/universalStatus advances to a committed/submitted state via status or success callback

OPERATION: GetTransactionStatus
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (REQUIRED); transactionType for correct status variant (OPTIONAL but recommended)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: status payload returned; read the type-specific status field

OPERATION: GetTransactionFees
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction whose processing has produced fees (REQUIRED)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: fee list returned (may be empty before processing completes)

OPERATION: GetTransactionForms
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction whose processing has produced documents (REQUIRED); limit/offset for paging (OPTIONAL)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: document list returned

OPERATION: DownloadTransactionForms
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction with produced documents (REQUIRED); recipient target (OPTIONAL)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: PDF binary returned

OPERATION: DownloadTransactionDocument
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: existing transaction (REQUIRED); valid documentId (REQUIRED); blank flag (OPTIONAL)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: PDF binary returned

OPERATION: DownloadTransactionCoversheet
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: committed transaction with shipping documents assigned (REQUIRED)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: PDF binary returned; a no-content response means "not ready yet, retry later" — NOT failure
AGENT_NOTE: poll on not-ready; distinguish from not-found

OPERATION: GetTransactionIdByRefNumber
AUTH: keycloak / oneapi:access (REQUIRED)
PRECONDITIONS: a refNumber previously supplied at create (REQUIRED)
SIDE_EFFECTS: none
SUCCESS_SIGNAL: numeric transaction ID returned

Safety Classification Table

operation_id	Classification
`GetTransactionStatus`	safe (read-only)
`GetTransactionFees`	safe (read-only)
`GetTransactionForms`	safe (read-only)
`DownloadTransactionForms`	safe (read-only)
`DownloadTransactionDocument`	safe (read-only)
`DownloadTransactionCoversheet`	safe (read-only)
`GetTransactionIdByRefNumber`	safe (read-only)
`CreateTransaction`	mutating
`UpdateTransaction`	mutating
`CommitTransaction`	mutating (effectively irreversible — submits a real filing in production)
`CancelTransaction`	irreversible

Failure-Handling Rules

ON_FAILURE_AUTH_UNAUTHENTICATED:
  MEANS: token missing/expired/invalid
  RETRY: yes, once, after acquiring a fresh token
  BACKOFF: none needed for the first re-auth attempt
  STOP: if failure persists after re-auth — treat as credential/config error

ON_FAILURE_AUTH_FORBIDDEN:
  MEANS: authenticated but lacks permission for the resource
  RETRY: no
  STOP: immediately; escalate to permission/scope review

ON_FAILURE_VALIDATION:
  MEANS: malformed or state-invalid request body/params
  RETRY: no (not without changing the payload)
  STOP: immediately; repair against the per-state schema, then resubmit

ON_FAILURE_NOT_FOUND:
  MEANS: unknown transaction/document identifier
  RETRY: only if the resource may be newly created and eventually consistent
  BACKOFF: short, bounded polling
  STOP: after a bounded number of attempts; then treat identifier as invalid

ON_FAILURE_RATE_LIMIT:
  MEANS: throttled (too many requests)
  RETRY: yes
  BACKOFF: wait for the window to reset, then exponential backoff with jitter
  STOP: after a bounded retry budget

ON_FAILURE_SERVER:
  MEANS: server-side error
  RETRY: yes, cautiously
  BACKOFF: exponential with jitter, bounded attempts
  STOP: after budget exhausted
  AGENT_NOTE: for mutating ops (Create/Update/Commit/Cancel) reconcile via GetTransactionStatus or GetTransactionIdByRefNumber before retrying — idempotency is unspecified

Workflow Recipes

RECIPE: submit_and_commit

1. CreateTransaction (state-specific body; set own refNumber; optional callbackUrl)
2. GetTransactionIdByRefNumber (if only refNumber is retained)  [OPTIONAL]
3. POLL GetTransactionStatus until processing has produced fees/forms (or await callback)
4. GetTransactionFees; GetTransactionForms  (review)
5. CommitTransaction (finalize body incl. shipping)
6. POLL GetTransactionStatus until committed/submitted (or await success callback)

RECIPE: revise_before_commit

1. CreateTransaction
2. UpdateTransaction (full corrected state-specific body)
3. GetTransactionFees / GetTransactionForms (re-review if affected)
4. CommitTransaction

RECIPE: retrieve_documents

1. GetTransactionForms (page via limit/offset)
2. For each needed doc: DownloadTransactionDocument (by documentId; blank optional)
   - - OR DownloadTransactionForms (bulk; optional recipient target)
3. DownloadTransactionCoversheet (poll on not-ready responses)

RECIPE: correlate_existing

1. GetTransactionIdByRefNumber (refNumber -> numeric id)
2. Use id (or refNumber) on any transaction-scoped operation