House-tops API

Build scripture-centered apps on top of House-tops.

1. Choosing an auth method

API Key — X-API-Key

Read-only access to public data (feed, verses, graph). No user context. Best for embeds, dashboards and integrations.

OAuth2 — Authorization: Bearer

Act on behalf of a House-tops user with their consent, limited to granted scopes. Best for third-party apps that read or write user data.

JWT — Authorization: Bearer

First-party tokens from /api/v1/auth/token/. For the official House-tops apps only.

2. Public endpoints (no auth)

Rate limited to 300/hour per IP, or 5000/hour with an API key.

GET /api/v1/public/feed/ curl -H "X-API-Key: ht_your_key" https://house-tops.com/api/v1/public/feed/ GET /api/v1/public/verses/?book=rom&chapter=8 curl "https://house-tops.com/api/v1/public/verses/?book=rom&chapter=8" GET /api/v1/public/graph/ curl "https://house-tops.com/api/v1/public/graph/?limit=500"

3. OAuth2 flow

# 1. Send the user to the consent screen GET /oauth/authorize/?client_id=CLIENT_ID&response_type=code&scope=reflections:read&redirect_uri=YOUR_URI # 2. Exchange the returned ?code=... for a token curl -X POST https://house-tops.com/oauth/token/ \ -d grant_type=authorization_code \ -d code=AUTH_CODE \ -d redirect_uri=YOUR_URI \ -d client_id=CLIENT_ID \ -d client_secret=CLIENT_SECRET # 3. Call the API with the access token curl -H "Authorization: Bearer ACCESS_TOKEN" \ https://house-tops.com/api/v1/reflections/

4. Scopes

Scope	Grants
`read`	Read public data and your profile
`reflections:read`	Read your private reflections
`reflections:write`	Create and edit reflections
`sermons:read`	Read your sermon notes
`sermons:write`	Create sermon notes
`post`	Publish posts on your behalf
`connections:write`	Create verse connections

A request with a token missing the required scope returns 403.

5. Webhooks

Subscribe to events: post.created, post.upvoted, connection.created, comment.created. Each delivery is a POST with headers X-HouseTops-Event and X-HouseTops-Signature (HMAC-SHA256 of the raw body).

Verify the signature (Python):

import hmac, hashlib def verify(body: bytes, signature: str, secret: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature)

A webhook is auto-disabled after 10 consecutive delivery failures.

6. Rate limits

Context	Limit
Anonymous	100 / hour
Public API (per IP)	300 / hour
Per API key	5000 / hour
Authenticated user	1000 / hour

Interactive API reference (Swagger) →