Getting started

Use the API to read your organization's events and guests from another system, such as a CRM, and to send a single-guest reminder when you need to test email and cancel links. Every route is under /rest/v1 and returns JSON. Most routes are GET; sending a guest reminder uses POST.

You need an API key first. Owners and Organization Admins create one from My organization. Copy it when it appears. WeHabit shows the full key once.

Call the API

Send the key in the Authorization header. The host is the same one you use for Leaders.

curl "https://wehabit.mx/rest/v1/events" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

A successful response looks like this:

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 0,
    "totalPages": 0
  }
}

data is the current page of events. pagination.total is how many events match the filters, not just this page.

Replace <API_KEY> with the key you copied. Do not send it as a query parameter. For GET requests, do not put a JSON body on the request; Content-Type is not required. For POST (guest reminder), send JSON with Content-Type: application/json.

Pass query parameters

Filters, paging, and sort order go in the URL query string.

Rule	Example
Start the query with ?	/rest/v1/events?status=published
Join parameters with &	?status=published&limit=20
Omit a parameter to use its default	No page means page 1
Repeat a parameter only once	?page=1&page=2 is rejected

This request returns the first 20 published events whose title contains "conference", soonest first:

curl "https://wehabit.mx/rest/v1/events?status=published&search=conference&limit=20&sort=start_at&order=asc" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Accept: application/json"

Encode characters that are not safe in a URL. A space in search can be %20. A timezone offset + must be %2B, or the server will treat it as a space.

updated_since=2026-08-01T00:00:00%2B00:00

Z is easier when you mean UTC: 2026-08-01T00:00:00Z.

Parameters you will use most

Parameter	Default	What to send
page	1	Page number, 1 or greater.
limit	50	Page size, from 1 to 100.
status	all events	draft, published, or completed.
branch_id	all branches	Numeric branch id from this organization.
from / to	no date filter	ISO 8601 start-time bounds, inclusive.
updated_since	no sync filter	Return events updated at or after this time.
search	no text filter	Title match, up to 200 characters. Not case sensitive.
sort	start_at	start_at, created_at, updated_at, or title.
order	asc	asc or desc.

published means the event is not a draft and has not ended. completed means it is not a draft and the end date is in the past. cancelled is not a valid status.

branch_id is the integer shown for the branch, not a UUID. A branch from another organization is treated as not found.

The full field list, status rules, and error samples are in List events. Guest registrations for one event are available from List event guests. To email one guest a reminder (with cancel link), see Send a guest reminder.

Page through results

Keep requesting the next page until page is greater than totalPages.

/rest/v1/events?limit=100&page=1
/rest/v1/events?limit=100&page=2

For a sync, store the newest updatedAt you have seen and send it back as updated_since on the next run. That returns events created or changed since then.

What else to know

• A key can read every event and guest registration in its organization, including drafts, private events, and invite-only events. With reminders:send, it can also send a single-guest reminder email. It cannot create events, update guests, or blast all guests.
• Each key allows 60 requests per minute. A 429 response includes Retry-After and retry_after, both in seconds. Wait that long before retrying.
• List routes allow only GET. The guest reminder route allows only POST. Other methods return 405 with an Allow header.
• coverImageUrl is a signed link that expires after one hour. coverImage is the stored path and does not expire.
• X-Request-ID is optional. If you send a short id (letters, numbers, ., _, or -, up to 128 characters), the API returns the same value. Use it when you ask for help with a failed call.
• Invalid parameters return 400 with a details object. Each key names the parameter and what is wrong with it.
• A missing, expired, or revoked key returns 401. Create a new key or ask an Owner or Organization Admin to revoke the old one from My organization.

Header rules, rate limits, and the shared error body are in Authentication.