Why one-descriptor API requests are easier to trust than ambiguous batches.

Single-item contracts make failure ownership explicit. One descriptor enters validation, receives one timeout boundary, and returns one confidence score, signal list, and warning list. A caller can tell exactly which transaction was accepted, rejected, retried, or shown with fallback UI.

POST /v1/enrich
{"raw_description":"SQ *JOES COFFEE 0421 TORONTO","country":"CA","mcc":"5814"}

POST /v1/enrich
{"raw_description":"NORTHSIDE MARKET 017 KINGSTON","country":"CA"}

The first call may match reviewed evidence. The second may return an honest miss. Neither result is coupled to the other, and a privacy rejection for one descriptor does not create an unclear partial-success state for a larger payload.

Keep concurrency outside the contract

for each transaction with bounded concurrency:
  validate local input boundary
  call POST /v1/enrich
  cache by safe normalized signature
  retry only transient failures
  render confidence and warnings per item

A single-descriptor API does not mean clients must process feeds serially. The caller can choose bounded concurrency, backpressure, caching, and retry policy that fit its workload. The API remains narrow while operational throughput stays under client control.

Batch APIs can be appropriate when atomic bulk semantics, file import, or provider-owned job orchestration is the product. They also need precise rules for per-item validation, partial failure, ordering, retry identifiers, body limits, and privacy rejection. TxnKit deliberately avoids introducing those ambiguous semantics into its first public contract.

When to use it

Use one-descriptor requests for interactive transaction feeds, incremental imports, supportable retries, agent calls, and integrations where each row needs an explainable outcome. The complete contract is visible in the TxnKit API docs and OpenAPI document.

When not to use it

Do not assume a single-item endpoint replaces every bulk ingestion architecture. If a system must accept large offline files or guarantee all-or-nothing processing, design a separate import job with explicit status and privacy controls instead of hiding batch behavior inside the interactive endpoint.

Privacy caveat

Smaller payloads reduce blast radius but do not remove the privacy obligation. Reject card numbers, account numbers, customer PII, bank credentials, contact details, full statements, and multi-transaction text before calling the API. Never put raw descriptors in URLs, analytics, or broad request logs.