GET /ext/transaction/{rid}

/ext/transaction/{rid} is the reconciliation endpoint for the OneStream flavor. Every POST in this API accepts an rid in its body and, on success, stores the response for at least 24 hours. If the original response never reached your integration (timeout, dropped connection, worker crash, redeploy in the middle of the request), you can call this endpoint with the same rid before deciding whether to retry. A 200 tells you the write succeeded and hands you the original response. A 404 tells you the write never reached the panel and it is safe to retry with the same rid.

The endpoint does not exist on the underlying v1 API. It is served locally by the OneStream dialect, which looks the rid up in the panel's idempotency store, scopes the lookup to the calling key, and returns either the cached response or a uniform 404. Do not build workflows around it, but do call it in your retry code before any repeat POST whose result you did not observe.

Endpoint

GET https://<your-panel-domain>/panel-api/onestream/ext/transaction/{rid}

The {rid} path segment is the exact string you sent in the body of the original write, URL-encoded. Allowed characters are unreserved URL characters: letters, digits, and ., _, ~, -. A request whose {rid} contains anything else returns a uniform 404 without touching the idempotency store.

Authentication

Send the API key in X-Api-Key, X-Auth-User, or Authorization: Bearer. See the OneStream overview.

Required scope

None. Any authenticated key can look up transactions that it created. The lookup is scoped to the caller's key: an rid created by another key is indistinguishable from one that does not exist. Both return 404 with {"error": "Not Found"}.

Path parameters

Name Type Description
rid string The exact receipt identifier you sent in the body of the write. URL-encode it if it contains reserved characters.

Response

Two shapes, on two status codes.

Found (HTTP 200)

The cached transaction wraps the original response body under a response key. The wrapper carries the rid echoed back, a transaction_status string, and the original HTTP status the write returned.

{
  "rid": "onestream-idem-1",
  "transaction_status": "success",
  "http_status": 201,
  "response": {
    "line_id": "550e8400-e29b-41d4-a716-446655440000",
    "expire_at": "2026-09-08T16:39:45+00:00",
    "transaction_amount": 100,
    "rid": "onestream-idem-1"
  }
}
Field Type Description
rid string The receipt identifier echoed from the request.
transaction_status string Fixed value "success". The endpoint only returns 200 when a stored transaction exists; failures are not cached and are not visible here.
http_status int HTTP status the original write returned.
response object or null The parsed JSON body of the original write. null when the stored body was not valid JSON (never happens for writes this API produces).

Not found (HTTP 404)

{"error": "Not Found"}

Returned in every one of these situations, deliberately indistinguishable:

  • No transaction with that rid exists for the calling key.
  • The rid exists but was created by a different key on this panel.
  • The rid path segment contains characters outside the allowed set.
  • The request did not present a valid API key.

The lack of distinction is deliberate. If the endpoint told you the difference between "your rid does not exist" and "someone else's rid does", it would let a caller enumerate other integrators' transaction identifiers.

Recovery workflow

The standard shape of a safe retry loop for any POST in this API is:

  1. Pick a stable rid per business operation (an invoice number, a webhook event id).
  2. Send the POST with rid in the body.
  3. If you see the response, you are done. Store the response.
  4. If the connection timed out or dropped before you saw the response, call GET /ext/transaction/{rid} before doing anything else.
  5. If the lookup returns 200, treat the write as complete and use the returned response as if the original POST had returned it.
  6. If the lookup returns 404, the write never reached the panel. Retry the POST with the same rid. The panel will process it exactly once, and any subsequent lookup will return the response.

Examples

cURL

curl -H "X-Api-Key: <your-api-key>" \
     "https://<your-panel-domain>/panel-api/onestream/ext/transaction/onestream-idem-1"

PHP raw

$rid = 'onestream-idem-1';
$url = 'https://<your-panel-domain>/panel-api/onestream/ext/transaction/' . rawurlencode($rid);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Api-Key: <your-api-key>']);
$body = json_decode(curl_exec($ch), true);
$http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http === 200) {
    echo 'original http_status: ' . $body['http_status'] . PHP_EOL;
    print_r($body['response']);
} elseif ($http === 404) {
    echo "not seen, safe to retry with the same rid\n";
}

Python raw

import requests
from urllib.parse import quote

rid = "onestream-idem-1"
url = (
    "https://<your-panel-domain>/panel-api/onestream/ext/transaction/"
    + quote(rid, safe="")
)
r = requests.get(url, headers={"X-Api-Key": "<your-api-key>"}, timeout=30)

if r.status_code == 200:
    payload = r.json()
    print("original http_status:", payload["http_status"])
    print(payload["response"])
elif r.status_code == 404:
    print("not seen, safe to retry with the same rid")

Errors

HTTP Error slug When it happens How to fix
404 not_found The rid was not created by this key, does not exist, contains invalid characters, or the request presented no valid API key. Retry the original POST with the same rid if you never observed its response. Verify you are calling with the same key that made the original write.
429 rate_limited The per-key or per-IP rate limit was hit. Response carries Retry-After and X-RateLimit-* headers. Back off for the number of seconds in Retry-After.
403 api_disabled An admin has turned the Panel API off for this panel. Ask the admin to re-enable it.

See also