# UN Mandate Registry

> Public registry of UN mandate-source documents and their programme-budget references. Budget citation is not a determination of legal in-force status.

## Recommended workflow
1. Search GET https://mandates.un.org/api/v1/documents?keyword=climate&limit=2
2. Follow each item's literal jsonUrl to read the available English paragraphs and full selected-cycle sidebar data. Do not guess document URLs.
3. Cite canonicalUrl and the original sourceUrl; include the budgetVersion for citation claims. Use pageUrl when sharing the selected cycle.
4. For complete searches, follow pagination.hasMore and increment page. Page size is at most 100, with no overall traversal cap.

## Data access
- GET /api/v1/documents: website filters, sorting and paging. Add include=details for complete sidebar data.
- GET /api/v1/documents/{symbol}: complete document; URL-encode the symbol.
- Append .json to a document page: /mandate/A/RES/79/1.json. Optional ppb_version selects the citation cycle.
- GET /api/v1/reference: entities, organs, programme hierarchy and budgetVersions.
- GET /api/v1/agendas?body=GA: complete agenda tree, sessions, allocations, available meeting counts, resolution counts and related items. Optional session selects a returned session (SC uses a year); defaults match the agenda tab. Serialize node.scope as agenda_scope for document search. Null resolutionCount and unavailable count status are not zero.
- GET /api/v1/programmes: complete entities/programmes tree, expenditure matches and clusters. Serves only the latest available budget cycle, as in the tab; ppb_version selectors are not supported. The response identifies its budgetVersion. Rows use id/parentId; expenditures are keyed by row ID and clusters contain nodeIds. Official zero-citation locations are included.
- GET /api/v1/exports?format=csv|xlsx|json: every matching document, all pages, versions expanded. JSON supports include=details. No total export cap.

## Interpretation
- Budget citations describe recorded programme-budget references, not legal in-force status.
- Missing extracted text does not establish that the original document contains no relevant provisions.
- Resolution collections are related documents, not necessarily ordered versions or legal replacements.
- Citation context is the selected budget cycle. Extraction and relationship coverage may be incomplete.
- matchingCitationCount, matchingEntityCount and matchingBudgetLocations follow search filters; details contain the complete selected-cycle context.
- paragraphs.status=unavailable means extracted text cannot be read here, not that the document is empty. Do not infer missing provisions.
- not_included is different from an empty relationship list. Expenditure amounts are entity/location figures, not allocations to individual resolutions.
- Series is_latest/latest_version are registry annotations, not legal status.

## Documentation
- [Interactive API reference](https://mandates.un.org/openapi)
- [OpenAPI 3.1 specification (JSON)](https://mandates.un.org/openapi.json)
- [About and methodology](https://mandates.un.org/about)

## Query parameters
- entity: Citing entity code, for example `DESA`. `__none__` selects documents with no citing entity.
- organ: Issuing body code from `/api/v1/reference`.
- crossCitingEntity: Second citing entity; intersects entity scope.
- keyword: Search document titles, symbols and subjects using the website search grammar. Up to 500 characters and 32 whitespace-separated terms.
- budget_part: Budget part number.
- section: Budget section identifier.
- subprogramme: Subprogramme label.
- foundational: Set to `true` to select foundational/mandates-and-background citations. Applies to the selected document/entity pair.
- programme: Programme identifier.
- subject: UNBIS subject heading.
- subject_domain: Two-digit UNBIS domain code.
- start_year: Inclusive earliest document year, 0–9999.
- end_year: Inclusive latest document year, 0–9999.
- budget_document: Budget stream: `ppb`, `pko` or `plan_outline`.
- budget_group: Peacekeeping budget group: `missions` or `support`.
- budget_location: Structured budget-location scope serialized by website links. Copy this parameter from a filtered website URL.
- document_type: Document type label as used in the website.
- agenda_item: Agenda item filter.
- agenda_scope: Structured agenda scope serialized by website links; takes precedence over `agenda_item`.
- related_scope: Related agenda cluster scope; takes precedence over `agenda_scope` and `agenda_item`.
- full_document_symbol: Exact document symbol.
- min_citations: Minimum matching citation count, 0–1000000.
- max_citations: Maximum matching citation count, 0–1000000.
- cited: Set to `1` to select only documents cited in the selected budget cycle.
- ppb_version: Budget-cycle slug from `/api/v1/reference`. Defaults to the database default; responses identify the resolved cycle.
- group: Set to `1` to group matching versions in list responses. Exports always expand all matching documents.
- sort_by: `citing_entities_desc` (default), `citing_entities_asc`, `citations_desc`, `citations_asc`, `year_desc`, `year_asc`, `similarity_desc`, `similarity_asc`, `word_count_desc` or `word_count_asc`. Keyword matches rank first; symbol breaks ties.
- page: 1-based page. No overall traversal limit.
- limit: Page size, default 15, maximum 100; larger values are normalized to 100. Exports ignore `page` and `limit`.

Known repeated filter parameters and malformed numeric values return 400. Unknown query parameters are ignored. An unknown budget cycle is a 400. Omitted ppb_version resolves the database default; pin the returned slug for subsequent calls.

## Response shape
Search: {apiVersion,budgetVersion,coverage,items:[Document],pagination:{page,pageSize,total,hasMore}}. Single document: {apiVersion,budgetVersion,coverage,document:Document}.
Document: {symbol,title,issuingBody,year,documentType,subjects,agendaItems,sourceUrl,pageUrl,canonicalUrl,jsonUrl,budgetVersion,matchingCitationCount,matchingEntityCount,matchingEntities,matchingFoundationalEntities,matchingProgrammes,matchingBudgetLocations,series,group,details}.
Expanded details: {status:'included',citations,budgetLocations,foundationalEntities,entityCitationTotals,entityExpenditures,budgetLocationExpenditures,paragraphs:{status,language,items},versionHistory,reports,relatedDocuments}. Summary-only details: {status:'not_included'}. Paragraphs retain source IDs, ordering, structural labels, links and available extraction annotations. Reports retain source/provenance and family-member links. See OpenAPI for schemas.

## Export semantics
CSV: a standard table of document fields, including agenda items, matching programmes and foundational citing entities. File-level filters, generation time and coverage are included in Excel/JSON, not repeated in CSV. Excel: Documents, Budget citations, Version relationships, About this export; sheets continue if required by the file format. JSON: indented regular JSON, {metadata,documents:[Document],exportedDocuments}; metadata includes expected total, filters, resolved cycle and detail inclusion. Filters select documents; expanded details retain all selected-cycle citations. No recursive expansion of linked documents. Downloads are live batched reads, not frozen snapshots; source changes may alter results while downloading. A failed or interrupted stream must be retried.

## HTTP behavior
Public endpoints require no authentication. Cross-origin GET is allowed. API JSON is cached for 300 seconds with up to 600 seconds stale-while-revalidate; exports use no-store. Errors: 400 invalid request, 404 unknown document, 503 temporary data failure (Retry-After:30). Error responses contain {error:string}. Respect retry guidance. The API grants no additional reuse licence; preserve original source attribution and UN/source terms.