Build Your First Integration

From zero knowledge to live humanitarian data in about ten minutes — the mental model, your first authenticated request, and two real queries.

This is the front door. If you’ve never touched the CLEAR API before, read this page top to bottom. By the end you’ll understand how the data is shaped and you’ll have pulled real records with your own API key. Everything else in these docs — the Queries, Mutations, and Types reference — is there to look things up after you understand the shape of the system.

1. The mental model

CLEAR is a five-tier graph. Raw observations flow in at the bottom and are progressively grouped, classified, and escalated into human-readable advisories. Almost every query you write touches one of these five tiers:

Two things to internalise. First, the tiers build upward: a Signal links to the Event it belongs to, which links to any Alert raised from it. Second, everything is geolocated — signals, events, and alerts all reference the Location hierarchy. That’s why the “by location” queries are the most powerful way to slice the data.

One staging area sits in front of tier 2. The ground staging tier holds staged Signals — messages ingested from ground sources such as WhatsApp groups (GroundMessage) — grouped into threads (GroundThread). A thread is a cluster of staged Signals with a correction lifecycle; when a reviewer approves a thread for publication, it is promoted and becomes a Signal. Nothing enters the signals graph from a ground source without passing that review gate.

2. Get set up

You need an account and an API key. Both live in the Developer Portal.

3. Your first request

The me query is the simplest authenticated call: it returns the account your key belongs to. Run it first to confirm your key works before you touch real data. Replace YOUR_API_KEY with the key you just generated:

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { id email role } }"}'Copy

A successful response echoes your own user back:

{
  "data": {
    "me": {
      "id": "aBc123XyZ",
      "email": "you@example.com",
      "role": "viewer"
    }
  }
}Copy

If me comes back null, your key isn’t being read — double-check the Authorization header and that the key hasn’t been revoked in the portal.

4. Pull real data

Now something useful. Locations are the backbone of the graph, so start there: this lists every country CLEAR tracks (hierarchy level 0), with each one’s id, name, and resident population.

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ locations(level: 0) { id name population } }"}'Copy

You’ll get back an array of Location objects. Grab the id of a country that interests you — you’ll feed it into the next query.

5. Slice by location

This is where it gets powerful. eventsByLocation returns every event whose origin, destination, or general location falls within a location and all of its descendants — so one country id gives you everything happening anywhere inside that country. Drop in the id from the previous step:

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query($loc: String!) { eventsByLocation(locationId: $loc) { id title severity types generalLocation { name level } } }","variables":{"loc":"YOUR_LOCATION_ID"}}'Copy

Each Event comes back with a severity from 1 (low) to 5 (severe), its disaster-type types tags, and the place it’s bound to. From any event you can follow the graph further — ask for its signals to see the raw observations underneath, or its alerts to see what was escalated from it.

Where to go next

You now know the shape of the graph and how to authenticate, query, and slice by location. From here:

• Browse the full Queries and Types reference below — it’s auto-generated from the live schema, so it’s always current.
• Open the GraphQL Sandbox to build queries interactively with field autocomplete.
• Read the Authentication section for the browser/cookie flow if you’re building a web app rather than a server integration.
• Manage your keys anytime in the Developer Portal.

Quick Start

Go from zero to your first API response in three steps.

curl -X POST https://api.clearinitiative.io/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ me { id email } }"}'Copy

Want to explore interactively? Open the GraphQL Sandbox to browse the full schema, autocomplete queries, and test requests in your browser.

Authentication

Two ways to authenticate, depending on your use case.

API Keys (server-to-server)

Pass your key as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_your_key_hereCopy

Session Cookies (browser apps)

Sign in via the REST auth API. The session cookie is set automatically and sent with subsequent requests:

// Sign in
const res = await fetch('/api/auth/sign-in/email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ email: 'you@example.com', password: '...' }),
});

// Then query (cookie sent automatically)
const data = await fetch('/graphql', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({ query: '{ me { id email } }' }),
});Copy

Queries

Mutations

Types

All types in the schema, auto-generated from the running server.

DateTime scalar

ISO 8601 date-time string (e.g. 2024-01-15T09:30:00.000Z).

GeoJSON scalar

JSON scalar

Arbitrary JSON value — objects, arrays, strings, numbers, booleans, or null.

Upload scalar

File upload scalar (via graphql-upload).

AlertOrderBy enum

AlertStatus enum

Publication status of an alert.

Channel enum

Notification channel for alert subscriptions.

CrisisEnrichmentStatus enum

Durable enrichment status for the Dagster drain. PENDING = needs (re)enrichment (set on crisis create / event add / event remove); ENRICHED = narrative/scenarios/needs-analysis current.

DetectionStatus enum

Processing status of a detection (retained for potential future use).

EntityKind enum

EventOrderBy enum

Frequency enum

How often a user receives alert notifications.

InvitationStatus enum

Status of an invitation.

KnowledgebaseIngestStatus enum

Coarse-grained status of a manual-ingest Dagster run. Dagster's own RunStatus enum is finer-grained (STARTING / MANAGED / CANCELING / …) — we fold those down to what a UI actually needs to render.

NotificationStatus enum

OrgMemberRole enum

Role within an organisation.

SignalOrderBy enum

SignalStatus enum

Durable processing status for the Dagster event-driven drain. NEW = ingested, awaiting downstream processing; PROCESSED = classify→group→ alert done; FAILED = terminal failure.

StatsGroupBy enum

TeamMemberRole enum

Role within a team.

WebhookDeliveryStatus enum

AcceptInviteInput input

ActivityLogFilterInput input

Filter for the paginated activityLogs query.

AddCommentInput input

AddFeedbackInput input

AlertDigestInput input

AlertNotifyInput input

AlertsPageInput input

CreateAlertInput input

CreateApiKeyInput input

Input for creating a new API key.

CreateBulkNotificationsInput input

CreateCrisisFromEventsInput input

CreateDataSourceInput input

CreateDevUserInput input

Input for `createDevUser`.

CreateEventInput input

CreateGroundSourceInput input

CreateLocationInput input

CreateManualSignalInput input

CreateNotificationInput input

CreateOrganisationInput input

Fields for creating a new organisation.

CreatePublicEventLinkInput input

Input for the `createPublicEventLink` mutation.

CreateSignalInput input

CreateTeamInput input

CreateWebhookSubscriptionInput input

Input for creating a new webhook subscription. The secret is generated server-side (openssl rand -hex 32 equivalent) and returned once on create.

DateRangeInput input

Half-open date window (from inclusive, to exclusive) used to filter `searchKnowledgebase` by the chunk's extracted event window. Chunks whose time_range overlaps the window match.

EntityStatsInput input

EventsPageInput input

FindOrCreateLandmarkL4Input input

Input for findOrCreateLandmarkL4. Drives geoparser-based L4 promotion in the signal-ingestion pipeline.

GroundMessageClassificationInput input

One classification write-back from the pipeline worker.

GroundThreadUpsertInput input

One thread (a cluster of staged Signals) produced by the pipeline threading task. Its messageIds are re-pointed at the thread, replacing their V1 one-per-message placeholder threads. With `threadId` set, the input APPENDS to that existing thread (cross-run threading: late corrections/retractions join the thread they belong to) instead of creating a new one.

InviteUserInput input

KnowledgebaseChunkInput input

One chunk written into the knowledgebase table. Mirrors the columns exactly (minus `lexicalTsv`, which the DB trigger fills from `embeddedText`, and `createdAt` which uses the column default).

KnowledgebaseFilters input

Optional filters applied BEFORE the retrieval step — array filters use overlap semantics (any-of), the time range uses inclusive intersection. Leave a field null to skip that filter.

LocaleTranslationInput input

Per-locale payload accepted by upsertTranslations. data mirrors the canonical entity's JSON shape exactly for the given locale — e.g. for a crisis it carries the localized title/summary/scenarios/needs with the same keys/nesting the English columns use.

ReplyToCommentInput input

SignalsPageInput input

SubmitSignalLocationChallengeInput input

SubscribeToAlertsBatchInput input

SubscribeToAlertsInput input

TeamAssignmentInput input

One (team, role) assignment passed to inviteUser.

UpdateAlertInput input

UpdateAlertSubscriptionInput input

UpdateCrisisPopulationInput input

UpdateDataSourceInput input

UpdateEventInput input

UpdateGroundSourceInput input

Partial update of a source's policy record. Null/omitted fields are left unchanged; transportId is immutable (it is the identity that externalIds are minted against). The merged row is re-validated: group kinds must end up with a complete consent record.

UpdateLocationInput input

UpdateOrganisationInput input

Fields for updating an existing organisation.

UpdateProfileInput input

UpdateTeamInput input

UpdateWebhookSubscriptionInput input

Input for updating an existing subscription. All fields are optional — provide only what you want to change.

UpsertLocationMetadataInput input

UpsertNominatimCacheInput input

UpsertReportDatapointsInput input

Input for `upsertReportDatapoints`. Field names / types mirror the ReportDatapoint output so a client can echo one back into the other with minimal transformation.

UpsertSituationAnalysisInput input

UpsertTranslationsInput input

ActivityCountsByAction object

ActivityLog object

A single user-initiated action recorded for analytics.

ActivityStats object

Aggregate counts and time-series for the admin dashboard.

AggregatedDatapoint object

One aggregated bucket - the roll-up of every contributing `report_datapoint` for a scope (window × window_kind × location). Consumed by the situation-analysis dashboard tiles and by chatbot factual queries. See `AggregatedField` docstring for the JSON `data` shape.

Alert object

An alert created from an event, distributed to subscribed users.

AlertsPage object

AlertSubscription object

A user's subscription to alerts of a specific type at a specific location.

ApiKey object

A personal API key for programmatic access. The full key is only shown once at creation.

ApproveUserResult object

Result of the admin-only `approveUser` mutation. Flips a `pending` user's role to `viewer` and moves the matching CRM contact from the prospects collection into the approved collection, triggering Exponential's welcome automation.

ArchiveStaleAlertsResult object

Result of the archiveStaleAlerts bulk mutation.

CommentTag object

A tag linking a user to a comment.

CreateApiKeyPayload object

Returned only from createApiKey. Contains the full plaintext key that will never be retrievable again.

CreateDevUserResult object

Result of the admin-only `createDevUser` mutation. The plaintext API key is returned only here — it is never stored and cannot be retrieved later. The admin UI surfaces it once so the operator can copy-paste it in case the welcome email bounces.

CreatePublicEventLinkResult object

Returned once from `createPublicEventLink`. The token is part of the URL and not retrievable again — same one-time-show semantics as `createApiKey`.

Crisis object

A crisis aggregates multiple events into a single coherent narrative.

CurrentTotals object

Estimated current totals for a country bucket (ADR-0006 §4). Each metric is `null` when there is no anchoring stock in scope to accrue flows onto.

DailyActivityCount object

DataSource object

An external data source that feeds signals into the system.

DauPoint object

One day in a DAU time series.

DisasterLevel1 object

A level-1 category with its level-2 groups.

DisasterLevel2 object

A level-2 group with its distinct classification codes.

DisasterType object

A disaster classification in a 3-level hierarchy (level1 > level2 > level3). Events store arrays of codes (GLIDE or CLEAR IDs).

EntityStats object

Event object

An event grouping related signals into a coherent narrative.

EventCrisis object

Link between a crisis and an event.

EventEscalation object

Tracks a user escalating an event, optionally to a crisis.

EventsPage object

FeatureFlag object

A feature toggle that controls runtime behavior.

FindOrCreateLandmarkL4Result object

Outcome of findOrCreateLandmarkL4.

GazetteerHit object

A GeoNames gazetteer match for a place name. Coordinates come straight from GeoNames — callers still validate them (e.g. the same-A2 check against a signal's source coordinates) before trusting a fuzzy hit.

GroundIngestResult object

Result of a chat-export ingest (also returned by the REST upload route as JSON).

GroundMessage object

A staged Signal: a canonical message parsed from a WhatsApp source, held in the ground staging tier until its thread is reviewed. Text is phone-number-redacted at persistence. senderName is private-tier data and is scrubbed from anything promoted to the signals graph.

GroundMessageForClassification object

Pipeline-facing projection of a staged Signal for the classification/threading worker (clear-pipeline's classify_ground_messages task). Deliberately excludes senderName — the pipeline never sees private-tier identity, only the pseudonymous senderRef.

GroundSource object

Per-source policy record for ground intelligence (WhatsApp groups, future hotline). Carries the consent scope, privacy default, reviewer roles, and retention rule for everything ingested from the source. The whole ground staging tier is private: admin/analyst only.

GroundThread object

A thread — a cluster of staged Signals — in the review queue. V1 threads are one-per-message placeholders until the pipeline threading task clusters them. Lifecycle state models the correction chain; review state is the human gate in front of the signals graph. An approved thread is promoted and becomes a Signal.

Invitation object

An invitation to join an organisation, with one or more team assignments.

InvitationInfo object

Public invitation info returned by token lookup (limited fields).

InvitationInfoTeam object

One (team, role) assignment as returned by the public token lookup.

InvitationTeam object

One (team, role) assignment attached to an invitation.

KnowledgebaseHit object

One hit from `searchKnowledgebase`. Carries enough source provenance (report title, url, page range) that a UI can render a citation without a follow-up fetch, plus the parameter arrays so the caller can highlight which filters matched.

KnowledgebaseIngestJob object

One Dagster run kicked off by `uploadKnowledgebaseDocument`. Returned by both the mutation (initial launch) and the polling query. `reportId` / `reportTitle` / `s3Key` are populated from the run's Dagster tags, which the mutation attaches at launch time — a client that lost track of the initial payload can still recover the identity of the document being ingested.

Location object

A geographic location in a hierarchy (country > state > city, etc.).

LocationMetadata object

Arbitrary per-location metadata keyed by type. History is preserved: writes close the current row (set validTo = now()) and insert a new one. The CURRENT value for a (location, type) is the row where validTo is null.

MauPoint object

One month in a MAU time series.

NominatimCacheEntry object

A cached Nominatim-protocol geocoder response.

Notification object

Organisation object

An organisation that owns teams and has members.

OrganisationUser object

Links a user to an organisation with a role.

OrgMember object

Links a user to an organisation with an org-level role.

PipelineCountry object

A country the CLEAR pipeline publishes a Situation Analysis for, with the bounding box used to create its level-0 Country location. bbox order matches ensureCountryLocation: [minLng, minLat, maxLng, maxLat].

PublicEvent object

The slim, unauthenticated view of an event used for share-link rendering. Deliberately a new type — not a slim wrapper around `Event` — so the field set is auditable in one place and field- selection can't accidentally leak signals, comments, alerts, or any other gated data through the public surface. Returned by the `publicEvent(eventId, token)` query when the Redis-cached snapshot for that token is still alive. Cache TTL defaults to 30 days; entries can be evicted earlier under memory pressure, in which case the link expires and the user has to request a new one.

PublicEventSignalPoint object

One Point location attached to one of the event's signals.

RefreshAggregatedDatapointsResult object

Summary counts from a `refreshAggregatedDatapoints` run.