Living Signals REST API v1#

Use the read-only Living Signals REST API to explore news-derived Claims, corroborated Signals, and related Topics. All endpoints use the /api/v1 base path.

Start with GET /api/v1/countries to discover your access. Read GET /api/v1/rubric before you build filters. You can also read this reference on the documentation page, as Markdown, download the OpenAPI 3.1 document, or open the browsable reference.

Changed from the previous contract: /clusters, the level, cluster, and offset parameters, the stable_id, rubric_tags, and topic_stable_id fields, and the countries and languages aliases are not part of v1. There is no compatibility layer.

The model#

Living Signals uses four core concepts:

1. A Claim is an immutable assertion extracted from one source. It includes article and Source provenance.
2. A Signal combines corroborating Claims into a discrete, time-bounded occurrence. Signals are the primary exploration resource. Signal detail includes every retrievable Claim in the Signal.
3. A Topic groups related Signals for browsing.
4. The rubric describes each Signal with binary attributes. A category groups related attributes and matches when any member attribute is true. Both attributes and categories support multiple values on one Signal.

Annotation layers independently classify Signals through attributed standards or operational vocabularies. Access to each layer is granted separately.

The rubric and annotation layers describe Signals after they form. They do not determine how Claims form Signals or how Signals form Topics.

Getting started#

Send the API key on authenticated requests:

Authorization: Bearer ls_live_<token>

Then follow this path:

1. Discover your countries, coverage, and annotation layers:

   GET /api/v1/countries
   

2. Learn the category and attribute vocabulary:

   GET /api/v1/rubric
   

3. Explore environmental Signals in Cameroon:

   GET /api/v1/signals?country=CM&category=environmental
   

4. Retrieve one Signal with every supporting Claim:

   GET /api/v1/signals/28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19
   

5. Poll newly extracted Claims by ingestion time:

   GET /api/v1/claims?since_extracted=24h
   

For paginated requests, follow every non-null nextPage unchanged before you advance a polling watermark.

Authentication and entitlements#

Send an API key in either header:

Authorization: Bearer ls_live_<token>

X-API-Key: ls_live_<token>

Create and manage keys in the Living Signals app at /access#keys. Keys begin ls_live_. Keys issued before 2026-07-21 may begin ls_cust_; they behave identically.

Customer keys can access only their active country grants. Omit country to use every country available to your key. Requesting any unentitled country rejects the entire request with 403 country_not_entitled. The API never returns a partial country subset. Team keys can access every country.

Annotation layer grants are independent of country grants. Customer Signal responses include only granted layers with stored annotations. Filtering by an ungranted layer rejects the entire request with 403 annotation_layer_not_entitled. Team keys can filter by every registered layer. Set include_annotations=true to include stored annotations in a team response.

Use GET /api/v1/countries to discover annotation layer ids. Use GET /api/v1/annotation-layers to retrieve their code vocabularies.

Enrichment grants are separate from annotation layer and country grants. Customer Signal detail includes satellite imagery only when the organization has the geospatial_v1 enrichment enabled. Team keys can access every enrichment.

Authentication and entitlement failures use distinct codes:

Conventions#

Dates and timestamps#

Timestamps use RFC 3339 UTC, such as 2026-07-20T21:31:21.628Z. Timestamp fields include extracted_at, article.published_at, first_claim_at, last_claim_at, and formed_at.

event_date, occurred_on, signal_start, and signal_end use YYYY-MM-DD. These fields can be null. occurred_on is the canonical occurrence date for a Claim: event_date when the source states one, else the article's publish date. A null occurred_on means the occurrence time is unknown; such Claims match only since=all. Because event_date comes from source content, it can be imprecise or unreliable. Poll Claims with since_extracted instead.

Every since parameter is an exclusive bound. It accepts:

• One or more digits followed by h, d, or w. Units are case-insensitive.
• An ISO date or timestamp beginning with YYYY-MM-DD. Use an RFC 3339 timestamp when you need a time of day.
• all, which removes the bound.

Valid examples include 24h, 7d, 2w, all, 2026-07-20, and 2026-07-20T21:30:00Z. Invalid suffixes and date strings return 400 invalid_parameter.

The default window#

/signals, /topics, and /claims return the last 90 days when you omit since. Set since to choose a different window, or since=all to search the whole corpus.

The window measures when something happened, not when it was ingested. A story published today about a flood two years ago produces a Claim dated two years ago, and the default window excludes it. Claims filter on occurred_on; Signals filter on signal_end, the latest occurred_on across their Claims. Records whose occurrence time is unknown appear only under since=all.

Passing since_extracted turns the default window off, so a poll returns everything ingested since your last one whatever its occurred_on.

Strict validation#

Query parameters follow these validation rules:

/docs and /openapi.json serve fixed documents and ignore all query parameters.

Retired parameters are handled explicitly:

The API applies only safe normalization. It trims country codes and converts them to uppercase. It trims language codes and converts them to lowercase. It removes duplicate repeated or comma-separated values. A positive integer limit above 500 is clamped to 500. Check pagination.limit for the effective page size.

Every known path answers OPTIONS with 204 and Allow: GET, OPTIONS, with or without an API key. Unsupported methods return 405 method_not_allowed with the same Allow header.

Unknown paths return a JSON 404 not_found response. Authentication runs before routing under /api/v1/*. An unknown protected path without a valid key therefore returns 401. Public paths are /api/v1, /rubric, /docs, and /openapi.json.

Error envelope and codes#

Most errors use this envelope:

{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown rubric category \"climate\". See GET /api/v1/rubric for valid category ids."
  }
}

410 signal_retired is the Signal-detail exception. It uses the structured retirement body documented under GET /api/v1/signals/{id} so integrations can distinguish a durable reference with no successor from an id that never existed.

Error codes:

Rate limits#

Customer keys use a sliding-window limit of 240 requests per minute per key by default. Your deployment may use a different limit. Check these headers on authenticated customer responses:

A 429 rate_limit_exceeded response also includes Retry-After in seconds. Authentication runs before rate limiting, so 401 responses do not include rate limit headers. Public responses and team-key responses do not include them either. Team keys are not rate limited.

Pagination#

/signals, /topics, /claims, and /sources use keyset pagination:

{
  "nextPage": "https://api.livingsignals.example/api/v1/signals?country=CM&limit=50&cursor=MjEw",
  "pagination": {
    "limit": 50,
    "count": 50
  }
}

nextPage is an absolute URL on a first-party Living Signals host. Follow it unchanged until it is null. Its query string preserves your parameters as you sent them (for example, a lowercase country=cm stays lowercase even though filtering normalizes it) — treat the URL as opaque rather than parsing it. count reports rows on the current page, not total results.

Cursors are base64url-encoded sort keys. Treat them as opaque. Omit cursor to start a page walk. An empty, malformed, or incompatible cursor returns 400 invalid_cursor.

Cursors are not bound to a filter set. Some endpoints share a cursor shape, so reusing a cursor may not fail even when it points to an undefined page position. Never create, edit, or reuse a cursor. Follow the nextPage issued for the exact query you are paging through.

Endpoint reference#

GET /api/v1#

Begin here to find core concepts, authentication rules, pagination guidance, supported parameters, and a recommended integration path.

Example:

{
  "name": "Living Signals REST API",
  "version": "v1",
  "model": {
    "data_primitives": "Claims are immutable assertions extracted from one source. Signals combine corroborating Claims into time-bounded occurrences. Explore Signals as the primary resource.",
    "enrichment": "Topics group related Signals for browsing.",
    "filtering_and_organization": "The versioned rubric organizes Signals with categories and attributes. Annotation layers add independent classification vocabularies available to your key."
  },
  "getting_started": [
    {
      "step": 1,
      "request": "GET /api/v1/countries",
      "purpose": "Discover your country access, data coverage, and annotation layers."
    },
    {
      "step": 2,
      "request": "GET /api/v1/rubric",
      "purpose": "Learn the rubric vocabulary before you build filters."
    },
    {
      "step": 3,
      "request": "GET /api/v1/signals?country=CM&category=environmental",
      "purpose": "Explore corroborated occurrences in an available country."
    },
    {
      "step": 4,
      "request": "GET /api/v1/signals/{id}",
      "purpose": "Retrieve a Signal with its complete Claim provenance."
    },
    {
      "step": 5,
      "request": "GET /api/v1/claims?since_extracted=24h",
      "purpose": "Poll /claims with since_extracted. Follow nextPage and deduplicate by Claim id."
    }
  ],
  "documentation": "/api/v1/docs",
  "documentation_note": "Read the public Markdown reference at /api/v1/docs. Download OpenAPI at /api/v1/openapi.json. Browse the rendered reference at /reference. Manage keys at /access#keys.",
  "openapi": "/api/v1/openapi.json",
  "reference": "/reference",
  "auth": {
    "scheme": "Bearer or X-API-Key header",
    "customer_example": "Authorization: Bearer ls_live_<token>",
    "team_example": "Authorization: Bearer ls_live_<token>",
    "key_management": "/access#keys",
    "entitlements": "Customer keys can access granted countries, annotation layers, and enrichments. Requesting an unentitled country or annotation layer returns 403; unentitled imagery is absent from Signal detail and its PNG route returns 404. Internal keys can access every country, layer, and enrichment."
  },
  "rate_limit": {
    "applies_to": "Customer keys.",
    "default": "240 requests per minute for each API key.",
    "response": "HTTP 429 rate_limit_exceeded with Retry-After in seconds.",
    "headers": "Metered responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset."
  },
  "validation": {
    "parameters": "On data endpoints, malformed values and parameters supported by a different endpoint return HTTP 400 invalid_parameter. Unknown parameter names are ignored. The static /docs and /openapi.json endpoints ignore all query parameters.",
    "vocabulary": "Unknown rubric ids and annotation codes return HTTP 400 invalid_parameter. The error points to /rubric or /annotation-layers.",
    "paths": "Unknown paths return a JSON HTTP 404 not_found envelope.",
    "methods": "OPTIONS returns HTTP 204. Other non-GET methods return HTTP 405 method_not_allowed with Allow: GET, OPTIONS."
  },
  "pagination": {
    "next_page": "Follow the absolute nextPage URL unchanged until it is null.",
    "cursor": "Treat cursors as opaque and endpoint-specific. Omit the cursor to start. Empty or incompatible cursors return HTTP 400 invalid_cursor.",
    "response": "pagination contains the effective limit and the number of rows on the current page."
  },
  "endpoints": {
    "GET /api/v1": {
      "description": "Public integration guide and endpoint index.",
      "auth": "public",
      "params": {}
    },
    "GET /api/v1/countries": {
      "description": "Your available countries, Claim coverage, and annotation layer ids.",
      "auth": "API key",
      "params": {}
    },
    "GET /api/v1/rubric": {
      "description": "Rubric categories and attributes for filtering Signals and Topics.",
      "auth": "public",
      "params": {}
    },
    "GET /api/v1/annotation-layers": {
      "description": "Annotation vocabularies available to your key.",
      "auth": "API key",
      "params": {}
    },
    "GET /api/v1/signals": {
      "description": "Corroborated Signals with rubric filters and available annotations.",
      "auth": "API key",
      "params": {
        "country": "Repeat or comma-separate ISO-2 codes to use OR. Omission uses your full country access.",
        "category": "Repeat or comma-separate category ids to match any Signal with a member attribute from any listed category.",
        "attribute": "Repeat or comma-separate attribute ids. Every listed attribute must be true.",
        "attribute_any": "Repeat or comma-separate attribute ids. At least one listed attribute must be true.",
        "glide_v1": "Repeat or comma-separate GLIDE codes to use OR within the layer.",
        "acled_v1": "Repeat or comma-separate ACLED codes to use OR within the layer.",
        "iasc_v1": "Repeat or comma-separate IASC codes to use OR within the layer.",
        "iep_positive_peace_v1": "Repeat or comma-separate IEP Positive Peace pillars to use OR within the layer.",
        "geospatial_v1": "Repeat or comma-separate geospatial imagery-suitability codes to use OR within the layer.",
        "topic": "Parent Topic UUID.",
        "since": "Exclusive bound on when the occurrences happened, using signal_end (latest member occurrence date; Signals with no datable occurrence match only all). Defaults to 90d; pass all for the full corpus. Accepts <n>h, <n>d, <n>w, or an ISO date or timestamp.",
        "limit": "Page size. Defaults to 50 and clamps at 500.",
        "cursor": "Opaque cursor from nextPage.",
        "include_annotations": "For team keys, true includes all stored layers. Customer responses always follow grants."
      }
    },
    "GET /api/v1/signals/{id}": {
      "description": "The canonical active Signal with all of its Claims and entitled attached imagery. Retired merge and split ids resolve to their primary successor.",
      "auth": "API key",
      "params": {
        "id": "Signal UUID.",
        "include_annotations": "For team keys, true includes all stored layers. Customer responses always follow grants."
      }
    },
    "GET /api/v1/signals/{id}/imagery/{kind}.png": {
      "description": "An attached satellite imagery chip for the canonical active Signal when geospatial_v1 enrichment access is enabled.",
      "auth": "API key",
      "params": {
        "id": "Signal UUID.",
        "kind": "Imagery kind, currently post_event."
      }
    },
    "GET /api/v1/topics": {
      "description": "Browse groups of related Signals. Topic ids can change between processing runs, so store Signal or Claim ids instead.",
      "auth": "API key",
      "params": {
        "country": "Repeat or comma-separate ISO-2 codes to use OR.",
        "category": "Match any listed category on one grouped Signal.",
        "attribute": "Require every listed attribute on the same grouped Signal.",
        "attribute_any": "Require any listed attribute on the same grouped Signal.",
        "glide_v1": "Match any listed GLIDE code on the same grouped Signal.",
        "acled_v1": "Match any listed ACLED code on the same grouped Signal.",
        "iasc_v1": "Match any listed IASC code on the same grouped Signal.",
        "iep_positive_peace_v1": "Match any listed IEP Positive Peace pillar on the same grouped Signal.",
        "geospatial_v1": "Match any listed geospatial imagery-suitability code on the same grouped Signal.",
        "since": "Exclusive occurrence-time bound met by one grouped Signal. Defaults to 90d; pass all for the full corpus.",
        "limit": "Page size. Defaults to 50 and clamps at 500.",
        "cursor": "Opaque cursor from nextPage."
      }
    },
    "GET /api/v1/claims": {
      "description": "Extracted Claims with article and Source provenance plus current Signal assignment.",
      "auth": "API key",
      "params": {
        "country": "Repeat or comma-separate ISO-2 codes to use OR.",
        "signal": "Current Signal UUID.",
        "since": "Exclusive occurrence-time bound on occurred_on (event date, else article publish date; unknown-date Claims match only all). Defaults to 90d unless since_extracted is set; pass all for the full corpus.",
        "since_extracted": "Exclusive extracted_at bound for incremental polling. Turns off the default since window so polling stays lossless.",
        "limit": "Page size. Defaults to 50 and clamps at 500.",
        "cursor": "Opaque cursor from nextPage."
      }
    },
    "GET /api/v1/claims/{id}": {
      "description": "One extracted Claim.",
      "auth": "API key",
      "params": {
        "id": "Numeric Claim id."
      }
    },
    "GET /api/v1/sources": {
      "description": "Active Sources by country, with recent Claim coverage.",
      "auth": "API key",
      "params": {
        "country": "Repeat or comma-separate ISO-2 codes to use OR.",
        "language": "Repeat or comma-separate two- or three-letter language codes to use OR.",
        "limit": "Page size. Defaults to 100 and clamps at 500.",
        "cursor": "Opaque cursor from nextPage."
      }
    },
    "GET /api/v1/docs": {
      "description": "Public Markdown API reference.",
      "auth": "public",
      "params": {}
    },
    "GET /api/v1/openapi.json": {
      "description": "Public OpenAPI 3.1 document.",
      "auth": "public",
      "params": {}
    }
  }
}

Responses use Cache-Control: public, max-age=3600.

GET /api/v1/countries#

Call this endpoint first to discover your country access, data coverage, and annotation layers. Countries are ordered by code.

Example:

{
  "countries": [
    {
      "code": "CM",
      "name": "Cameroon",
      "status": "live",
      "claim_count": 18420,
      "source_count": 37,
      "first_claim_at": "2026-05-02T06:14:20.931Z",
      "last_claim_at": "2026-07-20T21:26:42.133Z"
    }
  ],
  "annotation_layers": ["acled_v1", "geospatial_v1", "glide_v1", "iasc_v1"]
}

Coverage includes only successfully extracted Claims available through /claims. Rejected and failed extraction outcomes do not contribute. A country's claim_count equals a complete country-scoped /claims walk. Its last_claim_at comes from a Claim available through /claims.

Responses use Cache-Control: private, max-age=300.

GET /api/v1/rubric#

Use this public, versioned vocabulary to build category, attribute, and attribute_any filters. An attribute is a binary property that may be true for a Signal. A category groups related attributes and matches when any member attribute is true. Scaled and numeric properties are not returned because they are not graded or stored.

Selected elements from the complete response:

{
  "version": "v1.1",
  "categories": [
    {
      "id": "environmental",
      "label": "Environmental",
      "attributes": [
        "involves_environmental_damage",
        "involves_deforestation",
        "involves_water_contamination",
        "involves_extractive_industry"
      ]
    }
  ],
  "attributes": [
    {
      "id": "involves_environmental_damage",
      "label": "Environmental Damage",
      "description": "General environmental harm, ecosystem damage",
      "section": "harm_type",
      "categories": ["environmental"]
    },
    {
      "id": "involves_air_pollution",
      "label": null,
      "description": "Air quality issues, toxic fumes, emissions, smog, respiratory hazards",
      "section": "harm_type",
      "categories": []
    }
  ]
}

Ids are case-sensitive. Responses use Cache-Control: public, max-age=3600.

GET /api/v1/annotation-layers#

Retrieve the annotation vocabularies available to your key. Customer keys receive only granted layers. An empty layers array means no layers are granted. Team keys receive every registered layer.

Selected codes from one granted layer:

{
  "layers": [
    {
      "id": "glide_v1",
      "name": "GLIDE disaster event types",
      "version": "1",
      "attribution": {
        "name": "GLIDE",
        "url": "https://glidenumber.net"
      },
      "codes": [
        {
          "code": "ff",
          "canonical": "FF — Flash Flood",
          "meaning": "Taxonomy path: natural hazard / flash flood / flash flood. Key phrases: flash flood, sudden flooding, rapid-onset flood, torrential rain flooding, urban flash flood, floodwaters surged, runoff flooding, swept away by flood."
        },
        {
          "code": "fl",
          "canonical": "FL — Flood",
          "meaning": "Taxonomy path: natural hazard / flood / flood. Key phrases: flood, flooding, river overflow, inundation, overflowing river, waterlogged areas, floodwaters, seasonal flooding."
        }
      ]
    }
  ]
}

Each layer's codes array is complete and ordered. Responses use Cache-Control: private, max-age=300.

GET /api/v1/signals#

With query, results use word matching and semantic similarity across the accessible corpus. search.mode is hybrid, or lexical when the embedding service is unavailable. search.reranked indicates whether evidence-based reranking succeeded; false means the base retrieval order is used. search.truncated indicates more matches than the result limit; nextPage is null for search. Search is a relevance-ranked retrieval aid, not an exhaustive export. Without query, the existing paginated listing is unchanged. No results means no matching reports under the selected filters, not that no event occurred.

Explore active, corroborated Signals with rubric and annotation filters. Parameters combine with AND. Values within country, category, attribute_any, and each annotation layer use OR. Multiple attribute values use AND. Results use a stable keyset order.

Within an annotation layer, a Signal matches any requested code. A Signal without stored data for that layer does not match. Separate annotation layers combine with AND. Rubric filters, annotation filters, country, topic, and since also combine with AND.

Unknown category, attribute, or code values return 400 invalid_parameter. Filtering by an ungranted customer layer returns 403 annotation_layer_not_entitled.

Example:

{
  "signals": [
    {
      "id": "28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19",
      "label": "Flooding disrupts homes and water access in Far North",
      "description": "Seasonal floodwater affected several communities and interrupted safe-water access.",
      "country_code": "CM",
      "signal_start": "2026-07-18",
      "signal_end": "2026-07-20",
      "last_claim_at": "2026-07-20T08:45:00.000Z",
      "formed_at": "2026-07-20T09:10:00.000Z",
      "claim_count": 1,
      "source_count": 1,
      "topic": {
        "id": "18aad58a-73fb-4966-a640-626c79aa7d39",
        "label": "Far North climate and displacement"
      },
      "rubric": {
        "version": "v1.1",
        "categories": ["displacement", "natural_disasters", "environmental"],
        "attributes": [
          "involves_flood",
          "involves_displacement",
          "involves_water_contamination"
        ]
      },
      "annotations": {
        "glide_v1": {
          "codes": ["fl"],
          "rationale": "The Signal describes river flooding affecting several communities."
        },
        "iasc_v1": {
          "codes": ["wash", "shelter"],
          "rationale": "The reported impacts concern safe water and emergency shelter."
        },
        "iep_positive_peace_v1": {
          "codes": ["equitable_distribution_of_resources"],
          "directions": { "equitable_distribution_of_resources": "eroding" },
          "rationale": "Damage to water infrastructure widened the gap in access between affected communities."
        }
      }
    }
  ],
  "nextPage": null,
  "pagination": {
    "limit": 50,
    "count": 1
  }
}

Responses use Cache-Control: private, max-age=60.

GET /api/v1/signals/{id}#

Retrieve the canonical active Signal with all of its retrievable Claims. Claims are ordered by numeric id. If the requested id was retired by a merge or split, the API follows its primary successor and returns the canonical Signal instead.

The response adds claims to the Signal fields returned by the list endpoint. Each embedded Claim uses the list Claim shape. Its signal_id equals the parent Signal id.

When an attached satellite chip exists and the organization has the geospatial_v1 enrichment enabled, the response also includes an imagery array. Each entry contains kind, provider, scene_id, scene_datetime, scene_cloud_cover, aoi_cloud_fraction, bbox as [west, south, east, north], pixel width and height, attribution, an analyst-written caption (a string, or null when none has been written), and the authenticated PNG url. Cloud values are numbers or null. Entries are ordered as a before/after story: pre_event, then post_event, then any derived analysis layer such as burn_map. The entire key is absent without the enrichment grant, while imagery is pending, when no clear scene was found, after a failure, or when imagery does not apply to the Signal.

Example:

{
  "signal": {
    "id": "28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19",
    "label": "Flooding disrupts homes and water access in Far North",
    "description": "Seasonal floodwater affected several communities and interrupted safe-water access.",
    "country_code": "CM",
    "signal_start": "2026-07-18",
    "signal_end": "2026-07-20",
    "last_claim_at": "2026-07-20T08:45:00.000Z",
    "formed_at": "2026-07-20T09:10:00.000Z",
    "claim_count": 1,
    "source_count": 1,
    "topic": {
      "id": "18aad58a-73fb-4966-a640-626c79aa7d39",
      "label": "Far North climate and displacement"
    },
    "rubric": {
      "version": "v1.1",
      "categories": ["displacement", "natural_disasters", "environmental"],
      "attributes": [
        "involves_flood",
        "involves_displacement",
        "involves_water_contamination"
      ]
    },
    "imagery": [
      {
        "kind": "post_event",
        "provider": "sentinel-2-l2a",
        "scene_id": "S2B_20260723T091029_CM",
        "scene_datetime": "2026-07-23T09:10:29.000Z",
        "scene_cloud_cover": 8.42,
        "aoi_cloud_fraction": 0.0312,
        "bbox": [14.2731, 10.5487, 14.3583, 10.6336],
        "width": 512,
        "height": 512,
        "attribution": "Contains modified Copernicus Sentinel data 2026",
        "caption": null,
        "url": "/api/v1/signals/28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19/imagery/post_event.png"
      }
    ],
    "claims": [
      {
        "id": "5210",
        "claim": "Floodwater entered homes and interrupted access to a community water point.",
        "event_date": "2026-07-19",
    "occurred_on": "2026-07-19",
      "occurred_on": "2026-07-19",
        "occurred_on": "2026-07-19",
        "extracted_at": "2026-07-20T08:45:00.000Z",
        "country_code": "CM",
        "geo_scope": "point",
        "place_name": "Mayo Crossing",
        "place_country": "CM",
        "region_code": null,
        "lat": 10.5912,
        "lng": 14.3157,
        "signal_id": "28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19",
        "article": {
          "url": "https://cameroon-observer.example/far-north-flood-update",
          "title": "Communities report flood damage in Far North",
          "published_at": "2026-07-20T07:30:00.000Z"
        },
        "source": {
          "id": "a12e699c-cfa2-4ce9-8c01-bec72963ea91",
          "name": "Cameroon Observer",
          "language": "en",
          "country_code": "CM"
        }
      }
    ]
  }
}

An alias response adds resolved_from beside signal. This abbreviated example focuses on the response wrapper:

{
  "signal": {
    "id": "28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19",
    "label": "Flooding disrupts homes and water access in Far North",
    "claims": []
  },
  "resolved_from": {
    "requested_id": "831ecb98-66b4-4503-b6f7-b66a7477afc0",
    "relation": "merged",
    "resolved_at_depth": 2,
    "overlap": 0.875
  }
}

The actual signal object is the complete canonical payload shown above, including only that Signal's Claims. relation and overlap describe the first transition from the requested id; resolved_at_depth is the number of transitions followed. Treat resolved_from as a prompt to replace the stored reference with signal.id.

If a known id has no active successor, the endpoint returns 410 Gone:

{
  "error": "signal_retired",
  "id": "831ecb98-66b4-4503-b6f7-b66a7477afc0",
  "relation": "dissolved",
  "last_seen": "2026-07-20T09:10:00.000Z",
  "successors": []
}

last_seen is omitted when it cannot be derived. An id that never existed still returns 404 not_found.

An existing Signal outside your country access returns 403 country_not_entitled. Responses use Cache-Control: private, max-age=60.

GET /api/v1/signals/{id}/imagery/{kind}.png#

Retrieve one attached satellite imagery chip. The route resolves retired merge and split ids to the same canonical active Signal as Signal detail, then applies the same country entitlement check. Customer organizations must also have the geospatial_v1 enrichment enabled.

A missing Signal, unknown imagery kind, pending row, failed row, terminal no-scene row, absent row, or missing enrichment grant returns the same 404 not_found. An existing Signal outside your country access returns 403 country_not_entitled.

Successful responses use Content-Type: image/png, Cache-Control: private, max-age=86400, and include the required attribution in X-Imagery-Attribution.

GET /api/v1/topics#

Topics group related Signals for browsing.

Topic ids are temporary. They can change between processing runs, and the API does not preserve old ids. Store Signal or Claim ids instead. Use filters to find the current Topics.

Results use a stable keyset order. Topic responses do not include rubric or annotations.

One active, labeled Signal within a Topic must satisfy every rubric and annotation filter. Two Signals cannot satisfy different parts of the same request. category, attribute_any, and codes within one annotation layer use OR. attribute, separate layers, and separate filter groups use AND.

Example:

{
  "topics": [
    {
      "id": "18aad58a-73fb-4966-a640-626c79aa7d39",
      "label": "Far North climate and displacement",
      "description": "Current reporting on seasonal hazards and their community impacts.",
      "country_code": "CM",
      "signal_count": 4,
      "claim_count": 18,
      "last_claim_at": "2026-07-20T08:45:00.000Z",
      "formed_at": "2026-07-20T09:00:00.000Z",
      "is_fallback": false
    }
  ],
  "nextPage": null,
  "pagination": {
    "limit": 50,
    "count": 1
  }
}

Responses use Cache-Control: private, max-age=60.

GET /api/v1/claims#

With query, results use word matching and semantic similarity across the accessible corpus. search.mode is hybrid, or lexical when the embedding service is unavailable. search.reranked indicates whether evidence-based reranking succeeded; false means the base retrieval order is used. search.truncated indicates more matches than the result limit; nextPage is null for search. Search is a relevance-ranked retrieval aid, not an exhaustive export. Without query, the existing paginated listing is unchanged. No results means no matching reports under the selected filters, not that no event occurred.

List immutable, extracted Claims with article, Source, geography, and current Signal assignment. Claims are ordered by numeric id.

When both time filters are present, both must match. Claims do not support rubric filters because rubric attributes belong to Signals. A new Claim may not have a Signal assignment yet, so rubric filtering would omit it from a poll.

To retrieve Claims under a current Topic, list its Signals with /signals?topic={id}. Then query Claims by each Signal id.

Example:

{
  "claims": [
    {
      "id": "5210",
      "claim": "Floodwater entered homes and interrupted access to a community water point.",
      "event_date": "2026-07-19",
    "occurred_on": "2026-07-19",
      "occurred_on": "2026-07-19",
      "extracted_at": "2026-07-20T08:45:00.000Z",
      "country_code": "CM",
      "geo_scope": "point",
      "place_name": "Mayo Crossing",
      "place_country": "CM",
      "region_code": null,
      "lat": 10.5912,
      "lng": 14.3157,
      "signal_id": null,
      "article": {
        "url": "https://cameroon-observer.example/far-north-flood-update",
        "title": "Communities report flood damage in Far North",
        "published_at": "2026-07-20T07:30:00.000Z"
      },
      "source": {
        "id": "a12e699c-cfa2-4ce9-8c01-bec72963ea91",
        "name": "Cameroon Observer",
        "language": "en",
        "country_code": "CM"
      }
    }
  ],
  "nextPage": "https://api.livingsignals.example/api/v1/claims?country=CM&limit=1&cursor=NTIxMA",
  "pagination": {
    "limit": 1,
    "count": 1
  }
}

article is present when the Claim retains a source-content URL. Its title and published_at can independently be null. The API decodes common and numeric HTML entities in article.title.

source is present when the Claim retains a Source id. Its name, language, and country_code can independently be null.

Distinguish the country fields:

Geography values:

Country- and region-scoped Claims do not include coordinates. Do not display them as point markers.

Availability and assignment timing#

Claims rejected or failed during extraction are not available through the API. /countries excludes them from Claim counts and coverage dates.

Extraction and Signal assignment happen separately. A new Claim appears in /claims immediately with signal_id: null. A later processing run may assign it to a Signal. Polling with since_extracted still returns the Claim. Retrieve GET /api/v1/claims/{id} again to get its current Signal assignment.

Polling recipe#

For incremental ingestion, record the poll time immediately before the request. Send it on the next poll as since_extracted=<previous poll time>. Overlap adjacent windows slightly and deduplicate by Claim id. This handles boundary timing, retries, and incomplete page walks.

Follow every non-null nextPage unchanged before you advance the poll time. This keeps the same filters and server-issued cursor across the page walk.

Do not use occurred_on or since as an incremental cursor. occurred_on describes source content. It may be old, null, or unreliable. since filters occurrence time and is not a polling watermark.

Responses use Cache-Control: private, max-age=30.

GET /api/v1/claims/{id}#

Retrieve one Claim in the same shape as a list item. The response wraps it in {"claim": ...}.

Example:

{
  "claim": {
    "id": "5210",
    "claim": "Floodwater entered homes and interrupted access to a community water point.",
    "event_date": "2026-07-19",
    "occurred_on": "2026-07-19",
    "extracted_at": "2026-07-20T08:45:00.000Z",
    "country_code": "CM",
    "geo_scope": "point",
    "place_name": "Mayo Crossing",
    "place_country": "CM",
    "region_code": null,
    "lat": 10.5912,
    "lng": 14.3157,
    "signal_id": "28eeab9d-47f6-4a2e-bd28-cafe6ad6ca19",
    "article": {
      "url": "https://cameroon-observer.example/far-north-flood-update",
      "title": "Communities report flood damage in Far North",
      "published_at": "2026-07-20T07:30:00.000Z"
    },
    "source": {
      "id": "a12e699c-cfa2-4ce9-8c01-bec72963ea91",
      "name": "Cameroon Observer",
      "language": "en",
      "country_code": "CM"
    }
  }
}

An existing Claim outside your country access returns 403 country_not_entitled. A missing, rejected, or failed Claim returns 404 not_found. Responses use Cache-Control: private, max-age=60.

GET /api/v1/sources#

List active Sources by country with recent Claim coverage. Each row represents one (source, country_code) pair. A Source appears once for each country it covers. Results are ordered by Source id and then country_code.

Country and language filters combine with AND.

Example:

{
  "sources": [
    {
      "id": "a12e699c-cfa2-4ce9-8c01-bec72963ea91",
      "name": "Cameroon Observer",
      "url": "https://cameroon-observer.example",
      "domain": "cameroon-observer.example",
      "language": "en",
      "country_code": "CM",
      "type": "newspaper_independent",
      "claim_count_30d": 143
    }
  ],
  "nextPage": null,
  "pagination": {
    "limit": 100,
    "count": 1
  }
}

Source type values:

type may contain any string or null. Preserve values you do not recognize. Responses use Cache-Control: private, max-age=300.

GET /api/v1/docs and GET /api/v1/openapi.json#

Use these public endpoints to retrieve the Markdown and OpenAPI references. They serve fixed documents, so query parameters do not change the response.

Markdown response:

# Living Signals REST API v1

Use the read-only Living Signals REST API to explore news-derived Claims,
corroborated Signals, and related Topics.

OpenAPI response excerpt:

{
  "openapi": "3.1.0",
  "info": {
    "title": "Living Signals API",
    "version": "v1"
  },
  "paths": {
    "/api/v1/signals": {
      "get": {
        "summary": "List Signals"
      }
    },
    "/api/v1/claims": {
      "get": {
        "summary": "List Claims"
      }
    }
  }
}

Browse the OpenAPI document at /reference. Responses from /docs and /openapi.json use Cache-Control: public, max-age=3600.

Signal lifecycle and id stability#

Claim ids are immutable. Signal ids are durable references. When a merge or split retires an id, GET /api/v1/signals/{id} follows lineage transitively to the primary active successor and returns its full payload with resolved_from. Primary successors are selected by highest stored overlap, then by the latest transition time.

Claims in the response always belong to the canonical Signal; the API does not combine Claims from historical identities. When resolved_from appears, update the stored reference to the returned signal.id.

If an id existed but no active successor remains, the detail endpoint returns the structured 410 signal_retired body with an empty successors array. An id that never existed returns 404 not_found.

A Signal can move to a different Topic without receiving a new Claim. Treat signal.topic as current browsing context, not durable identity.

Signals do not expose updated_at or a since_updated watermark. Incremental Claim polling cannot fully reveal relabels, merges, annotation updates, or Topic changes. Periodically perform a complete Signal sync in addition to polling Claims.

Appendix: rubric vocabulary#

The rubric assigns binary attributes to each Signal. Multiple attributes can be true. Categories group related attributes. A Signal belongs to a category when any member attribute is true, so category membership is derived and can also have multiple values.

GET /api/v1/rubric is the machine-readable source of truth. Its category order and member order match these tables.

violence_harm — Violence & Harm#

conflict_intensity — Conflict & Unrest#

displacement — Displacement & Migration#

natural_disasters — Natural Disasters#

health_humanitarian — Health & Humanitarian#

environmental — Environmental#

actors — Actors Involved#

affected_populations — Affected Populations#

women_peace_security — Women, Peace & Security#

structural — Social Harms#

positive_signals — Peace, Justice & Reform#

Attributes without a category#

These attributes do not belong to a category. You can still filter by them with attribute and attribute_any. They also appear in rubric.attributes. In GET /api/v1/rubric, they have label: null and an empty categories array. The section field groups them by theme.

harm_type#

actors#

affected_population#

causation#

sector#

verification#

Appendix: annotation layers#

Annotation layers map Signals to attributed, independent classification vocabularies. Each layer is versioned. Annotation layers appear only on Signals and do not affect how Signals or Topics form.

Use GET /api/v1/countries to discover available layer ids in annotation_layers. Use GET /api/v1/annotation-layers to retrieve each layer's version, attribution, and complete code vocabulary. Customer keys receive granted layers. Team keys receive every registered layer.

For a customer key, interpret annotations this way:

For a team key, omitting include_annotations, sending an empty value, or sending include_annotations=false omits all annotations. An absent layer then says nothing about its grading state. Send include_annotations=true before you use the table as an all-layer view.

Annotation example:

{
  "annotations": {
    "glide_v1": {
      "codes": ["fl"],
      "rationale": "The Signal describes river flooding."
    }
  }
}

API codes use lowercase snake_case. GLIDE uses lowercase two-letter codes. The _v1 suffix pins the vocabulary version. Discover codes from /annotation-layers instead of assuming that versions share the same values.

glide_v1 — GLIDE disaster event types#

GLIDE is the GLobal IDEntifier number disaster-event taxonomy. API values are lowercase; canonical GLIDE codes are uppercase two-letter codes.

acled_v1 — ACLED event sub-types#

ACLED is the Armed Conflict Location & Event Data Project taxonomy. API codes are slugified forms of ACLED's canonical sub-event type names. The event-type family in each meaning also comes from the registered definition.

iasc_v1 — IASC humanitarian coordination clusters#

IASC is the Inter-Agency Standing Committee humanitarian coordination standard. API codes map to its canonical domain names.

iep_positive_peace_v1 — IEP Positive Peace pillars#

Positive Peace is the Institute for Economics & Peace framework describing the attitudes, institutions, and structures that sustain peaceful societies. API codes map to its pillar names.

This layer describes the societal condition a Signal speaks to, not what happened. Positive Peace is defined against the absence of violence, which IEP measures separately through the Global Peace Index, so violent events, natural hazards, and their humanitarian impacts carry no pillar and return an empty codes array. Use glide_v1 and acled_v1 to classify those.

A pillar names the condition under discussion, never a verdict that the condition is in good health. An anti-corruption prosecution and an embezzlement scandal both carry low_levels_of_corruption. Read the code together with directions, which records which way the evidence points for each assigned code:

So a report of extrajudicial killings returns well_functioning_government with direction eroding — the Signal is about the rule of law, and the rule of law is failing.

To filter on direction, attach it to the pillar it applies to:

?iep_positive_peace_v1=well_functioning_government:eroding

The direction is scoped to that pillar, so a Signal whose rule of law is strengthening does not match, even if another of its pillars is eroding. Pillars in the same request are independent — well_functioning_government:eroding,low_levels_of_corruption narrows the first and leaves the second matching in any direction. To ask the looser question across the whole layer, use iep_positive_peace_v1_direction on its own.

A pillar is recorded only where the Signal reveals something about how the condition stands. Routine administration — procurement, workshops, ceremonies, appointments, internal meetings — and internal political party business such as primaries and campaign strategy carry no pillar on their own.

The Positive Peace Index indicators beneath these pillars measure countries over years rather than classify events, and are not part of this layer. No IEP index values are reproduced through this API.

geospatial_v1 — Living Signals geospatial imagery suitability#

This focused operational layer records whether a Signal describes already observed physical effects that may support a useful 10 m/pixel optical satellite chip. It is independent of the rubric. Signals about ceremonies, inaugurations, commissionings, openings, financing approvals, plans, appeals, or statements about physical things receive an empty codes array.