API Reference

The flashbay API gives you programmatic access to remote MCU development boards. Flash firmware, open serial consoles, and manage sessions — all over HTTPS and WebSocket.

Base URL

https://api.fbay.io/v1/

All endpoints are prefixed with /v1/. Responses are JSON unless otherwise noted.

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer key_cxxxxxxxxxxxxxxxxxxxxxxxxx

Create API keys in the web UI or via the CLI. Keys inherit your account's tier and credit balance.

Common patterns

Sessions

The typical workflow is:

1. List boards — find an available board type
2. Create session — reserves a board and starts billing
3. Flash firmware — upload a .bin file to the board
4. Serial console — open a WebSocket for real-time serial I/O
5. End session — releases the board and stops billing

Sessions transition through states: pending → allocating → active ⇄ idle → ended.

Credits

Every session consumes credits from your account balance. Credits are deducted while a session is active. Check your balance via the /v1/auth/me endpoint.

Power cycling

If your firmware hangs, you can power-cycle the board without ending the session. This toggles USB power to the physical device.

Errors

All errors return a JSON body with an error field:

{
  "error": "insufficient credits"
}

Status	Meaning
400	Bad request — check your parameters
401	Not authenticated — check your API key
403	Forbidden — account disabled or insufficient tier
404	Resource not found
409	Conflict — e.g. board already in use
429	Rate limited — slow down
500	Server error

Rate limits

Public endpoints are rate-limited to 2 requests/second with a burst of 10. Authenticated endpoints are not rate-limited.

WebSocket

The serial console uses a WebSocket connection:

wss://api.fbay.io/v1/sessions/{id}/serial?token=key_cxxxxxxxxxxxxxxxxxxxxxxxxx

Data is exchanged as binary frames (raw serial bytes).

SDKs & tools

• CLI — fbay command-line tool
• Python SDK — pip install flashbay
• GitHub Action — flashbay-dev/action

Browse the endpoints in the sidebar for full request/response details.