# API Reference (/docs/api-reference)



The BeamCore HTTP API at `https://beamcore.b1m.ai` reads your organization's
transfers from any language. It authenticates with an API key (`b1m_…`) in the
`X-Api-Key` header.

It does not create transfers. Create them with an [SDK](/docs/sdk) or
[Beam Studio](/docs/studio), then read their status here.

Administering the account — creating, rotating and revoking those keys, and
reading credits and usage — is a separate API on a separate host. See the
[Account Management API](/docs/management-api).

New to Beam? Start with the [Developer Quickstart](/docs/developer-quickstart)
to create an API key and send your first transfer.

## Base URL [#base-url]

```text
https://beamcore.b1m.ai
```

## Authentication [#authentication]

Send your API key in the `X-Api-Key` header:

```http
X-Api-Key: b1m_...
```

A request without a valid key is refused with `401`. The transfer endpoints also
need a key that may read or create transfers (`transfers:read` or
`transfers:create`, such as the Console's read-only preset); any other key is
refused with `403`.

## Endpoints [#endpoints]

| Method | Path                               | Returns                                                                         |
| ------ | ---------------------------------- | ------------------------------------------------------------------------------- |
| `GET`  | `/transfers`                       | Your organization's transfers, newest first.                                    |
| `GET`  | `/transfers/{transfer_id}`         | One of your organization's transfers.                                           |
| `GET`  | `/transfers/{transfer_id}/receipt` | The fields an onchain receipt records for one of your organization's transfers. |
| `GET`  | `/auth/me`                         | Confirms that the key authenticates.                                            |

### List transfers [#list-transfers]

```bash
curl "https://beamcore.b1m.ai/transfers?status=completed&limit=10" \
  -H "X-Api-Key: $BEAM_API_KEY"
```

| Query parameter   | Default      |                                                                                                                |
| ----------------- | ------------ | -------------------------------------------------------------------------------------------------------------- |
| `limit`           | `20`         | Transfers per page, at most 100.                                                                               |
| `offset`          | `0`          | Transfers to skip.                                                                                             |
| `status`          | —            | Only transfers in this [status](/docs/transfers#transfer-statuses), such as `completed`.                       |
| `order_by`        | `created_at` | `created_at` or `completed_at`, newest first. With `completed_at`, transfers that have not finished come last. |
| `completed_after` | —            | An ISO 8601 timestamp: only transfers that finished after it.                                                  |

```json
{
  "transfers": [
    {
      "id": "0b7c4f1e-6d52-4a8e-9a0f-2f1c9e5d7a31",
      "transfer_key": "…",
      "status": "completed",
      "total_bytes": 1073741824,
      "bytes_transferred": 1073741824,
      "error_message": null,
      "metadata": {},
      "prism_excluded": false,
      "prism_exclusion_reason": null,
      "created_at": "2026-09-29T10:15:02.000Z",
      "started_at": "2026-09-29T10:15:03.000Z",
      "completed_at": "2026-09-29T10:16:41.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}
```

`completed_at` is set when a transfer finishes, whether it succeeded or not. To
pick up newly finished transfers, poll with `order_by=completed_at` and
`completed_after` set to the latest `completed_at` you have seen.

### Get one transfer [#get-one-transfer]

```bash
curl "https://beamcore.b1m.ai/transfers/$TRANSFER_ID" \
  -H "X-Api-Key: $BEAM_API_KEY"
```

`transfer_id` is the ID the SDK returned when it created the transfer; the
transfer's `transfer_key` works too. The response is one transfer object, as
below. A transfer that does not exist, or belongs to another organization,
returns `404` with `{"error": "transfer not found"}`.

### Get a transfer's receipt fields [#get-a-transfers-receipt-fields]

```bash
curl "https://beamcore.b1m.ai/transfers/$TRANSFER_ID/receipt" \
  -H "X-Api-Key: $BEAM_API_KEY"
```

Returns only the fields an onchain receipt records, about 340 bytes whatever the
transfer's size. The full transfer object grows with the transfer: its
`metadata` is over 100 KB for a 100 GB transfer. Readers with a response limit,
such as a [Chainlink CRE](/docs/integrations/chainlink-cre) workflow, use this
endpoint.

```json
{
  "id": "0b7c4f1e-6d52-4a8e-9a0f-2f1c9e5d7a31",
  "status": "completed",
  "total_bytes": 1073741824,
  "bytes_transferred": 1073741824,
  "completed_at": "2026-09-29T10:16:41.000Z",
  "plan_fingerprint": "5f0c…",
  "coordinate_checksum": "9a41…"
}
```

| Field                                                              |                                                                             |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `id`, `status`, `total_bytes`, `bytes_transferred`, `completed_at` | As in the [transfer object](#the-transfer-object).                          |
| `plan_fingerprint`                                                 | A hash of the transfer's plan, from its `metadata`, or `null`.              |
| `coordinate_checksum`                                              | A hash of the transfer's chunk coordinates, from its `metadata`, or `null`. |

`transfer_id` must be the transfer ID; `transfer_key` is not accepted here. A
transfer that does not exist, or belongs to another organization, returns `404`
with `{"error": "transfer not found"}`.

### The transfer object [#the-transfer-object]

| Field                                      |                                                                                                            |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `id`                                       | The transfer ID.                                                                                           |
| `transfer_key`                             | A second identifier for the transfer.                                                                      |
| `status`                                   | See [Transfer statuses](/docs/transfers#transfer-statuses).                                                |
| `total_bytes`                              | The transfer's size, in bytes.                                                                             |
| `bytes_transferred`                        | Bytes delivered so far.                                                                                    |
| `error_message`                            | Why the transfer failed, or `null`.                                                                        |
| `metadata`                                 | The transfer's metadata.                                                                                   |
| `prism_excluded`                           | `true` when the transfer does not count for PRISM, Beam's miner scoring.                                   |
| `prism_exclusion_reason`                   | Why it does not count: `not_eligible`, `review`, `storage_refused` or `incomplete`; `null` when it counts. |
| `created_at`, `started_at`, `completed_at` | Timestamps. `started_at` and `completed_at` are `null` until the transfer starts and finishes.             |

Transfer responses do not include the name you gave a transfer: there is no name
field, and `name` and `transfer_name` are removed from `metadata`.

### Check a key [#check-a-key]

```bash
curl https://beamcore.b1m.ai/auth/me \
  -H "X-Api-Key: $BEAM_API_KEY"
```

A valid key returns `200` with the prefix of the key you sent, in
`current_key_prefix`, and the number of your organization's active keys, in
`api_key_count`. It does not return your organization or the key's permissions;
see those under **API Keys** in the [Console](https://console.b1m.ai).

## Request samples [#request-samples]

The [endpoint pages](/docs/api) have a request panel for each of these
endpoints, which builds a sample in cURL, JavaScript, Go, Python, Java, C#, and
Rust. The tables above describe the parameters and response fields.
