API
A REST API for the distribution company’s systems: metering (AMI), billing, field-work management. Data are uploaded and collected without manual exports. Permissions are the same as in the workspace: an account sees only its own organisation’s projects.
Connection
- base URL:
https://gridinspector.com/api/v1(orhttps://gridinspector.ru/api/v1); - JSON in UTF-8; files as
multipart/form-data; - sign-in with the login and password of an account issued by GRID-IN; the response contains a token,
passed in the header
Authorization: Bearer <token>; - browser requests from a customer website — from origins agreed at connection;
- errors — a code in the
errorfield and an HTTP status: 400 bad request, 401 not signed in, 404 not found, 409 not possible now (e.g. no data or no contract), 429 too many failed sign-ins.
Requests
| Request | What it does |
|---|---|
POST /session | sign in: {"login", "password"} → {"token", "expires_in", "user"} |
GET /me | the signed-in account: login, name, role |
GET /projects | the organisation’s projects |
POST /projects | create a project: {"name", "name_en"} |
GET /projects/{id} | project: substations with data periods, last calculation |
POST /projects/{id}/files | upload files (field file, several allowed) → an ingest task per file |
GET /tasks/{id} | task status: queued, running, done, failed; for ingest — what was recognised in the file, for a calculation — its number and summary |
POST /projects/{id}/run | start a calculation → task; if one is already running — its task |
GET /projects/{id}/runs | project calculations: number and time |
GET /projects/{id}/runs/{run} | calculation summary by substation: period, number of meters, imbalance, number of targets |
GET /projects/{id}/runs/{run}/targets | field targets in priority order |
GET /projects/{id}/outcomes | recorded field-visit outcomes |
POST /projects/{id}/outcomes | record an outcome: {"substation", "target", "outcome", "note"}; outcome — found, not_found, no_access |
Creating projects, uploading files and starting calculations requires the manager role; inspectors can also record visit outcomes.
Field target
| Field | Meaning |
|---|---|
priority | position in the visit order |
substation, pos | substation |
target | target key — used to record the visit outcome |
meter, label | meter number and its name |
address, lat, lon | address and coordinates |
kind | target type: theft — unmetered consumption, extra — meter of another substation, fault — fault |
categories | finding codes for the target |
probability | probability of confirmation, %, where measured |
unaccounted_kwh, metered_kwh | estimated unmetered and metered energy for the period, kWh |
outcome | recorded visit outcome |
Typical sequence
POST /session— get a token;POST /projects/{id}/files— send the export; wait for the tasks viaGET /tasks/{id};POST /projects/{id}/run— start the calculation; wait for the task;GET /projects/{id}/runs/{run}/targets— collect the targets;POST /projects/{id}/outcomes— return the visit outcomes.
API access is issued together with the organisation’s account.