Documentation
A bridge you can inspect.
Rivetport transforms one authorized GET request into one upstream GET request, then returns only explicitly mapped JSON fields. Astra can propose fields. Your approval and declared checks determine what can be published.
1. Connect
Create a workspace, name a bridge, and upload the old and new OpenAPI 3.0.x or 3.1.x JSON or YAML documents. Select an actual GET operation from each. Unselected operations are not exposed. Parsing, unsupported schema, and serialization errors must be resolved before publication.
Enter the upstream HTTPS origin. Place the exact challenge token at the displayed verification path on that origin, then verify control. Configure a dedicated service credential or select a public upstream. Everyone holding a bridge key must be allowed to access the same upstream data. Per-user authorization delegation is unsupported.
2. Review
Map old response fields to new response fields, including nesting, flattening, bounded arrays of objects, and exact enum values. Map route parameters and compatible query parameters. Review success and error statuses separately. Missing fields are not substituted with null or invented values.
Provide request paths and independently expected JSON responses. Test inputs must be authorized. Examples are sent to Astra only when you explicitly opt in, and potential credentials are redacted. Model analysis is optional to deterministic execution; a provider failure does not affect published releases.
Evaluation mapping analysis has a shared budget of 20 reservations per UTC day, for trials only. Paid allowances follow the paid billing period. Each reservation admits at most 24,000 input UTF-8 bytes (and characters) and 4,000 output tokens. Reservations count before contacting Astra, including failed or cancelled requests. When this daily budget is exhausted, trial analysis is unavailable until 00:00 UTC; manual mapping and published bridges continue to work. There are no automatic model retries. Workspace deletion does not reset this trial budget.
3. Publish
Save the draft, build its immutable release, run its declared live checks, approve it, then publish. Saving a change invalidates prior approval and test evidence for the new draft. Test and production use the same mapping implementation and credential versions. A live check batch has a 30-second total budget and an eight-second limit per upstream request. Checks that cannot start within the batch budget report CHECK_BUDGET_EXCEEDED; split slower batches before retrying. All admitted checks count toward the request allowance.
Issue a scoped bridge key. It is shown once. Keep it in your server secret store; never put it in a browser bundle. The application displays the actual managed endpoint and request example after publication.
Two ways to route traffic
Managed endpoint: configure the integration to use the displayed bridge base URL and bearer credential. This changes client configuration.
Your controlled ingress: keep the original hostname, paths, and existing authentication checks. After authorizing each request, your ingress forwards it to the managed bridge with its own scoped bridge key. It must strip caller-supplied upstream credentials and preserve approved route/query parameters. Test on isolated infrastructure before moving real traffic. Rivetport does not change your DNS.
Supported contract
- Read-only public HTTPS JSON REST APIs, with object response roots and bounded arrays of objects.
- One selected GET operation pair per bridge; up to three bridges per workspace.
- Scalar path parameters and explicitly compatible form query serialization.
- Field selection, renaming, nesting, flattening, and exact approved scalar value mappings.
- Local document references only; no remote reference downloads, filesystem references, or YAML aliases.
Unsupported schema keywords and selected operation features are blockers, including root arrays, nested arrays, unions beyond the supported nullable type, arbitrary expressions, and implicit conversions. Pagination is supported only when the contracts have the same semantics; page numbers cannot become cursors by renaming. JSON schema matching alone does not establish business equivalence.
Operational errors
Authentication failures return 401. Paused or unavailable bridges return 503. Exhausted quotas or concurrency return 429 with retry guidance. Upstream, mapping, or contract failures return 502; timeouts return 504. These bridge-level errors may differ from the old API. Valid mapped business errors retain their declared error status. Live upstream requests are not retried or cached.
Rotation and rollback
Create a replacement integration key, install it at your ingress or client, verify it, then revoke the previous key. Pausing blocks new admissions. Already admitted requests may finish. Resume restores admission while preserving limits. Rollback selects a previously tested, approved release atomically. Each request uses one coherent release. Each bridge retains at most 20 releases, credential versions, and destination versions. When space is needed, the oldest inactive releases and unused configuration are retired. The active release and its credentials are preserved. Retired releases are no longer available for rollback.