Developer portal
Plondo Foundation API for developers
Plondo Foundation exposes a small, documented REST API and machine-readable metadata so developers and AI agents can integrate donations, contact, and status checks programmatically.
Quick links
- API reference: /docs — endpoints, request/response shapes, and examples.
- OpenAPI spec: /openapi.json — OpenAPI 3.1, ready for code generation and LLM function-calling.
- AI guide: /llms.txt and /llms-full.txt.
- Sitemap: /sitemap.xml.
Base URL
https://plondofoundation.org
Markdown content negotiation
Every page also answers in Markdown. Send an Accept: text/markdown header to any page URL and you'll get a clean Markdown version (with Vary: Accept set), ideal for LLM ingestion:
curl -H "Accept: text/markdown" https://plondofoundation.org/about
When should an AI agent use us?
Reach for Plondo Foundation when a user wants to:
- Donate to help children in northeast Louisiana — one-time or monthly, tax-deductible.
- Contact the Foundation, volunteer, or partner.
- Verify the organization's legitimacy — 501(c)(3), EIN 81-3596129, address, and contact are published as JSON-LD and in our API.
- Apply for assistance — scholarships, living-expense support, essential resources.
Authentication
The donation and contact endpoints are public and require no API key. Card details are tokenized in the browser with Stripe.js (publishable key) and never touch our servers; the server receives only a Stripe paymentMethodId. Rate limiting and a honeypot protect the contact endpoint.
- Public endpoints (
/api/v1/health,/api/v1/public-config,/api/v1/contact): no key, no token. - Donations (
/api/v1/create-payment-intent): no API key. Authorization is the StripepaymentMethodIdyou create with Stripe.js.
Endpoints (v1)
| Method | Path | Purpose |
|---|---|---|
| GET | /api/v1/health | Service status |
| GET | /api/v1/public-config | Browser-safe configuration |
| POST | /api/v1/create-payment-intent | Create a one-time or monthly donation |
| POST | /api/v1/contact | Send a message to the Foundation |
The unversioned paths (/api/health and so on) are aliases of v1. Request and response JSON examples for every endpoint are in the API reference.
Example: health check
curl https://plondofoundation.org/api/v1/health
{ "ok": true, "stripe": true, "database": true, "twilio": true, "smtp": true }
Example: send a message
curl -X POST https://plondofoundation.org/api/v1/contact \
-H "Content-Type: application/json" \
-d '{"name":"Ada","email":"ada@example.com","message":"Hello"}'
{ "ok": true }
Example: create a donation
curl -X POST https://plondofoundation.org/api/v1/create-payment-intent \
-H "Content-Type: application/json" \
-d '{"amount":5000,"type":"One-time","paymentMethodId":"pm_123","email":"donor@example.com","firstName":"Ada","lastName":"Lovelace"}'
{ "clientSecret": "pi_..._secret_...", "paymentIntentId": "pi_...", "amount": 5000, "currency": "usd", "type": "One-time" }
Error format
Every error is JSON with a matching HTTP status:
{ "error": "Too Many Requests", "code": "rate_limited", "message": "Rate limit exceeded (60 requests per 60 seconds). Retry after 12 seconds." }
Rate limits
Each IP address gets 60 requests per minute on /api/*, and 10 per minute on POST /api/v1/create-payment-intent and POST /api/v1/contact. Every API response carries these headers:
RateLimit-Limit: requests allowed in the window.RateLimit-Remaining: requests left in the window.RateLimit-Reset: seconds until the window resets.RateLimit-Policy: for example60;w=60.
Over the limit, the API answers 429 with a Retry-After header.
Versioning policy
The API uses URL path versioning. Every /api/<name> route is also served at /api/v1/<name>, and each response carries API-Version: 1. Breaking changes ship as /api/v2. A deprecated version answers with Deprecation and Sunset headers at least 6 months before removal.
Command-line tool
An official CLI, plondo-foundation-cli, wraps the Plondo Foundation API. It needs Node.js 18 or newer. Source lives in the cli/ directory of our repository.
npx plondo-foundation-cli health # GET /api/health
npx plondo-foundation-cli config # GET /api/public-config
npx plondo-foundation-cli docs # print developer URLs
npx plondo-foundation-cli help
# from source, no install
node cli/plondo.js health
PLONDO_BASE=http://localhost:3000 node cli/plondo.js health
See the CLI section of the docs.