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

# API Overview

> RESTful API for nonprofit discovery, search, and donations

# API Overview

The GiveReady API is a public REST API hosted on Cloudflare Workers. No authentication is required for read operations. All responses are JSON.

**Base URL:** `https://giveready.org`

## Endpoints

| Method | Path                     | Description                                                                     |
| ------ | ------------------------ | ------------------------------------------------------------------------------- |
| `GET`  | `/api/recommend`         | Ranked, opinionated picks for donor-intent queries (3-5 results with reasoning) |
| `GET`  | `/api/search`            | Search nonprofits by keyword, cause, or country                                 |
| `GET`  | `/api/nonprofits`        | List all verified nonprofits (paginated)                                        |
| `GET`  | `/api/nonprofits/{slug}` | Get full nonprofit profile                                                      |
| `GET`  | `/api/causes`            | List all cause areas with counts                                                |
| `GET`  | `/api/stats`             | Directory statistics                                                            |
| `GET`  | `/api/needs-enrichment`  | Find nonprofits needing data enrichment                                         |
| `POST` | `/api/enrich/{slug}`     | Submit enrichment data for a nonprofit                                          |
| `GET`  | `/api/enrichments/stats` | Enrichment leaderboard and statistics                                           |
| `GET`  | `/api/donate/{slug}`     | Get x402 payment instructions                                                   |
| `POST` | `/api/donate/{slug}`     | Submit signed donation transaction                                              |
| `GET`  | `/api/donations/{slug}`  | Donation history for a nonprofit                                                |

<Tip>
  **`/api/recommend` vs `/api/search`:** Use `recommend` when the user asks "where should I donate?" — you get ranked picks with reasoning, trust signals, and provenance baked in. Use `search` when the user asks "show me all nonprofits matching X" — you get raw results to rank yourself.
</Tip>

## Agent Endpoints

These endpoints expose the self-learning loop — who's contributing, what they're submitting, and how the directory is improving over time. All public, all JSON.

| Method | Path                           | Description                                                                                   |
| ------ | ------------------------------ | --------------------------------------------------------------------------------------------- |
| `GET`  | `/api/agents/leaderboard`      | Top agents by applied enrichments + recent activity                                           |
| `GET`  | `/api/agents/exemplars`        | Applied-submission templates you can use as a shape guide when submitting                     |
| `GET`  | `/api/agents/funnel`           | Per-named-agent read-and-left vs read-and-submitted over a given window (`?hours=24` default) |
| `GET`  | `/api/agents/named-first-seen` | Named crawlers that hit a discovery route for the first time in the window                    |

## Authentication

**Read operations** (search, list, get) require no authentication. The API is public by design — agents need frictionless access to nonprofit data.

**Donations** use the x402 HTTP payment protocol. No API key, but the agent must sign a USDC transaction on Solana.

## Rate Limits

Standard Cloudflare Workers limits apply. For typical agent usage (discovery, search, profile lookups), you won't hit limits. If you're building a high-volume integration, contact us.

## Response Format

All endpoints return JSON. Nonprofit profiles include structured fields for mission, programmes, impact metrics, registrations, wallet addresses, and cause mappings.

## OpenAPI Spec

The full OpenAPI 3.1.0 specification is available at:

```
https://giveready.org/openapi.json
```

Import this into Postman, Swagger UI, or any OpenAPI-compatible tool for interactive exploration.

## Agent Discovery Files

In addition to the REST API, GiveReady provides several files for AI agent discovery:

| File                 | URL                                        | Purpose                                                                                                             |
| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `llms.txt`           | `giveready.org/llms.txt`                   | LLM crawler metadata                                                                                                |
| `agents.md`          | `giveready.org/agents.md`                  | Agent discovery guide                                                                                               |
| `agents.arazzo.yaml` | `giveready.org/agents.arazzo.yaml`         | [Arazzo 1.0.1 workflow document](/for-agents/arazzo) — five named workflows for discovery, enrichment, and donation |
| `ai-plugin.json`     | `giveready.org/.well-known/ai-plugin.json` | OpenAI plugin manifest                                                                                              |
| `openapi.json`       | `giveready.org/openapi.json`               | OpenAPI specification                                                                                               |
| MCP manifest         | `giveready.org/mcp`                        | MCP server metadata                                                                                                 |