Authentication
For server-to-server integrations, generate an API key from Settings → Account Settings → Developer Settings in the Gratona dashboard. Send the key in theX-HYS-API-Key header on protected admin requests:
Authorization: Bearer <token>. These are alternative authentication methods; one valid credential is sufficient. Access is limited to the key or token’s organization and the user’s permissions.
Public endpoints do not require an admin API key. Donor, recipient, and participant portal endpoints have their own sign-in and session requirements. Follow each endpoint’s parameters and authentication description; an admin API key does not replace a portal session.
API Versions
Most operations usehttps://api.gratona.com/v1. The v2 notes API uses /v2. Schema discovery, primitives and the newer Zapier operations use /v3. Public endpoints mounted outside a version prefix use the root API URL. Each endpoint’s generated request example includes its correct base URL.
The continuing api.helpyousponsor.com host supports compatibility integrations. The X-HYS-API-Key header remains the API-key header on both hosts.
Available Workflows
The reference includes donors and households, donations and recognition, sponsorships and recipient funding, events, journeys, trips, tasks, fundraising and stewardship, impact stories, communications, reports, integrations, Spaces and Library, and workspace setup. Feature availability depends on your organization’s configuration, subscription, permissions and rollout settings. An endpoint’s presence in the reference does not grant access to its feature. Read the endpoint’s requirements and preview or approval steps before submitting a change.Requests And Responses
Use the method, path, content type, and required fields shown for each operation. Mutations may require a preview token or an idempotency key. A202 Accepted response means work was queued; use the documented status endpoint to observe completion. Retired operations may return 410 Gone.
This reference is generated from controller annotations in the Gratona API repository. Examples describe the API contract; use test data when trying operations that create or change records.