> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Stream Overview

> Drop-in Stedi Core 2023-08-01 endpoints for your EDI 835, 837, and 277 transaction stream.

Cair exposes your processed EDI transaction stream through a set of endpoints that are **wire-compatible with [Stedi Core `2023-08-01`](https://www.stedi.com/docs/healthcare/api-reference)**. Any client or SDK written against Stedi Core — including Stedi's own SDKs and the `listTransactions`, `pollTransactions`, `getTransaction`, and document-download operations — can be pointed at Cair instead, without changing how requests or responses are shaped.

<Note>
  These endpoints are read-only and expose transactions Cair has already received or produced for your organization. They never call Stedi live and never generate X12 on demand — whatever Cair has ingested is the source of truth.
</Note>

## Base URL

All endpoints live under a versioned prefix that mirrors Stedi's:

```text theme={null}
https://forecaster.cairhealth.com/api/stedi/2023-08-01
```

To migrate an existing Stedi integration, change **only** the base URL (from `https://core.us.stedi.com/2023-08-01`) and the credential. The paths (`/transactions`, `/polling/transactions`, `/transactions/{transactionId}`, `/transactions/{transactionId}/input`, `/transactions/{transactionId}/output`) are identical.

## Authentication

Every endpoint uses the same Cair authentication as the rest of this API reference:

1. Exchange your `clientId` / `clientSecret` for an access token at [`POST /api/token`](/api-reference/endpoint/token).
2. Send that token as a Bearer credential: `Authorization: Bearer <accessToken>`.
3. Your organization must have the `api-access` feature enabled. Tokens without it receive `401`.

Your access token is scoped to a single organization, so every endpoint automatically returns only your organization's transactions. There is no `organizationId` parameter.

```bash theme={null}
curl "https://forecaster.cairhealth.com/api/stedi/2023-08-01/transactions?pageSize=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Using a Stedi SDK

Two settings are all that change:

* **Base URL / endpoint** — set it to `https://forecaster.cairhealth.com/api/stedi/2023-08-01`.
* **API key / Authorization value** — set it to `Bearer <your Cair access token>` (the literal `Bearer` prefix is required).

The exact configuration key depends on your SDK version; consult its documentation for how to override the base URL. The example below shows the shape using the operations from the Stedi Core SDK.

```ts theme={null}
// Point any Stedi Core 2023-08-01 client at Cair and pass the Cair token.
const stedi = Stedi({
  apiKey: `Bearer ${process.env.CAIR_ACCESS_TOKEN}`,
  baseUrl: 'https://forecaster.cairhealth.com/api/stedi/2023-08-01',
});

// Same calls as against Stedi:
for await (const transaction of stedi.core.listTransactions({ transactionSetId: '835' })) {
  console.log(transaction.transactionId, transaction.direction);
}

const x12 = await stedi.core.getTransactionInput('c1f2e3d4a5b6c7d8e9f0a1b2c3d4e5f6');
```

## What transactions are included

A transaction is visible to your organization if it was ingested under your account, regardless of how it arrived:

| Source | Description |
| :- | :- |
| `stedi` | Transactions received from or submitted to payers through Cair's Stedi clearinghouse connection, matched to your billing providers by NPI / EIN. |
| `upload` | X12 files your team uploaded to Cair. |
| `eob-conversion` | Historical EOB / X12 data converted into Cair. |

Uploaded and converted X12 preserve the **business date** from the file's `GS04` header as `processedAt`, so it can be well before the time the file was imported.

## Pagination

The list and poll endpoints both return an opaque `nextPageToken`. Tokens are:

* **Stateless and encrypted** — they encode a keyset position, not a database row id.
* **Organization-bound** — a token minted for one organization is rejected for another.
* **Filter-bound** (list only) — reusing a `pageToken` with a different filter set returns `400`.

There is no offset/`page` paging. Always request the next page with the returned `nextPageToken` and stop when it is absent (list) or when you decide to stop polling (poll).

## Errors

Errors use Stedi's envelope of `{ "message": "...", "code": "..." }`:

| Status | `code` | Meaning |
| :- | :- | :- |
| `400` | `BadRequestException` | Invalid query parameter, cursor, or filter combination. |
| `401` | `UnauthorizedException` | Missing, invalid, or insufficiently scoped credential. |
| `404` | `ResourceNotFoundException` | The transaction or artifact does not exist for your organization. |
| `500` | `ServiceException` | Unexpected server error. |

`404` is deliberately returned for both "does not exist" and "not yours" so the endpoints never reveal the existence of another organization's transactions.

## Compatibility notes

* `partnershipId`, `sender`, and `receiver` list filters are accepted for compatibility but ignored — all transactions use Cair's shared Stedi connection.
* Only `input` and `output` artifacts are surfaced in `artifacts[]`; their `url` values point back at Cair's download endpoints (see [Get transaction input](/api-reference/endpoint/stedi/get-transaction-input)).
* The list and poll endpoints return the same `TransactionSummary` object, exactly as Stedi's `TransactionSummary` schema defines it.

## Endpoints

<CardGroup cols={2}>
  <Card title="List transactions" icon="list" href="/api-reference/endpoint/stedi/list-transactions">
    Browse the transaction history with filters and cursor pagination.
  </Card>

  <Card title="Poll transactions" icon="arrows-rotate" href="/api-reference/endpoint/stedi/poll-transactions">
    Incrementally follow the stream without gaps.
  </Card>

  <Card title="Get a transaction" icon="magnifying-glass" href="/api-reference/endpoint/stedi/get-transaction">
    Fetch one transaction summary by id.
  </Card>

  <Card title="Get transaction input" icon="file-import" href="/api-reference/endpoint/stedi/get-transaction-input">
    Download the original input document (X12).
  </Card>

  <Card title="Get transaction output" icon="file-export" href="/api-reference/endpoint/stedi/get-transaction-output">
    Download the translated JSON document.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.