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.

ItemValue
Base URLhttps://api1.jirani.ai/api/v1
FormatJSON over HTTPS, UTF-8
Sign-inYour Jirani AI account email and password, used from your server
LanguagesEnglish (en) and Kiswahili (sw)

1. Getting access

  1. Register a Jirani AI account for your organization and verify its email address.
  2. 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.
  3. 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:

FieldUse
accessTokenSend it on every request as Authorization: Bearer <accessToken>. It expires after 15 minutes.
refreshTokenExchange it for a new access token before or after it expires.
accessTokenExpiresAtWhen 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

WhatEndpointWho sees itSends an alert?
Community reportPOST /external/observationsPeople browsing the map and feed around the event locationNo
NewsPOST /external/newsEveryone in one country, or only people looking at a place inside your circle (local news), for 25 hoursNo
AnnouncementPOST /external/announcementsMembers of public communities inside your target circleNo
NotificationPOST /external/notificationsPeople in your target area who allow alertsYes, 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"}
FieldRule
latitude, longitudeRequired. The centre of the circle.
radiusMetersRequired. From 100 to 50,000 metres.
placeLabelRequired. 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 fieldRule
typeobservation, news, announcement or notification
targetA circle, or {"countryCode": "TZ"} for news
categoryOptional. Counts only people interested in this category (see section 8). Required for observation.
domainRequired for news (any label, 2-160 characters)

The response audience contains:

NumberMeaning
uniqueUsersPeople reached, each counted once. Use this number.
publicGroupsPublic communities that would receive the content
groupMembersPeople reached through those communities
placeFollowersPeople reached because they follow a nearby place
notificationEligibleUsersPeople who would get an in-app alert
pushEligibleUsersPeople who could also get a phone push notification
countryUsersFor 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 fieldRule
AuthorizationBearer <accessToken>
Content-Typeapplication/json
Idempotency-KeyRequired. 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.
externalIdRecommended. 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"
}
FieldRequiredRule
descriptionYes10-5,000 characters
titleNo5-160 characters; made from the description if left out
categoryYesOne of the categories in section 8
visibilityYespublic, or private to show it only to Jirani AI staff and a chosen sector
sectorIdNoA sector from GET /sectors (for example a utility company)
languageYesen or sw
placeLabelYes2-160 characters
coordinateYesWhere the event happened
targetYesThe audience circle (can match the coordinate)
observedAtNoWhen it happened (ISO 8601, not in the future)
sourceDetailsNoUp to 2,000 characters
mediaIdsNoUp 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"
}
FieldRequiredRule
titleYes5-160 characters
bodyYes10-5,000 characters
domainYesYour 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.
sourceUrlYesThe original article, https:// only
languageYesen or sw
targetYes{"countryCode": "TZ"} for national news, or a circle without a country for local news (see section 4)
categoryNoOne of the categories in section 8
mediaIdsNoUp 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"
}
FieldRequiredRule
titleYes5-160 characters
bodyYes10-5,000 characters
targetYesA circle
categoryNoOne of the categories in section 8
linkUrl, mapUrlNohttps:// links
startsAtNoWhen to start showing it
expiresAtNoWhen to stop showing it; must be in the future and after startsAt
eventAtNoThe date of the event you are announcing (shown to users)
pinnedNotrue to keep it at the top of each community's announcements
imageMediaIdNoOne 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"
}
FieldRequiredRule
titleYes1-180 characters
bodyYes1-5,000 characters
targetYesA circle
typeNoalerts (default), groups or system
categoryNoOnly people interested in this category
expiresAtNoAfter 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

RequestReturns
GET /categoriesActive 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.

RequestReturns
GET /sectorsSectors 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_…"}}
StatusCodeWhat to do
400INVALID_REQUESTThe JSON is malformed or has a field this guide does not list.
400IDEMPOTENCY_KEY_REQUIREDAdd an Idempotency-Key header.
401AUTH_REQUIRED, SESSION_REVOKEDRefresh the access token, or sign in again.
403EXTERNAL_API_DISABLEDPublishing access is off for your account; contact Jirani AI.
403IDENTITY_VERIFICATION_REQUIREDVerify the account's email address.
409IDEMPOTENCY_CONFLICTYou reused an Idempotency-Key with a different body. Use a new key.
409CONFLICTAn item of this kind with this externalId already exists.
422VALIDATION_FAILEDA field breaks a rule in this guide (length, range, date, URL).
422INVALID_CATEGORYUse a category from GET /categories.
422INVALID_COUNTRY_CODEUse a supported country code.
422REPORT_VISIBILITY_REQUIREDSend visibility for reports.
422EVENT_LOCATION_REQUIREDSend coordinate for reports.
422AUDIENCE_TOO_LARGEUse a smaller circle.
422INVALID_ANNOUNCEMENT_IMAGEUse your own ready photo uploaded for external_announcement.
429RATE_LIMITEDToo many requests; wait and retry.
503TEMPORARILY_UNAVAILABLERetry later with the same Idempotency-Key.

10. Good practice

  • Preview your audience before large announcements and notifications.
  • Use one Idempotency-Key per item and reuse it for retries of that item.
  • Always send externalId so 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.