House-tops has a public REST API so developers can build on top of the platform. This is a quick orientation; full reference lives in the developer documentation and the interactive API explorer.
Ways to authenticate
- Public endpoints — read-only data (feed, verses, graph) at
/api/v1/public/needs no auth. - API keys — app-level access for server-to-server calls. Send your key in the
X-API-Keyheader. - OAuth2 — for acting on behalf of a user. The user authorizes your app and you receive a scoped access token.
Get started
1
Open the Developer Portal and register an app.
2
Create an API key for server-side calls, or note your OAuth2 client ID and secret for user authorization.
3
Call an endpoint. For example, fetch the public feed:
GET /api/v1/public/feed/
— or, with a key —
curl -H "X-API-Key: YOUR_KEY" https://house-tops.com/api/v1/…
— or, with a key —
curl -H "X-API-Key: YOUR_KEY" https://house-tops.com/api/v1/…
Scopes and webhooks
When a request is OAuth-authenticated, endpoints are gated by the scopes the
user granted. You can also register webhooks to receive events; deliveries are
signed with an X-HouseTops-Signature HMAC header so you can verify them.
🔑 See OAuth and API keys for how
authorization and revocation work from the user's side.