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.

ItemValue
Base URLhttps://api1.jirani.ai/api/v1
FormatJSON over HTTPS, UTF-8
Sign-inThe staff member's own Jirani AI email and password
AccessRead only: reports assigned to your sectors

1. Getting access

  1. Each staff member registers a Jirani AI account and verifies its email address.
  2. A Jirani AI administrator adds that verified email to your sector. One person can belong to several sectors.
  3. 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 fieldUse
accessTokenSend it on every request as Authorization: Bearer <accessToken>. It expires after 15 minutes.
refreshTokenExchange 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 parameterRule
limit1-100 per page (default 20)
cursorThe page.nextCursor from the previous page
sectorIdOnly one of your sectors
updatedSinceOnly reports changed after this time (ISO 8601, for example 2026-10-18T09:00:00Z)
createdBeforeOnly reports created before this time
publicationStatepublished or pending_review
visibilitypublic or private
categoryA category, for example utilities or roads
qWords 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

FieldMeaning
idThe report's Jirani AI ID
title, descriptionWhat the reporter wrote
categoryFor example utilities, roads, health
languageen or sw
sourceDetailsExtra source information the reporter gave, if any
sectorThe sector it is assigned to: id, name
visibilitypublic (everyone can see it) or private (only Jirani AI staff and your sector)
publicationStatepublished, or pending_review while Jirani AI checks it
verificationStateunverified, under_review, verified, disputed or false
eventStatusongoing, resolved or unknown
locationWhere the problem is: latitude, longitude, exact, accuracyMeters, source, mapsUrl, placeLabel, precision and area (see below)
reporterid and display name of the person who reported it
observedAtWhen the reporter says it happened (may be empty)
createdAt, publishedAt, updatedAtWhen it was sent, published and last changed
countshelpful reactions, confirmations from other people, visible comments
imagesPhotos: 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.

FieldMeaning
latitude, longitudeThe exact point (6 decimal places) when exact is true
exacttrue when the reporter gave an exact point for your sector
accuracyMetersHow accurate the reporter's GPS was, in metres (for example 8); empty when not known
sourcegps (the reporter's phone at the spot), search (an address the reporter searched) or map
mapsUrlA Google Maps link to the point, ready to open on a phone
placeLabelThe 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:

LinkSize
urlFull size
feedUrlMedium, for lists
thumbnailUrlSmall 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_…"}}
StatusCodeWhat to do
401AUTH_REQUIRED, SESSION_REVOKEDRefresh the access token, or sign in again.
401INVALID_CREDENTIALSCheck the email and password.
403SECTOR_ACCESS_REQUIREDThis account is not in any active sector; ask a Jirani AI administrator to add it.
404NOT_FOUNDThe report does not exist, was removed, or is not assigned to your sectors.
422VALIDATION_FAILEDA query parameter is not valid (for example a date not in ISO 8601).
429RATE_LIMITEDToo many requests; wait and retry.
503TEMPORARILY_UNAVAILABLERetry later.

Support

Contact the Jirani AI team with your account email, the time of the request and its meta.requestId.