ByteBeacon

Quickstart

Two curls from zero to a working form.

$BASE below is the API origin — https://api.bytebeacon.com in production, http://localhost:8080 if you are running it yourself. Set it once and paste the rest verbatim:

bash
BASE=https://api.bytebeacon.com

Every API URL in these docs is on that origin. The dashboard is a different host (https://app.bytebeacon.com) and serves no API path — pointing a form or a curl at it gets you nothing.

1. Create an account (no signup form, no verification wait)#

bash
curl -s -X POST $BASE/v1/accounts \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]"}'

Response (the secret_key is shown exactly once — store it):

json
{"success":true,"data":{"user_id":"usr_…","organization_id":"org_…",
 "project_id":"prj_…","form_id":"form_…","secret_key":"bb_sk_…"}}

2. Put the form on any website#

The form_id is public — safe to publish; it only lets people send you submissions. Never publish the secret_key.

This snippet goes on your site, so there is no shell to expand $BASE: write the API origin out in full (https://api.bytebeacon.com/s/…). The form posts cross-origin from wherever you host it, which is deliberate — ingest accepts any origin.

html
<form action="$BASE/s/YOUR_FORM_ID" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="checkbox" name="botcheck" style="display:none">
  <input type="hidden" name="redirect" value="https://yoursite.com/thanks">
  <button type="submit">Send</button>
</form>

3. Send a test submission#

The HTML form above posts application/x-www-form-urlencoded, which is what a browser sends. From a terminal or an agent, JSON is easier — but curl -d defaults to urlencoded, so spell the header out or you get 400 content_type_mismatch:

bash
curl -s -X POST $BASE/s/YOUR_FORM_ID \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","message":"hello"}'
json
{"success":true,"data":{"id":"sub_…","stored":true,
 "fields_received":["email","message"],"message":"submission received"}}

fields_received echoes exactly what was stored — if it does not match what you sent, your encoding is wrong. GET /v1/submissions/{id} reads that row back.

4. Read submissions#

bash
curl -s "$BASE/v1/submissions?form_id=YOUR_FORM_ID" \
  -H "Authorization: Bearer bb_sk_…"

See the API reference for pagination, CSV export, and error codes.