Resources / Changelog
Changelog
Changes to the Nustro API, dashboard, and these guides. Breaking changes are announced before they ship and are never applied silently.
What counts as breaking
Build against this contract and additive changes will not disturb you.
| Change | Breaking? | Notes |
|---|---|---|
| New endpoint | No | Ignore what you do not use. |
| New optional request field | No | Defaults preserve existing behaviour. |
| New response field | No | Your parser must tolerate unknown fields. This is the most common source of self-inflicted breakage. |
| New enum value | No | Handle unrecognised values as a default case rather than failing. |
| New event type | No | Ignore event types you do not recognise. |
| New error code | No | Fall back on the HTTP status class. |
| Removing or renaming a field | Yes | Announced, with a migration window. |
| Changing a field’s type or meaning | Yes | Announced. Semantics changes are treated as seriously as type changes. |
| Removing an event type or error code | Yes | Announced. |
| Tightening validation | Yes | A request that used to succeed and now fails is breaking, even if it was always ill-formed. |
Nustro enforces
Additive changes ship without notice, so your integration must tolerate them: unknown fields, unknown enum values, unknown event types, unknown error codes. A parser that rejects what it does not recognise will break on a change that broke nobody else.
How changes are announced
| Channel | Carries |
|---|---|
| This page | Everything, newest first |
customer.* notices | Account-affecting changes, to your registered admin contact |
| Status page | Incidents and degradations — operational, not contractual |
Sandbox receives changes ahead of production wherever the difference is meaningful, so an integration tested there sees new behaviour before its live traffic does.
Log
Error statuses: validation is 422, state conflicts are 409
- Field and value validation across management endpoints moved
400→422, carryingfield_errors[]. Affectsmissing_fields,invalid_economic_role,invalid_cert_tier,invalid_field,field_not_allowed_for_role,invalid_market_format, the counterparty-floor, spending-limit, escrow-config and dispute field codes, and more — see Errors for the full table. - Illegal transitions moved
400→409:invalid_status,use_activate_endpoint,escrow_constrained_cannot_reactivate. - The rule, from here on:
400the request itself is wrong;422the values are invalid;409the object’s state forbids it.no_changes_requestedstays400— an empty patch is a request problem, not a validation failure. - The response body was already canonical, so only the HTTP status changed. If you branch on status, update; if you branch on
code, nothing breaks.
Agent catalogues, the scheme directory, and five new error codes
catalog_urlonidentity.profile— a link to your agent’s schema.orgOfferCatalog. Provider and enterprise only; serializesnullon consumers. Only the link is signed; Nustro never fetches the document. See Agent configuration.- Scheme directory —
GET /v1/directory/agents,/agents/{did}and/changes: every certified agent on the scheme, with an incremental change feed. See Scheme directory. - Five error conditions that previously collapsed into a generic code are now branchable:
agent_status_not_mutable,no_changes_requested,use_activate_endpoint,escrow_constrained_cannot_reactivate,catalog_url_not_permitted; pluscert_tier_role_mismatchandauthorized_action_role_mismatchinsidefield_errors.
API v0.3 — the tenant is the Platform
- Every
/v1/customer(s)/*account path moved under/v1/platform. Old paths return 404 — a hard cutover, not a redirect. - Renamed: KYB status field
customer_status→platform_status; profilecustomer_id→platform_id(plat_…); schemasCustomer{Register, Registered, Profile}→Platform*; webhook eventcustomer.verification_decided→platform.verification_decided. - New and additive: the Customers grouping resource (
/v1/customers) — group principals under your own customers, filter principals bycustomer_id, suspend a customer to suspend its principals in one call. Opt-in: never set it and nothing changes. - Migration: a find/replace of the path prefix covers ~95% — the hand-fixes are the profile
statusread and the webhook event string.
Webhook endpoints
- Register multiple endpoints, each with its own environment, event selection, and signing secret.
- Deliveries carry
Nustro-Signature,Nustro-Timestamp, andNustro-Event-Id. - Event types:
customer.verification_decided,transaction.settled,dispute.filed,dispute.resolved,agent.status_changed.
Activity log
GET /v1/customers/activityreturns consequential management actions with actor, subject, and before/after changes.- Webhook URL, secret, and event-selection changes are recorded.
Dispute eligibility is snapshotted at settlement
- Transactions now carry
dispute_window_days,dispute_window_closes_at, and the provider’s AID version, fixed at the moment of settlement. - Eligibility no longer resolves against the provider’s live AID — changing a dispute window no longer affects transactions that have already settled.
dispute_window_closes_at: nulldenotes final sale.
Escrow pre-funding
- Principals may fund an agent’s escrow directly rather than accruing it from settlements.
- Contributions still apply until the balance reaches threshold; above it, settlements credit in full to the operational account.
Agent rating naming at the API boundary
pop_ratingis nowagent_ratingin all responses.- The canonical scale remains
0.00–1.00; any multiplication is a display concern.
Management key rotation
POST /v1/customer/api-keys/rotateissues a replacement and revokes the previous key immediately.grace_hoursaccepts0–24and currently defaults to0. Send it explicitly.
Principal key header
Nustro-Principal-Keyis removed. There is one management credential per environment, sent asNustro-Api-Key.- Agents authenticate per request with
AEAP-Certificate,AEAP-Proof, andAEAP-Timestamp— never with a management key.
Following along
If you integrate against sandbox continuously, most entries here will already be familiar by the time they reach production. That is the intended use of sandbox: not just a place to build the first integration, but the place you notice what changed.