API Reference

Read your transfers over HTTP: the BeamCore base URL, authentication, and the transfer endpoints.

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 or Beam 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.

New to Beam? Start with the Developer Quickstart to create an API key and send your first transfer.

Base URL

https://beamcore.b1m.ai

Authentication

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

X-Api-Key: b1m_...

A request without a valid key is refused with 401. The transfer endpoints also need a key that may create transfers; any other key is refused with 403.

Endpoints

Method	Path	Returns
`GET`	`/transfers`	Your organization's transfers, newest first.
`GET`	`/transfers/{transfer_id}`	One of your organization's transfers.
`GET`	`/auth/me`	Confirms that the key authenticates.

List transfers

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, 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.

{
  "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

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"}.

The transfer object

Field
`id`	The transfer ID.
`transfer_key`	A second identifier for the transfer.
`status`	See 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

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.

Request samples

The endpoint pages 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.

On this page