Developers

API reference

The REST API lets your church's own tools read the gallery, keep missionaries and newsletters up to date, post announcements, and read or feed giving. It's JSON over HTTPS, and every request uses an API key for one church.

Base URL and authentication #

https://missionarylane.org/api/v1

A self-hosted gallery has the same API in its own Supabase project, at https://your-project.supabase.co/functions/v1/api.

Send your API key as a bearer token on every request:

curl https://missionarylane.org/api/v1/missionaries \
  -H "Authorization: Bearer $ML_API_KEY"

• Keys look like ml_live_ followed by 32 letters and digits. An admin or owner creates them in the admin; see API keys and scopes.
• A key belongs to one church. Everything you read or write is that church's data.
• Each endpoint needs a scope. A write scope includes the matching read scope.
• Restricted missionaries come back with their public alias and an r-… slug only, exactly as the gallery shows them.

Conventions #

Errors #

Errors use the HTTP status and a JSON body with a code and a plain-language message:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key can't do that. It needs the giving:read permission.",
    "details": { "required": ["giving:read"] }
  }
}

Rate limits #

Each key can make 120 requests a minute by default. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time), and a limited response adds Retry-After.

Paging and caching #

• Lists take limit and cursor. Pass the cursor from one page to get the next.
• Responses carry an ETag. Send it back in If-None-Match and you get 304 Not Modified when nothing changed.
• Money is in cents (amount_cents), dates are YYYY-MM-DD and months are YYYY-MM.

Endpoints #

This list is read from the published OpenAPI description, openapi.json, which you can also load into your own tools.