API reference — Belfort

Authentication

Authenticate every request with your secret key in the Authorization header. Keep secret keys server-side — never ship them in an app binary.

curl

$ curl https://api.belfort.dev/v1/paywalls \
    -H "Authorization: Bearer sk_live_9f2c…"

The base URL is https://api.belfort.dev/v1. All timestamps are ISO 8601 in UTC.

Errors

Belfort uses standard HTTP status codes: 2xx for success, 4xx for client errors, and 5xx for server errors. Error bodies include a machine-readable code and a human message.

Paywalls

GET/v1/paywalls

List every paywall in a product, newest first.

Parameter	Type	Description
`product`	string	Product ID to filter by, e.g. caldera-ios.
`status`	string	Optional. One of live, paused, draft, scheduled.
`limit`	integer	Page size, 1–100. Defaults to 20.

200 OK

{
  "data": [{
    "id": "pw-onboarding-d0-story",
    "name": "Onboarding — Storyboard",
    "status": "live",
    "cvr": 10.07,
    "mrr_contribution": 99800
  }],
  "has_more": false
}

GET/v1/paywalls/:id

Retrieve a single paywall by ID, including its template and current experiment.

Parameter	Type	Description
`id`	string	The paywall ID.

POST/v1/placements/:key/resolve

Resolve a placement to the paywall a given user should see. This is what the SDK calls under the hood.

Parameter	Type	Description
`key`	string	Placement key, e.g. session_limit.
`user_id`	string	Stable end-user identifier for consistent bucketing.

200 OK

{
  "paywall_id": "pw-onboarding-d0-story",
  "variant": "B",
  "experiment_id": "exp-onb-layout"
}

Experiments

GET/v1/experiments

List experiments across a product with their significance and lift.

Parameter	Type	Description
`product`	string	Product ID to filter by.
`status`	string	Optional. running or complete.

POST/v1/experiments/:id/promote

Promote a variant to 100% of traffic and end the experiment.

Parameter	Type	Description
`id`	string	The experiment ID.
`variant`	string	The variant to promote, e.g. B.

Events

POST/v1/events

Track a custom event to trigger placements or attribute revenue.

Parameter	Type	Description
`user_id`	string	The end user the event belongs to.
`name`	string	Event name, e.g. free_sessions_exhausted.
`properties`	object	Optional key/value metadata.