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

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 Stripe paymentMethodId you create with Stripe.js.

Endpoints (v1)

MethodPathPurpose
GET/api/v1/healthService status
GET/api/v1/public-configBrowser-safe configuration
POST/api/v1/create-payment-intentCreate a one-time or monthly donation
POST/api/v1/contactSend 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 example 60;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.

Machine-readable resources

Read the API docs   View OpenAPI spec