Hosted sites

Hosted sites API

The public endpoints a hosted site's pages call: site status, page views, forms, events, resources and media. They need no key. The site's slug in the address is how Bynefit knows which site you mean.

Conventions

Which sites answer

Every endpoint decides the same way whether a site is open to the public. A live site is published, not suspended, not archived or deleted or waiting for deletion, and belongs to a Space that is active and not being deleted. Where an endpoint needs a live site, an unknown slug and a site that is not live get the identical answer (form submit also answers a malformed slug with Invalid site), so nobody can learn which sites exist by asking.

Only a Space that is switched off or being deleted stops serving its sites. Turning off public events hides the events endpoint and the events block, and nothing else.

Site status

curl "https://bynefit.com/api/sites/runtime-status?slug=my-site"

const res = await fetch("https://bynefit.com/api/sites/runtime-status?slug=my-site");
const { ok, status } = await res.json();
if (ok && status.is_maintenance) console.log(status.maintenance_message);

{
  "ok": true,
  "slug": "my-site",
  "kind": "hosted",
  "status": {
    "is_suspended": false,
    "is_maintenance": false,
    "maintenance_message": null,
    "published": true,
    "skip_branding": false,
    "badge_href": null
  }
}

• host works instead of slug for a verified custom domain. If both are sent, slug wins.
• A site that is archived or deleted, or a slug that does not exist, answers 200 with {"ok": false, "error": "Site not found"}. A suspended, unpublished or in-maintenance site is still reported, so the runtime can show its page.
• badge_href is the link the "Powered by Bynefit" badge should use. It is null for most sites. When the Space that owns the site is a Bynefit partner whose link is switched on, it is that partner's link on bynefit.com, and the badge should use it in place of the general link.
• Cached for 30 seconds.

Page views

Always answers a 1 by 1 transparent GIF, whatever you send, so it can be fired as an image: new Image().src = .... It stores the page path (without query string or fragment), the referring address, the browser's user agent and a hash of the visitor's IP address. No cookies and no raw IP address. Views are recorded for any site that has not been archived or deleted, including one that is unpublished or suspended; an archived or deleted site records nothing. Visitors or sites that send too many views in a minute have the extra ones dropped silently. The totals are shown to the Space owner in the dashboard; there is no endpoint to read them.

Form definition

{
  "ok": true,
  "form": {
    "id": "frm_AbC123xYz",
    "name": "Contact us",
    "team_name": "Riverside Aid",
    "confirmation_message": null,
    "fields": [
      { "id": 12, "label": "Email", "type": "email", "required": true, "placeholder": null, "help": null, "options": null },
      { "id": 13, "label": "Topic", "type": "dropdown", "required": false, "placeholder": null, "help": null, "options": ["Housing", "Food", "Other"] }
    ]
  }
}

Field types: text, textarea, email, tel, number, date, dropdown, checkbox, radio, section_header, hidden. Only active forms answer, and only while the form is open: a form tied to a site needs that site live, and a Space form needs an active Space. Anything else answers {"ok": false, "error": "Form not found"}, the same as an unknown form. A malformed id answers Invalid form id. Cached for 60 seconds.

Submit a form

Send a form-encoded body (application/x-www-form-urlencoded or multipart), not JSON. A value is matched to a field by field_{id}, or by the field's label lowercased with anything that is not a letter or number turned into _ (so Full name is full_name). Checkbox groups can repeat the name (topic[]); the values are joined with a comma. Names that match no field are ignored.

curl -X POST https://bynefit.com/api/sites/my-site/forms/frm_AbC123xYz/submit \
  -d "full_name=Sam Rivera" \
  -d "email=sam@example.com" \
  -d "message=Do you have evening hours?"

const res = await fetch("https://bynefit.com/api/sites/my-site/forms/frm_AbC123xYz/submit", {
  method: "POST",
  headers: { Accept: "application/json" },
  body: new URLSearchParams({
    full_name: "Sam Rivera",
    email: "sam@example.com",
    message: "Do you have evening hours?"
  })
});
const result = await res.json();
if (!result.ok) console.error(result.error, result.missing);

$ch = curl_init("https://bynefit.com/api/sites/my-site/forms/frm_AbC123xYz/submit");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'full_name' => 'Sam Rivera',
        'email' => 'sam@example.com',
        'message' => 'Do you have evening hours?',
    ]),
]);
$result = json_decode(curl_exec($ch), true);

{ "ok": true, "message": "Thanks! We received your submission." }

The message is the form's own confirmation message when it has one. Nothing else comes back: no submission id and no echo of what was sent.

Forms that ask for an email code

The schema answer carries auth_mode. When it is email_otp, a submit without a confirmed email answers 403 with "code": "email_code_required". The Bynefit form module handles this for you: it shows a short first step, sends the code, and unlocks the form with the confirmed address already in the first email field. A form that asks people to sign in (bynli_login) answers 403 with "code": "auth_required" and the address of its Bynefit form page instead.

Form-encoded body with action=send and email: a six digit code is emailed and {"ok": true, "challenge": "..."} comes back. Codes are limited to one a minute per address and form, 5 an hour per address and 200 an hour per form, and each caller address is throttled; over a limit answers 429. Then action=verify, challenge and code: {"ok": true, "ticket": "...", "email": "..."}. Five wrong tries lock a code. Send the ticket as _bynli_otp with the submit. It is a bearer token: good for an hour, for that form only, for any number of submissions. The submission is stored under the confirmed address, and the form's first email field is replaced by it. An unknown or non-email-code form answers 404 or 400, and an expired ticket answers 403 with email_code_required so the form asks again.

What a submission sets off

• The answers are saved with the form. A lead form also creates a contact.
• The form.submitted webhook fires. It carries the form's id and name, never the answers. See Webhooks.
• Unless it is a registration form, your Space's leaders get a follow-up task and a notification. This is capped at 20 a hour per Space; past the cap the answers are still saved.
• If the person gave an email address (email, email_address or _respondent_email), they get your autoresponder if the form has one, or a short receipt. A malformed address is ignored and the submission still goes through.
• A hidden field named _bynli_hp is a bot trap. If it is filled in, the answer is {"ok": true} and nothing is saved.

The server only checks that required fields are filled. It does not check that an email looks like an email, that a number is a number, or that a dropdown value is one of the options, so validate in the page as well.

Events

limit is 1 to 50 (default 5). scope is upcoming (default) or past. Only a live site answers, and only when the Space has turned on public events. Otherwise the answer is the same 404 {"ok": false, "error": "site_not_found"} as for an unknown or malformed slug, so the answer never reveals which sites exist. Cancelled and draft events are left out. upcoming covers today up to two years ahead and past reaches back two years, newest first.

curl "https://bynefit.com/api/sites/my-site/events?limit=3&scope=upcoming"

const res = await fetch("https://bynefit.com/api/sites/my-site/events?limit=3&scope=upcoming");
const { events, count } = await res.json();
for (const e of events) console.log(e.event_date_iso, e.title);

$data = json_decode(file_get_contents("https://bynefit.com/api/sites/my-site/events?limit=3&scope=upcoming"), true);
foreach ($data['events'] as $e) {
    echo $e['event_date_iso'], ' ', $e['title'], "\n";
}

{
  "ok": true,
  "team": { "slug": "riverside-aid", "name": "Riverside Aid" },
  "scope": "upcoming",
  "count": 1,
  "events": [
    {
      "id": 481,
      "title": "Free tax help night",
      "description": "Bring your documents.",
      "event_date": "2026-11-04 18:00:00",
      "event_date_iso": "2026-11-04T18:00:00+00:00",
      "location": "Community hall",
      "tickets_enabled": true,
      "ticket_price": 0.0,
      "ticket_name": "General",
      "tickets_sold": 12,
      "tickets_limit": 40
    }
  ]
}

Errors use real codes: 404 site_not_found for an unknown, malformed or gated site (one answer for all, so it never reveals which sites exist), and 500 server_error. At most 50 events come back. Cached for 60 seconds. Sold counts and limits come with every event listed. There are no attendee lists or buyers in the answer. Ticket and detail links on a hosted site go to the event's page on Bynefit.

Ready-made blocks

Returns finished HTML in a JSON field, for dropping into a page. Any other kind, or any site that is not live, answers 404 with {"ok": false, "error": "Not found"}, the same body for each, and so does the events block when the Space has not turned on public events. Cached for 60 seconds.

The HTML is escaped on our side. Set it with innerHTML only for these two endpoints, never for text from anywhere else.

Media library

{
  "ok": true,
  "site": "my-site",
  "count": 1,
  "media": [
    {
      "id": 7,
      "filename": "team.jpg",
      "url": "https://my-site.site.bynefit.com/media/team.jpg",
      "mime_type": "image/jpeg",
      "size_bytes": 184233,
      "uploaded_at": "2026-10-08 09:12:44"
    }
  ]
}

Newest first, with no paging, so a big library is a big answer. Not cached. An unknown, malformed or not-live site answers {"ok": false, "error": "Site not available"}.

Secure requests

The one endpoint here that is not open to every origin. It forwards a page's call to the service the site owner chose and adds the owner's secret on the server, so a page can use a paid or private API without holding its key. It accepts only the methods the owner allowed, answers only the site's own addresses, and has per-visitor, per-minute and per-day limits. The full contract, limits and error codes are in Keeping keys safe on a hosted site.

What is not here

• No way to read form answers, visitor totals, members, payments, donations or ticket buyers from a page.
• Donations and tickets are links to Bynefit's own pages, not API calls.
• Managing a site (publishing, uploading media, editing the document) is done in the Bynefit Sites app and the dashboard, not through a public API.
• Planned A key-based API for a site's shop, products and orders.