Publishing API
How approved partners publish news, reports, announcements and alerts to people in a country or around a place.
This guide explains how your organization publishes to Jirani AI users from your own systems: community reports, news, announcements for local communities, and in-app notifications. It also explains how to check who you will reach before you publish.
| Item | Value |
|---|---|
| Base URL | https://api1.jirani.ai/api/v1 |
| Format | JSON over HTTPS, UTF-8 |
| Sign-in | Your Jirani AI account email and password, used from your server |
| Languages | English (en) and Kiswahili (sw) |
1. Getting access
- Register a Jirani AI account for your organization and verify its email address.
- Ask the Jirani AI team to turn on publishing API access for that account. Access is off for every account until Jirani AI switches it on, and Jirani AI can switch it off at any time.
- Keep the account's password on your server only. Never put it in a mobile app, a web page or a URL.
Publishing API access does not make your account an administrator, a moderator or an official source, and it does not open private communities.
2. Signing in
POST /auth/login
Content-Type: application/json
{"email":"[email protected]","password":"<your password>"}
The response data contains:
| Field | Use |
|---|---|
accessToken | Send it on every request as Authorization: Bearer <accessToken>. It expires after 15 minutes. |
refreshToken | Exchange it for a new access token before or after it expires. |
accessTokenExpiresAt | When the access token stops working. |
To get a new access token:
POST /auth/refresh
Content-Type: application/json
{"refreshToken":"<refreshToken>"}
Each refresh returns a new refresh token; always keep the latest one.
3. What you can publish
| What | Endpoint | Who sees it | Sends an alert? |
|---|---|---|---|
| Community report | POST /external/observations | People browsing the map and feed around the event location | No |
| News | POST /external/news | Everyone in one country, or only people looking at a place inside your circle (local news), for 25 hours | No |
| Announcement | POST /external/announcements | Members of public communities inside your target circle | No |
| Notification | POST /external/notifications | People in your target area who allow alerts | Yes, in the app (and on the phone where push is enabled) |
Everything you publish is shown with your organization's name as the author. You cannot publish on behalf of another account or choose individual recipients.
4. Choosing your audience
Most content is aimed at a circle on the map:
"target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Dar es Salaam"}
| Field | Rule |
|---|---|
latitude, longitude | Required. The centre of the circle. |
radiusMeters | Required. From 100 to 50,000 metres. |
placeLabel | Required. 2 to 160 characters, shown to users. |
Inside the circle, Jirani AI reaches:
- members of public communities whose centre is inside the circle (a large community whose centre lies outside is not included);
- people who follow a place that overlaps the circle (notifications only).
News can go to a whole country or to one area.
- National news: send a country. Everyone in that country sees it.
``json "target": {"countryCode": "TZ"} ``
countryCode accepts the ISO code (TZ) or the telephone code (255, +255).
- Local news: send a circle and no
countryCode. It is shown to people whose Home page is set to a place inside the circle, next to national news, and it is read out by Guide there.
``json "target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Kinondoni"} ``
The same rules as above apply: 100 to 50,000 metres and a place label. Local news is also only shown inside the country that contains the circle's centre.
If you send a circle and a countryCode, the news is treated as national news for that country, as it was before local news existed.
5. Checking your audience before you publish
Ask how many people a message would reach. Nothing is published or sent.
POST /external/audience-preview
Authorization: Bearer <accessToken>
Content-Type: application/json
{
"type": "announcement",
"category": "health",
"target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Dar es Salaam"}
}
| Request field | Rule |
|---|---|
type | observation, news, announcement or notification |
target | A circle, or {"countryCode": "TZ"} for news |
category | Optional. Counts only people interested in this category (see section 8). Required for observation. |
domain | Required for news (any label, 2-160 characters) |
The response audience contains:
| Number | Meaning |
|---|---|
uniqueUsers | People reached, each counted once. Use this number. |
publicGroups | Public communities that would receive the content |
groupMembers | People reached through those communities |
placeFollowers | People reached because they follow a nearby place |
notificationEligibleUsers | People who would get an in-app alert |
pushEligibleUsers | People who could also get a phone push notification |
countryUsers | For national news: people whose account is in that country. For local news the other numbers are an estimate from communities and followed places in the circle, because anyone can look at the place. |
groupMembers and placeFollowers can include the same person, so do not add them together. Counts describe memberships and followed places, not who is physically there right now, and they can change between your preview and your publish.
6. Publishing
Rules for every publishing request
| Header or field | Rule |
|---|---|
Authorization | Bearer <accessToken> |
Content-Type | application/json |
Idempotency-Key | Required. 8-128 characters, new for each new item. If a request times out, retry with the same key and the same body; Jirani AI will not create it twice. |
externalId | Recommended. Your own ID for the item (up to 160 characters). Jirani AI refuses a second item of the same kind with the same externalId from your account, even days later. |
Unknown fields are rejected, so send only the fields listed below.
Community report: POST /external/observations
{
"title": "Water supply interruption",
"description": "Water supply is interrupted near the public market.",
"category": "utilities",
"visibility": "public",
"language": "en",
"placeLabel": "Public market",
"coordinate": {"latitude": -6.7924, "longitude": 39.2083},
"target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Dar es Salaam"},
"externalId": "your-report-123"
}
| Field | Required | Rule |
|---|---|---|
description | Yes | 10-5,000 characters |
title | No | 5-160 characters; made from the description if left out |
category | Yes | One of the categories in section 8 |
visibility | Yes | public, or private to show it only to Jirani AI staff and a chosen sector |
sectorId | No | A sector from GET /sectors (for example a utility company) |
language | Yes | en or sw |
placeLabel | Yes | 2-160 characters |
coordinate | Yes | Where the event happened |
target | Yes | The audience circle (can match the coordinate) |
observedAt | No | When it happened (ISO 8601, not in the future) |
sourceDetails | No | Up to 2,000 characters |
mediaIds | No | Up to 5 photos (section 7) |
The report is published at once unless Jirani AI's moderation policy requires review; publicationState in the response tells you which. Reports start as unverified until Jirani AI checks them.
News: POST /external/news
{
"title": "New agricultural investment announced",
"body": "Details of the investment and the communities expected to benefit.",
"domain": "Agriculture & Food",
"sourceUrl": "https://example.com/news/123",
"language": "en",
"target": {"countryCode": "TZ"},
"externalId": "your-news-123"
}
| Field | Required | Rule |
|---|---|---|
title | Yes | 5-160 characters |
body | Yes | 10-5,000 characters |
domain | Yes | Your label for the kind of news, for example Risk alert or Funding opportunity (2-160 characters). It is shown to users but does not change who receives the news. |
sourceUrl | Yes | The original article, https:// only |
language | Yes | en or sw |
target | Yes | {"countryCode": "TZ"} for national news, or a circle without a country for local news (see section 4) |
category | No | One of the categories in section 8 |
mediaIds | No | Up to 5 photos |
latitude and longitude are optional for news: leave them out for national news. Send them only for local news, together with radiusMeters and placeLabel and without countryCode. A point without the rest of the circle is refused.
News is published immediately and stays in the Home news feed for 25 hours: for everyone in the country (national news), or for people looking at a place inside the circle (local news). It does not send alerts; use a notification if you need one.
Announcement: POST /external/announcements
{
"title": "Community health information",
"body": "A public information session will take place at the community centre.",
"category": "health",
"target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Dar es Salaam"},
"linkUrl": "https://example.com/community-health",
"mapUrl": "https://maps.google.com/?q=Dar+es+Salaam",
"startsAt": "2026-11-20T06:00:00Z",
"eventAt": "2026-11-20T09:00:00Z",
"expiresAt": "2026-11-21T18:00:00Z",
"pinned": false,
"externalId": "your-announcement-123"
}
| Field | Required | Rule |
|---|---|---|
title | Yes | 5-160 characters |
body | Yes | 10-5,000 characters |
target | Yes | A circle |
category | No | One of the categories in section 8 |
linkUrl, mapUrl | No | https:// links |
startsAt | No | When to start showing it |
expiresAt | No | When to stop showing it; must be in the future and after startsAt |
eventAt | No | The date of the event you are announcing (shown to users) |
pinned | No | true to keep it at the top of each community's announcements |
imageMediaId | No | One photo uploaded with purpose external_announcement (section 7) |
One copy is posted to each matching public community. If no community matches, the request still succeeds with announcementsCreated: 0. More than 1,000 matching communities is refused (AUDIENCE_TOO_LARGE). Announcements do not send alerts.
Notification: POST /external/notifications
{
"title": "Local public information update",
"body": "Please review the latest local public information.",
"category": "health",
"type": "alerts",
"target": {"latitude": -6.7924, "longitude": 39.2083, "radiusMeters": 4500, "placeLabel": "Dar es Salaam"},
"expiresAt": "2026-11-21T18:00:00Z",
"externalId": "your-notification-123"
}
| Field | Required | Rule |
|---|---|---|
title | Yes | 1-180 characters |
body | Yes | 1-5,000 characters |
target | Yes | A circle |
type | No | alerts (default), groups or system |
category | No | Only people interested in this category |
expiresAt | No | After this time the notification disappears from the app |
Each eligible person gets one in-app notification; where Jirani AI push delivery is enabled and the person allows it, they also get a phone notification. People who muted the community or turned off alerts are skipped. More than 10,000 recipients is refused (AUDIENCE_TOO_LARGE). No email or SMS is sent.
7. Adding photos
Photos are uploaded first, then referenced by ID.
Step 1: ask for an upload. Send POST /media/uploads with an Idempotency-Key header:
{"purpose": "observation", "fileName": "photo.jpg", "mimeType": "image/jpeg", "sizeBytes": 245000, "address": "Public market, Dar es Salaam"}
Use purpose observation for reports and news, or external_announcement for an announcement image. JPEG or PNG, up to 10 MB. Give an address, or latitude and longitude.
Step 2: upload the file. Send the file bytes to the returned uploadUrl, using the returned method and requiredHeaders.
Step 3: finish. Send POST /media/{id}/complete with a new Idempotency-Key and the body {}.
Step 4: wait until ready. Check GET /media/{id} until state is ready (usually a few seconds), then use the id in mediaIds or imageMediaId. A rejected photo cannot be used.
Each photo can be used once.
8. Reference data
| Request | Returns |
|---|---|
GET /categories | Active categories: roads, health, utilities, events, business, education, environment, safety, tourism |
Categories are also people's preferences: someone who has one switched off receives nothing from it. All news is published in the news category, whatever category you send.
| Request | Returns |
|---|---|
GET /sectors | Sectors a private report can be assigned to |
GET /locations/country?latitude=...&longitude=... | The country of a point, as Jirani AI will resolve it |
9. Responses and errors
A successful publish returns 201 with data describing what was created, including publicationId, the audience counts at publishing time, and for notifications notificationsCreated. Every response has meta.requestId; include it when you contact Jirani AI.
Errors look like this:
{"error": {"code": "VALIDATION_FAILED", "message": "Request could not be completed.", "retryable": false}, "meta": {"requestId": "req_…"}}
| Status | Code | What to do |
|---|---|---|
| 400 | INVALID_REQUEST | The JSON is malformed or has a field this guide does not list. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | Add an Idempotency-Key header. |
| 401 | AUTH_REQUIRED, SESSION_REVOKED | Refresh the access token, or sign in again. |
| 403 | EXTERNAL_API_DISABLED | Publishing access is off for your account; contact Jirani AI. |
| 403 | IDENTITY_VERIFICATION_REQUIRED | Verify the account's email address. |
| 409 | IDEMPOTENCY_CONFLICT | You reused an Idempotency-Key with a different body. Use a new key. |
| 409 | CONFLICT | An item of this kind with this externalId already exists. |
| 422 | VALIDATION_FAILED | A field breaks a rule in this guide (length, range, date, URL). |
| 422 | INVALID_CATEGORY | Use a category from GET /categories. |
| 422 | INVALID_COUNTRY_CODE | Use a supported country code. |
| 422 | REPORT_VISIBILITY_REQUIRED | Send visibility for reports. |
| 422 | EVENT_LOCATION_REQUIRED | Send coordinate for reports. |
| 422 | AUDIENCE_TOO_LARGE | Use a smaller circle. |
| 422 | INVALID_ANNOUNCEMENT_IMAGE | Use your own ready photo uploaded for external_announcement. |
| 429 | RATE_LIMITED | Too many requests; wait and retry. |
| 503 | TEMPORARILY_UNAVAILABLE | Retry later with the same Idempotency-Key. |
10. Good practice
- Preview your audience before large announcements and notifications.
- Use one
Idempotency-Keyper item and reuse it for retries of that item. - Always send
externalIdso an item is never published twice. - Write titles people understand at a glance, in the language of your audience.
- Only send notifications for things people need to know now; they interrupt people.
Support
Contact the Jirani AI team with your account email, the time of the request and its meta.requestId.
