Skip to content

Specification Overview

UGP version 2026-06-25. Authority domain ugp.dev.

UGP layers a single service, dev.ugp.giving, on top of UCP's discovery and profile model. A nonprofit advertises the service in its /.well-known/ucp profile; a giving provider serves the endpoints.

The dev.ugp.giving service

The giving service is declared in the nonprofit's profile under services["dev.ugp.giving"] as an array of transport bindings. The 2026-06-25 release defines a single transport binding: rest.

jsonc "services": { "dev.ugp.giving": [ { "version": "2026-06-25", "transport": "rest", "endpoint": "https://chariot.app/api/ugp/v1/orgs/eastside-shelter", "spec": "https://ugp.dev/specification/overview", "schema": "https://ugp.dev/services/giving/rest.openapi.json" } ] }

The service is accompanied by two capabilities:

  • dev.ugp.giving.profile — the nonprofit profile config (see Profile).
  • dev.ugp.giving.donations — the donation batch workflow (see Donations).

Endpoint resolution

The REST OpenAPI document (source/services/giving/rest.openapi.json) defines operations only. The base URL is not baked into the spec. A platform MUST:

  1. Fetch the nonprofit's profile from https://<nonprofit-domain>/.well-known/ucp.
  2. Read services["dev.ugp.giving"] and select the binding with transport == "rest".
  3. Use that binding's endpoint as the base URL for all operations below.

The endpoint points at the provider, not the nonprofit (see Core Concepts → the hosting split). All paths below are relative to that endpoint.

The four REST endpoints

Method Path operationId Purpose
GET /profile get_profile Retrieve the nonprofit profile config.
POST /donation-batches create_batch Create a batch and receive bank payment instructions.
GET /donation-batches/{batch_id} get_batch Retrieve full batch state, payment trace, and reconciliation.
POST /donation-batches/{batch_id}/status update_batch_status Advance the batch payment state.

create_batch returns 201 with a batch_response (or an error_response via oneOf). get_batch and update_batch_status return 200 with a batch_state_response (or error_response). The full workflow and state machine are described in Donations.

Request headers

UGP reuses UCP's REST header conventions verbatim. Every request carries:

  • UCP-Agent (required) — the caller's profile URI in RFC 8941 Dictionary syntax pointing at /.well-known/ucp, e.g. profile="https://platform.example.com/.well-known/ucp".
  • Request-Id (required) — UUID for tracing.
  • Idempotency-Key (required on writes: create_batch, update_batch_status) — UUID ensuring retries don't duplicate operations. Note that at the application layer, create_batch is also idempotent on external_batch_id.
  • Authorization / X-API-Key — platform authentication (OAuth bearer token or a provider-issued API key).
  • Signature, Signature-Input, Content-Digest — RFC 9421 HTTP Message Signatures + RFC 9530 body digest. Signatures are verified against the public JWK in the signer's profile signing_keys.
  • Standard negotiation headers: Content-Type, Accept, Accept-Language, Accept-Encoding, User-Agent.

Responses carry Signature, Signature-Input, and Content-Digest so the caller can verify the provider's response against the nonprofit/provider signing keys.