Developer documentation

The developer site is where the people who build on the Backed API read how it works. It is at https://backed.giving/developers, and it is public: it holds no organisation's data, so anyone can read it without signing in. Point your developer, or the company that builds your integration, at it.

Before you start

You need no account, sign-in or permission to read the developer site or to fetch the OpenAPI document. A credential is needed only to call the API itself: an Administrator creates one under Settings > Profile and terms, on the API Access tab, as API access explains. The API Access tab links to the developer site under Developer documentation.

What the developer site holds

The reference. Every operation of the API, read and write, with the request it takes and an example of the request and the response.
Guides. How a system signs in with a credential and gets a token, how to page through a long list, what each error means, how idempotency keys make a retry safe, how to check a webhook delivery's signature, and how to connect Power BI and Tableau.
Event catalogue. Every webhook event type, with its version, what it means and a sample payload. It is the same list as the Event catalogue on the Webhooks tab: see Webhooks.
Changelog. Each change to the API, with its date.

The guides describe the same API as these articles: API access for credentials and scopes, Webhooks for setting up endpoints, and the OData feed for BI tools and data warehouses.

The OpenAPI document

The OpenAPI document is a machine-readable description of the whole API, in the OpenAPI 3.1 format most developer tools read. It covers every read and write route under /api/v2/, the token endpoint at /oauth/token, the webhook delivery payload and event catalogue, and a pointer to the OData reporting feed.

Fetch it from either place:

Your organisation's own address, the one your team signs in at, plus /api/v2/openapi.json, such as https://your-subdomain.backed.giving/api/v2/openapi.json. The document names that address as its server, so a tool that reads it sends its requests to your organisation.
The developer site, at https://backed.giving/developers/openapi.json. It is the same document.

Fetching it needs no credential. The document describes the API and holds none of your records.

Generate a client

A developer can give the document to a code generator, such as OpenAPI Generator, or import it into an API tool, such as Postman or Insomnia, to get a ready-made client with every route and field typed. The client still needs a token from a credential to call the API. When the API changes, the document changes with it, so fetch it again and regenerate.

Pages for AI assistants

The developer site also publishes itself in forms an AI assistant, such as Claude, reads well, so a developer can ask one to help write an integration from the real documentation:

llms.txt, at https://backed.giving/developers/llms.txt: a short list of every page on the site, with a line on what each holds.
llms-full.txt, at https://backed.giving/developers/llms-full.txt: every page's text in one file, to give an assistant the whole documentation at once.
A Markdown copy of every page, at the page's own address plus .md. Give an assistant the one page it needs rather than the whole site.

Versions and the changelog

The current version of the API is v2. A change that could break a system already connected, such as removing or renaming a field or a route, is only ever published under a new version path, and the version you use keeps working as it is. The Changelog lists every change with its date, so your developer can see what is new without rereading the reference. How long a superseded version stays, and how you are told, is in Versions and deprecation.