> ## Documentation Index
> Fetch the complete documentation index at: https://docs.momentra.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints

> The six /api/v1/* routes, their auth, billing meter, and request bodies.

| Method | Path | Auth | Billing (meter) | Purpose |
| - | - | - | - | - |
| GET | `/api/v1/search/businesses?q=` | ZeroClick identity | **Free** | Find indexed orgs by name/domain |
| GET | `/api/v1/search/events?startDate=&endDate=&category=&city=&limit=` | ZeroClick identity | **Free** | Cross-index event search |
| POST | `/api/v1/orgs` | ZeroClick paid | `orgs_index` (qty 1) | Index an org on demand (fresh crawl) |
| GET | `/api/v1/orgs/{jobId}` | ZeroClick (verify-only) | **Free** | Poll an index job; `410` after 24h |
| GET | `/api/v1/businesses/{id}/events` | ZeroClick paid | `events_pull` (qty 1) | All upcoming events for an org |
| POST | `/api/v1/report` | ZeroClick identity | **Free** | Report a data/crawl issue |

<Info>
  **Free identity-scoped** routes require a registered agent (`zc-agent-id`). A
  signed anonymous probe gets a `$0` identity challenge (`402` with `usage:[]`).
  **Paid** routes declare a usage quantity; ZeroClick prices it from your catalog
  and issues the buyer a challenge. `/api/v1/orgs/{jobId}` is gated by an
  unguessable job id, so it needs no identity — a signed request (even anonymous)
  is served free.
</Info>

## `POST /api/v1/orgs`

Index an organization on demand (fresh crawl).

```json theme={null}
{
  "website": "https://example.com",
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "hints": {
    "calendarUrls": ["https://example.com/event-calendar/"],
    "eventUrls": []
  }
}
```

* `domain` is accepted as an alias for `website`.
* Dates default to today .. +90 days.
* Optional `hints` lets a caller supply known calendar/event URLs. They are
  **appended to** (not a replacement for) whatever auto-discovery finds — useful
  to rescue a site with weak discovery. URLs are sanitized (http(s) only),
  deduped, and capped (≤50 each, ≤2048 chars).

The charge always buys a fresh crawl, so usage settles with a `zc-usage` header
on the `202`. Returned URLs use the storefront host.

## `GET /api/v1/orgs/{jobId}`

Poll an index job.

| State | Response |
| - | - |
| running / pending | `202` |
| ready | `200 { status:"ready", orgId, eventsUrl, eventCount }` |
| failed | `502` |
| after 24h | `410` with a pointer (to the events URL if indexed, else back to `POST /api/v1/orgs`) |

## `GET /api/v1/businesses/{id}/events`

`{id}` is the `orgId` returned by the index/status calls. Returns the full
upcoming `EventRecord[]` (v1 schema) — not a preview. Settles one `events_pull`
unit on the `200`. An unknown/unindexed org returns `404` with an `indexUrl`
pointer (no charge).

## `POST /api/v1/report`

Free identity-scoped support channel (mirrors the MCP `report_issue` tool).

```json theme={null}
{
  "message": "…",
  "email": "you@example.com",
  "domain": "example.com",
  "orgId": "…",
  "jobId": "…"
}
```

Only `message` is required. Collects diagnostics (resolved org, indexed
`eventCount` + address, scraper `scriptVersion`, sample events, related job
status), emails the Momentra team, and persists an audit record.

| Response | Meaning |
| - | - |
| `202 { status:"received", reportId, delivered }` | Report recorded |
| `400` | Missing message |
| `429` | Per-reporter daily cap hit |

No allowance check, no settlement (`guardIdentity`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.