API overview — auth, base URL, conventions.

Mama's REST API is in beta. Coverage is partial — accounts and signals are fully exposed; briefs are read-only in v0. This page is the start: how to authenticate, what the base URL is, what conventions to expect.

Time: 5 min·Updated: 2026-05-25·Audience: developers·Status: Beta · Pro+ only·Version: v0

TL;DR

Base URL: https://api.signalmama.com/v0. Auth: Bearer token via API key (workspace → Settings → API). Format: JSON in/out, snake_case. Pagination: cursor-based with next_cursor in response. What's shipped: accounts (read+write), signals (read), briefs (read), saved searches (read). What's not: briefs (write), Reply Loop, Orbit, custom bots.

01API status

The Mama API is in beta. Pro and Company tiers can request API access from Settings → API. Free tier has no API access.

Honest about coverage: this is not yet a full programmatic surface for everything in Mama. We're shipping the most-requested endpoints first. The roadmap is public — see /changelog for what's coming.

02Base URL & versioning

All API requests go to:

https://api.signalmama.com/v0

v0 indicates beta. We may make breaking changes during v0 with 30-day deprecation notice. v1 stability guarantees coming once API surface stabilizes.

The v0 prefix is in the path, not a header. Future versions will be parallel paths (/v1, /v2) so you can migrate at your own pace.

03Authentication

Bearer token via API key. Get a key from Settings → API → "Create new key" in your Mama workspace.

# Example request curl "https://api.signalmama.com/v0/accounts" \ -H "Authorization: Bearer mama_live_xxxxxxxxxxxx"

Key conventions:

Prefix: mama_live_ for production keys, mama_test_ for sandbox keys
Scoped per-workspace: a key only sees data from the workspace that issued it
Revocable: revoke from Settings → API. Effective immediately.
Multiple keys per workspace: name them by use case (e.g., "Production sync," "CI test")

04Format conventions

Request body: JSON with snake_case field names
Response body: JSON with snake_case field names
Dates: ISO 8601 in UTC (e.g., 2026-05-25T14:30:00Z)
IDs: prefixed string IDs (acc_ for accounts, sig_ for signals, brf_ for briefs)
Money: integer cents (USD only in v0)
Booleans: true/false (not 1/0)

05Pagination

List endpoints return up to 100 results per page. Use cursor-based pagination via the next_cursor field in the response.

{ "data": [...], "next_cursor": "eyJpZCI6Im...", "has_more": true }

Pass cursor=<value> as a query param on the next request. When has_more is false, you've reached the end.

06Error envelope

All errors return a consistent JSON envelope:

{ "error": { "type": "invalid_request", "code": "missing_field", "message": "Field 'name' is required", "field": "name", "request_id": "req_xxxxxxxxxxxx" } }

Always include the request_id when contacting support — it lets us trace the request server-side.

07What's shipped in v0

Resource	Read	Write
Accounts	✓	✓
Signals	✓	—
Briefs	✓	— (use UI or Push)
Decision-makers	✓	—
Saved searches	✓	—
Archetypes	✓	—
Reply Loop	— (planned)	—
Orbit	— (planned)	—
Custom bots	— (planned)	—

08Common mistakes

Hard-coding API keys into client-side code

API keys grant workspace access. Never ship them to a frontend. Use a server-side proxy.

Polling instead of using webhooks

If you need real-time signal updates, webhooks (Push center) are better than polling /signals. Polling burns rate limit.

Assuming v0 is stable

It's beta. Expect breaking changes with deprecation notice. For production, subscribe to /changelog for API updates.

Was this page helpful?

Yes No Report unclear