Basic Usage

Base (dev): http://localhost:8000 (Swagger: /docs, ReDoc: /redoc, schema: /openapi.json). All endpoints use /api/v1/ prefix unless noted.

Auth status: In dev most endpoints are open. Planned: JWT Bearer (Authorization: Bearer <token>) and API Key (X-API-Key). Examples below show headers but they may be optional in dev.

Quick Calls (cURL)

Health

curl http://localhost:8000/health

List citizen reports (with filters)

curl "http://localhost:8000/api/v1/citizen-reports?category=infrastructure&priority=high&limit=20&offset=0"

Create citizen report

curl -X POST http://localhost:8000/api/v1/citizen-reports \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pothole on Le Loi Boulevard",
    "location": {"type": "Point", "coordinates": [106.7009, 10.7756]},
    "category": "infrastructure",
    "reportedBy": "user@example.com",
    "images": ["https://storage.urbanreflex.dev/images/report-001.jpg"]
  }'

Classify citizen report

curl -X POST \
  http://localhost:8000/api/v1/citizen-reports/classify/urn:ngsi-ld:CitizenReport:001

AI chatbot (non-streaming)

curl -X POST "http://localhost:8000/ai-service/chatbot/chat?stream=false" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the air quality in District 1?"}'

NGSI-LD direct (Orion-LD)

curl "http://localhost:1026/ngsi-ld/v1/entities?type=CitizenReport&georel=near;maxDistance==1000&geometry=Point&coordinates=[106.7009,10.7756]"

Python (httpx, async)

import httpx
 
BASE = "http://localhost:8000"
 
async def list_reports():
    async with httpx.AsyncClient(base_url=BASE) as client:
        resp = await client.get("/api/v1/citizen-reports", params={"limit": 20})
        resp.raise_for_status()
        return resp.json()
 
async def chat(message: str):
    async with httpx.AsyncClient(base_url=BASE) as client:
        resp = await client.post(
            "/ai-service/chatbot/chat",
            params={"stream": "false"},
            json={"message": message},
        )
        resp.raise_for_status()
        return resp.json()

TypeScript (fetch)

const BASE = "http://localhost:8000";
 
export async function listReports() {
  const res = await fetch(`${BASE}/api/v1/citizen-reports?limit=20`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}
 
export async function chat(message: string) {
  const res = await fetch(`${BASE}/ai-service/chatbot/chat?stream=false`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ message }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

Response Shapes (typical)

List with pagination:

{
  "data": [/* items */],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "page": 1,
    "pages": 8
  }
}

Error format (consistent):

{
  "detail": "Error message describing what went wrong",
  "status_code": 400,
  "error_type": "ValidationError"
}

Tips

Pagination: use limit/offset (or page), defaults: limit 100, offset 0 (see API reference).
Filtering: common params category, priority, status, type, created_after, created_before.
Sorting: sort_by, order=asc|desc (default desc).
Chat streaming: omit ?stream=false to receive SSE events (data: {"type":"token",...}).

For full endpoint list, auth plans, and examples, see docs/API_REFERENCE.md.

Basic Usage

On this page