Reports
Submit a report for editorial review.
PUT|PATCH|DELETE https://api.reliefweb.int/v2/reports/{uuid}?appname=REPLACE-WITH-APP-NAME
You need Access and credentials and Trusted URLs and UUIDs. For changes and withdrawals, see Update and Withdraw.
Field summary
Canonical schema: report.json. Field-by-field rules and examples: field reference.
| Name | Required | Type | Description |
|---|---|---|---|
url |
yes | string (IRI / URL) | Immutable unique identifier in URL form under your trusted document prefix. Used to generate the document UUID. Does not need to resolve to a live page. Never change it after first submission. |
uuid |
yes | string (UUID v5) | Document UUID v5 computed as `uuid5(ReliefWeb namespace, url)`. Must match what the server computes from the exact url string. |
title |
yes | string | Original title of the article or file. For series, add date or other distinguishing details as needed. |
source |
yes | array of integer | Source organization ID(s) from /v2/sources (ReliefWeb integer taxonomy IDs, not UUIDs). |
country |
yes | array of integer | Country ID(s) from /v2/countries. The first entry is the primary country. Tag only the most relevant. |
format |
yes | array of integer | Single content-format ID from /v2/references/content-formats. |
language |
yes | array of integer | Language ID(s) from /v2/references/languages. If an attachment is not in an official UN language, mention that in the attachment description. |
published |
yes | string (date-time) | Original publication date-time (ISO 8601) of the document. |
body |
yes | string (markdown or HTML) | Full article text, or an executive summary when the main content is a PDF attachment. Markdown or a small set of HTML tags. |
embargoed |
no | string (date-time) | UTC/GMT date-time until which the document stays embargoed; it publishes automatically at that time. |
origin |
no | string (IRI / URL) | Optional real public page where readers can view the document. Unlike url, this should resolve to a live page. |
file |
no | object (UUID-keyed map) | PDF attachments keyed by permanent file UUID (max 10, 20MB each). Each value needs `uuid`, `download_url`, `filename`, `checksum`; `url` required on create. Use your organization domain for `url`; `download_url` may use a CDN. On `PUT`, the map replaces the whole attachment set; on `PATCH`, keys merge (`null` deletes that attachment). |
file_order |
no | array of UUID | Optional display order of attachment UUIDs. Unlisted attachments keep relative order at the end; unknown ids are ignored. |
image |
no | object | Cover or illustration image. Required properties: `download_url`, `checksum`, `description`, `copyright`. No client-supplied `uuid`. Sending an `image` object replaces the whole cover; on `PATCH`, send `"image": null` to remove it. |
disaster |
no | array of integer | Disaster ID(s) from /v2/disasters. Tag only the most relevant. |
disaster_type |
no | array of integer | Disaster-type ID(s) from /v2/references/disaster-types. Tag only the most relevant. |
theme |
no | array of integer | Theme ID(s) from /v2/references/themes. Tag only the most relevant. |
notify |
no | array of string (email) | Email addresses to notify when the document is published. |
Use integer ids for taxonomies (source, country, format, language, and optional tags) — not UUIDs. Resolve them with the read API and /v2/references.
Body vs attachments
- Put the full article in
body, or an executive summary when the main content is a PDF. - PDFs go in
file(map of attachments,.pdffilename, max 20MB each, max 10). - An optional cover or illustration goes in
image(.jpg/.png/.webp, min width 700px, max 5MB).
Prefer PATCH for targeted field or attachment edits. Use PUT when you resend the full record from your system. See Update and Replace.
| Goal | See |
|---|---|
| Rules, examples, and lookups for each field | Report fields |
| Minimal and production-style payloads, troubleshooting | Report examples |
| PDF and image details | Files and images |
| Change title or body only | Update |
| New PDF version, same permanent URL | Publish a new version of a file |
| Withdraw | Withdraw |
Next: Report fields