Civesto Authority API

Quickstart

Three calls tell you whether the integration works: who you are, what is waiting, and one case in full.

1. Obtain a key from your authority's IT contact (created in the console under API keys) or from [email protected] for a pilot. Keys look like civ_live_prod_… and are shown once.
2. Call GET /me — it returns your authority, your scopes and your role.
3. Call GET /ihbarlar?limit=20 — the newest reports in your jurisdiction — then GET /ihbarlar/{id} for one of them.

# who am I, what may I do
curl https://civesto.com/v1/kurumsal/me \
  -H "X-Civesto-Key: civ_live_prod_REPLACE_ME"

# newest reports in my jurisdiction (cursor pagination)
curl "https://civesto.com/v1/kurumsal/ihbarlar?limit=20&durum=new" \
  -H "X-Civesto-Key: civ_live_prod_REPLACE_ME"

# record an outcome (needs the case_write scope)
curl -X POST https://civesto.com/v1/kurumsal/ihbarlar/211/status \
  -H "X-Civesto-Key: civ_live_prod_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"durum": "validated", "not": "Legal basis: SRTI Art. 3(b) — confirmed on site"}'

import requests

BASE = "https://civesto.com/v1/kurumsal"
H = {"X-Civesto-Key": "civ_live_prod_REPLACE_ME"}

me = requests.get(BASE + "/me", headers=H, timeout=10).json()
print(me["tenant"]["ad"], me["role"], me["scopes"])

page = requests.get(BASE + "/ihbarlar", headers=H, params={"limit": 20, "durum": "new"}, timeout=10).json()
for r in page["items"]:
    print(r["id"], r["referans"], r["ihlal_turu"], r["durum"], r["olusturulma_zamani"])
# page["next_cursor"] -> pass as ?cursor= for the next page

using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient { BaseAddress = new Uri("https://civesto.com/v1/kurumsal/") };
client.DefaultRequestHeaders.Add("X-Civesto-Key", "civ_live_prod_REPLACE_ME");

var me = await client.GetFromJsonAsync<JsonElement>("me");
var page = await client.GetFromJsonAsync<JsonElement>("ihbarlar?limit=20&durum=new");
foreach (var r in page.GetProperty("items").EnumerateArray())
    Console.WriteLine($"{r.GetProperty("id")} {r.GetProperty("ihlal_turu")} {r.GetProperty("durum")}");

const BASE = "https://civesto.com/v1/kurumsal";
const H = { "X-Civesto-Key": "civ_live_prod_REPLACE_ME" };

const me = await (await fetch(`${BASE}/me`, { headers: H })).json();
const page = await (await fetch(`${BASE}/ihbarlar?limit=20&durum=new`, { headers: H })).json();
for (const r of page.items) console.log(r.id, r.referans, r.ihlal_turu, r.durum);

Authentication & roles

One header. The key identifies the authority (tenant) and carries the scopes; nothing else is needed. Keys are stored as Argon2id hashes — the plain value exists only where you keep it.

Headers

Scopes

A key carries a set of scopes. Each endpoint states what it needs; a call without it returns 403 with the missing scope named in details. A key can never create another key with more than it holds itself.

Role presets

The console creates keys by role; a role is simply a scope set. The console shows only what the key can use.

Endpoints

All paths are relative to /v1/kurumsal. Jurisdiction is enforced on every report query: a key sees only the reports of its authority's area, and an id outside it answers 404.

Reports

A report is what one citizen submitted, plus what the platform could verify about it. The record carries observations, not conclusions: the assessment is the authority's.

Recording an outcome

POST /ihbarlar/{id}/status
{ "durum": "forwarded", "not": "Legal basis: StVO § 12 Abs. 4 — forwarded to the fine office" }

Status changes are recorded in the audit log. The receiving authority must define the processing purpose and applicable legal basis. If a webhook subscribes to report.updated, the change also queues an event.

Summary & statistics

GET /ihbarlar/ozet?days=30 (or baslangic/bitis) returns the period in aggregate: totals, outcome mix, category and priority breakdown, backlog age (open, new, waiting over 72 h, oldest), response times (median, p90, mean of submission → first action), evidence-sealed share, recurring locations (same condition within ~150 m, with open count and centroid) and a weekday × hour arrival matrix. It contains no case identifier, so a stats_read key may call it; repeat plates (masked) are added only for keys that hold read.

GET /ihbarlar/agrega?granularity=daily gives the volume trend; GET /ihbarlar/heatmap?resolution=6 gives ~700 m grid cells for a map layer. The console's Statistics and Activity report views are built from exactly these three calls.

Exports

GET /ihbarlar/export?fmt=… exports records within the key's jurisdiction. The recipient must validate the format and permitted fields; the presence of an adapter is not a completed integration.

CAP: GET /ihbarlar/{id}/cap renders a report's routing decision as a Common Alerting Protocol 1.2 envelope (ETSI TS 103 479 lists CAP as a mandatory NG112 interface). It is offered as an interoperable envelope on request, not as a channel any control room already consumes.

Webhooks

Subscribe an HTTPS endpoint of your case-management system and Civesto pushes events to it; your system stays the system of record. Failed deliveries are retried (1 m → 5 m → 30 m → 2 h → 6 h → 24 h) and every attempt is visible in the delivery log.

Events

Verifying a delivery

Each POST carries X-Civesto-Event, X-Civesto-Event-Id (idempotency key — deliveries may repeat), X-Civesto-Timestamp and X-Civesto-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body with the signing secret shown once at creation.

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, header)

Answer 2xx quickly and process asynchronously; anything else is retried. The endpoint must be a public HTTPS address — private and link-local ranges are refused at creation.

Keys & audit

POST /keys with {"isim", "scopes", "ip_allowlist", "expires_at"} returns the plain key exactly once. Give every person, integration and wall display its own key with the smallest role that does the job; revoke with DELETE /keys/{id}?reason=… the moment it is not needed. last_used_at answers "is this key still in use?".

GET /audit lists every call made with the authority's keys — timestamp, action, result, origin address, duration — and is the authority's own record of processing. The console adds a CSV export of it.

Errors & limits

Errors are JSON with a stable code, a readable message and details:

{ "error": "forbidden", "message": "This API key is not permitted to perform that action",
  "details": { "required": ["read"], "granted": ["stats_read"] } }

The allowance is per key and per hour, set per agreement (plan defaults from 1,000 to 1,000,000 requests/hour); GET /usage shows consumption. List responses carry X-Civesto-Record-Count.

OpenAPI reference

The complete, generated schema is at /v1/kurumsal/openapi.json. Click Authorize below to try requests with your own key — every call you make here is audit-logged like any other.