Sector API
How a utility or office pulls the reports sent to it, with photos, location and status.
This guide explains how a sector (for example a water utility, power company or roads agency) pulls the community reports that Jirani AI users assign to it, together with their photos and details, into its own systems.
| Item | Value |
|---|---|
| Base URL | https://api1.jirani.ai/api/v1 |
| Format | JSON over HTTPS, UTF-8 |
| Sign-in | The staff member's own Jirani AI email and password |
| Access | Read only: reports assigned to your sectors |
1. Getting access
- Each staff member registers a Jirani AI account and verifies its email address.
- A Jirani AI administrator adds that verified email to your sector. One person can belong to several sectors.
- Keep the password on your server only. Never put it in a web page, a mobile app or a URL.
When an administrator removes a person from the sector, their access stops immediately.
2. Signing in
POST /auth/login
Content-Type: application/json
{"email":"[email protected]","password":"<password>"}
| Response 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 with POST /auth/refresh and body {"refreshToken":"..."}. Each refresh returns a new refresh token; keep the latest one. |
3. Your sectors
GET /sector/me
Authorization: Bearer <accessToken>
Returns your name and the sectors you belong to, each with its id, name and number of reports.
4. Listing reports
GET /sector/reports?limit=50
Authorization: Bearer <accessToken>
Returns the reports assigned to your sectors, newest first. Reports from all time are included.
| Query parameter | Rule |
|---|---|
limit | 1-100 per page (default 20) |
cursor | The page.nextCursor from the previous page |
sectorId | Only one of your sectors |
updatedSince | Only reports changed after this time (ISO 8601, for example 2026-10-18T09:00:00Z) |
createdBefore | Only reports created before this time |
publicationState | published or pending_review |
visibility | public or private |
category | A category, for example utilities or roads |
q | Words in the title, description or place |
When page.hasMore is true, ask again with cursor set to page.nextCursor. A cursor is valid for a limited time; start again from the first page if it expires.
Keeping your system up to date: every few minutes, list with updatedSince set to the time of your last successful sync. Changed reports come back with their latest details; match them to your copy by id.
5. One report in full
GET /sector/reports/{id}
Authorization: Bearer <accessToken>
Returns the same fields as the list, plus the report's updates (evidence and status updates people sent) and visible comments.
6. Report fields
| Field | Meaning |
|---|---|
id | The report's Jirani AI ID |
title, description | What the reporter wrote |
category | For example utilities, roads, health |
language | en or sw |
sourceDetails | Extra source information the reporter gave, if any |
sector | The sector it is assigned to: id, name |
visibility | public (everyone can see it) or private (only Jirani AI staff and your sector) |
publicationState | published, or pending_review while Jirani AI checks it |
verificationState | unverified, under_review, verified, disputed or false |
eventStatus | ongoing, resolved or unknown |
location | Where the problem is: latitude, longitude, exact, accuracyMeters, source, mapsUrl, placeLabel, precision and area (see below) |
reporter | id and display name of the person who reported it |
observedAt | When the reporter says it happened (may be empty) |
createdAt, publishedAt, updatedAt | When it was sent, published and last changed |
counts | helpful reactions, confirmations from other people, visible comments |
images | Photos: id, mimeType, width, height, url, feedUrl, thumbnailUrl |
Location
Reports sent to a sector carry the exact point of the problem, so your field staff can go straight to it. The public only ever sees a point rounded to about 100 m.
| Field | Meaning |
|---|---|
latitude, longitude | The exact point (6 decimal places) when exact is true |
exact | true when the reporter gave an exact point for your sector |
accuracyMeters | How accurate the reporter's GPS was, in metres (for example 8); empty when not known |
source | gps (the reporter's phone at the spot), search (an address the reporter searched) or map |
mapsUrl | A Google Maps link to the point, ready to open on a phone |
placeLabel | The place name the reporter gave |
exact is false only for older reports sent before exact points were collected; those points are rounded to about 100 m.
To protect people's privacy, the reporter's phone number and email are never included.
7. Downloading photos
Each image has three links:
| Link | Size |
|---|---|
url | Full size |
feedUrl | Medium, for lists |
thumbnailUrl | Small preview |
Request them with the same Authorization: Bearer <accessToken> header. A photo of a private report can only be opened by your sector's staff, so store the image itself if you need it later rather than sharing the link.
8. Errors
Errors look like this:
{"error": {"code": "SECTOR_ACCESS_REQUIRED", "message": "Request could not be completed.", "retryable": false}, "meta": {"requestId": "req_…"}}
| Status | Code | What to do |
|---|---|---|
| 401 | AUTH_REQUIRED, SESSION_REVOKED | Refresh the access token, or sign in again. |
| 401 | INVALID_CREDENTIALS | Check the email and password. |
| 403 | SECTOR_ACCESS_REQUIRED | This account is not in any active sector; ask a Jirani AI administrator to add it. |
| 404 | NOT_FOUND | The report does not exist, was removed, or is not assigned to your sectors. |
| 422 | VALIDATION_FAILED | A query parameter is not valid (for example a date not in ISO 8601). |
| 429 | RATE_LIMITED | Too many requests; wait and retry. |
| 503 | TEMPORARILY_UNAVAILABLE | Retry later. |
Support
Contact the Jirani AI team with your account email, the time of the request and its meta.requestId.
