Backend API Reference

Complete REST API reference for the TerraGuard backend, covering event management, news, knowledge base, reports, notifications, and ingestion endpoints.

Overview

The backend API is the central service of TerraGuard, providing 40+ endpoints for disaster event management, AI-powered enrichment, and team collaboration. It is built with Python/FastAPI and uses JWT authentication via Clerk.

Base URL: /api/v1

Authentication: All endpoints require a valid Clerk JWT in the Authorization: Bearer <token> header, unless marked as public.

Events

Core CRUD operations for disaster events.

List Events

GET /api/v1/events

Query parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`event_type`	string	Filter by type: `earthquake`, `flood`, `cyclone`, `volcano`, `wildfire`
`severity`	string	Filter by severity: `green`, `orange`, `red`
`date_from`	string	ISO 8601 date filter (inclusive)
`date_to`	string	ISO 8601 date filter (inclusive)
`bbox`	string	Bounding box: `min_lon,min_lat,max_lon,max_lat`
`search`	string	Full-text search across title and description
`labels`	string	Comma-separated label IDs

Response:

{
  "items": [
    {
      "id": "evt_abc123",
      "title": "M7.7 Earthquake - Myanmar",
      "event_type": "earthquake",
      "severity": "red",
      "latitude": 20.88,
      "longitude": 95.95,
      "magnitude": 7.7,
      "occurred_at": "2025-03-28T08:15:00Z",
      "source": "gdacs",
      "source_id": "EQ-2025-001",
      "population_exposure": 2450000,
      "country_iso3": "MMR",
      "labels": ["monitoring", "response-active"],
      "created_at": "2025-03-28T08:20:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}

Get Event Detail

GET /api/v1/events/{event_id}

Returns the full event record including enrichment data, AI summary, contacts, and labels.

Update Event Labels

PUT /api/v1/events/{event_id}/labels

{
  "label_ids": ["lbl_001", "lbl_002"]
}

Update Event Contacts

PUT /api/v1/events/{event_id}/contacts

{
  "contact_ids": ["cnt_001", "cnt_002"]
}

Event News

News articles associated with disaster events.

List News for Event

GET /api/v1/event-news/{event_id}

Returns validated news articles that have been crawled and indexed for the event.

Trigger News Crawl

POST /api/v1/event-news/{event_id}/crawl

Initiates a web search and crawling pipeline for the event. This is an async operation -- articles will appear as they are processed through the enrichment pipeline.

Knowledge Base

Vector search and RAG-powered knowledge management.

Search Knowledge Base

POST /api/v1/knowledge/search

{
  "query": "earthquake preparedness guidelines Southeast Asia",
  "event_id": "evt_abc123",
  "limit": 10
}

Performs semantic search against the vector index of crawled documents and returns ranked results with relevance scores.

Generate AI Summary

POST /api/v1/knowledge/summarize

{
  "event_id": "evt_abc123",
  "query": "What is the current humanitarian impact?",
  "sources": ["news", "reports", "knowledge_base"]
}

Uses a RAG agent to generate a grounded summary from indexed documents. The response includes source citations.

Index URL

POST /api/v1/knowledge/index

{
  "url": "https://reliefweb.int/report/myanmar/earthquake-sitrep-3",
  "event_id": "evt_abc123"
}

Submits a URL for crawling and vector indexing. The crawler extracts content and the backend generates embeddings for semantic search.

Reports

AI-generated and manual disaster reports.

Generate Report

POST /api/v1/reports/generate

{
  "event_id": "evt_abc123",
  "template_id": "tpl_sitrep",
  "sections": ["overview", "impact", "response", "outlook"]
}

Triggers AI report generation using MCP servers for data gathering. The report agent queries the database, vector index, and external sources via MCP tools.

Reports can be retrieved individually via GET /api/v1/reports/{report_id} (returns structured JSON or rendered HTML) or listed via GET /api/v1/reports.

Schedule Report

POST /api/v1/reports/schedule

{
  "event_id": "evt_abc123",
  "template_id": "tpl_sitrep",
  "cron": "0 8 * * *",
  "recipients": ["team_ops"]
}

Notifications

Email and Telegram alert management.

Endpoint	Method	Description
`/api/v1/notifications/rules`	GET	List notification rules for the organization
`/api/v1/notifications/eligibility`	POST	Check which teams/users would be notified for an event
`/api/v1/notifications/test`	POST	Send a test notification (`channel`, `recipient`, `event_id`)

Ingestion

Endpoints for event ingestion from external sources.

Webhook (Go Processor)

POST /api/v1/internal/webhook/event

Called by the Go event processor when new or updated events are ingested. Triggers the Inngest enrichment pipeline.

{
  "event_id": "evt_abc123",
  "source": "gdacs",
  "source_id": "EQ-2025-001",
  "action": "created"
}

Legacy Ingest

POST /api/v1/ingest/event

Direct event ingestion endpoint used before the Go processor was introduced. Still available for manual imports and testing.

Labels & Contacts

Endpoint	Method	Description
`/api/v1/labels`	GET	List all labels
`/api/v1/labels`	POST	Create label (`name`, `color`)
`/api/v1/labels/{id}`	PUT	Update label
`/api/v1/labels/{id}`	DELETE	Delete label
`/api/v1/contacts`	GET	List all contacts
`/api/v1/contacts`	POST	Create contact (`name`, `email`, `role`)
`/api/v1/contacts/{id}`	PUT	Update contact
`/api/v1/contacts/{id}`	DELETE	Delete contact

Error Responses

All errors follow a consistent format:

{
  "detail": "Event not found",
  "status_code": 404
}

Status Code	Description
400	Bad request -- invalid parameters or request body
401	Unauthorized -- missing or invalid JWT
403	Forbidden -- insufficient permissions
404	Not found -- resource does not exist
422	Validation error -- request body failed schema validation
429	Rate limited -- too many requests
500	Internal server error

On this page