> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/products/open-agri-stack/exchange/composite/api.md). # Composite API API reference for the Agri Stack Composite: list and describe use cases, query a use case with a signed envelope, and the staff console's read-only API. The Composite serves approved use cases. A partner sends one signed request about one farmer, with the farmer's consent. The Composite queries each registry the use case names and returns one signed response. * **Base URL:** `https:///composite/v1` * **Who calls it:** partners (banks, MFIs, agritechs) onboarded in Partner Management with a policy there for the use case (`name@major`). Staff use the console API. * **Signing:** the query body is an envelope `{signature, header, message}`. `signature` is a detached JWS over `{header, message}`, made with the partner's key. The Composite verifies it against the partner's keys in Partner Management (`header.sender_id`). The Composite signs every response, errors included, with its own key. * **Consent:** send nothing (the Exchange's Consent Manager looks up the consent it holds from this partner for this farmer and use case), `message.consent_id` (a consent it holds) or `message.consent_jws` (a consent the partner signed, accepted only if its policy for the use case allows partner-signed consents). The first two need the Exchange consent mode. The Exchange turns the consent into a consent token for each registry, and the response names the one used (`message.consent_id`). * **Result:** each source (registry query) gets a status: `ok`, `no_record`, `denied`, `unavailable` or `error`. A failed optional source leaves its fields null. A failed mandatory source fails the request. {% hint style="info" %} For the step-by-step (onboarding, keys, consent, signing, verifying the response), see the [Partner Guide](/products/open-agri-stack/partner-guide.md). {% endhint %} ## Operations | Method | Path | What it does | Signed | | ------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------- | -------------------- | | `GET` | `/composite/v1/use-cases` | List the published use cases | No | | `GET` | `/composite/v1/use-cases/{use_case}` | Describe one use case: subject types, parameters, sources, consent grants and data scopes, output fields | No | | `POST` | `/composite/v1/use-cases/{use_case}/query` | Query a use case for one subject | Request and response | | `GET` | `/composite/v1/admin/...` | Console API (staff, read-only) | Staff login | `{use_case}` is `name` (for example `loan-profile`) or `name@major` (for example `loan-profile@1`). Without a major version, the highest published one is used. The `X-Use-Case-Major` header can name the major version instead. ## Error codes An error from a query is a signed envelope too. `header.status` is `rjct`, and `message.error` has the `code` and a `message`. | HTTP | Codes | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_envelope`, `wrong_receiver`, `stale_request`, `invalid_use_case`, `invalid_input`, `consent_id_needs_exchange` | | 401 | `signature_invalid` | | 403 | `partner_not_allowed`, `consent_required`, `consent_malformed`, `consent_signature_invalid`, `consent_subject_mismatch`, `consent_not_yet_valid`, `consent_expired`, `consent_grant_missing`, `consent_scope_missing`, `consent_denied`, `consent_receipt_missing`, `source_denied` | | 404 | `unknown_use_case` | | 429 | `rate_limited` | | 500 | `signing_unavailable` | | 502 | `source_error`, `consent_exchange_error` | | 503 | `source_unavailable`, `consent_exchange_unavailable`, `partner_policy_unavailable` | | 504 | `source_unavailable` (a mandatory source timed out) | The two codes about the partner's use-case grant ([data-sharing policies](/products/open-agri-stack/architecture/data-sharing-policies.md#fail-closed)): * **`403 partner_not_allowed`:** the partner has no policy for this use case (`name@major`) in Partner Management. Message: `partner 'bank-b' is not granted the use case loan-profile@1 in Partner Management`. * **`503 partner_policy_unavailable`:** Partner Management cannot be read to check the grant and no recent answer is cached. Message: `Partner Management cannot be read to check the partner's use-case grant; try again later`. **`403 consent_denied`** carries the Exchange Consent Manager's reason in its message, e.g. `consent_not_found` when the partner sent no consent and the CM holds none for this farmer and use case. **`403 consent_required`**: no consent sent in passthrough mode. ## Use cases ## Console API (staff) The console's read-only API, used by the [Composite Console](/products/open-agri-stack/exchange/composite/console.md). It needs a staff login (IAM) with the `composite:view` permission. It is present only when the console is on. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openg2p.org/products/open-agri-stack/exchange/composite/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.