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. Source 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 source observations underneath (title, location, severity — not the upstream source payload), 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.

AnalysisRequestStatus enum

CaseProposalDecision enum

The decision a named admin or analyst records on a proposed case.

CaseProposalState enum

A web Worker writes `proposed` only (V4). A named admin or analyst accepts or rejects each case; a rejected one stays, so its URL is never proposed again for the same Event.

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

EstimateAttribution enum

Whether a figure counts need caused by the Event, need that existed beforehand, or both.

EstimateMethod enum

How a figure was arrived at (the Domain Ontology's Estimate methods). `not_documented` when the method is unknown, e.g. figures backfilled from the pipeline's Event fields.

EstimateMetric enum

Which of the seven distinct figures an Estimate is (the Domain Ontology's Metric types). The sector routinely conflates them; keeping them apart is the point.

EventOrderBy enum

Frequency enum

How often a user receives alert notifications.

GlobalRole enum

Assignable global platform roles. `pending` is not in this enum — those users must go through `approveUser` first.

GroundPipelineStage enum

A clear-pipeline ground drain stage that can give up on a message.

GroundTranslationStatus enum

Where a message's on-demand translation stands.

ImpactPriorState enum

The state a V1–V3 whole-prior proposal was left in. Retired: none is created or decided any more.

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.

KnowledgebaseSearchMode enum

How `searchKnowledgebase` merges the report + incident tiers (ADR-0006).

KnowledgebaseTier enum

A knowledgebase tier (ADR-0006). `report` = the ReliefWeb state/analysis KB; `incident` = an event card from the incident index (lower-tier, possibly unverified). Lowercase values match the stored tier strings.

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

TaskOrigin enum

Who asked for the Task: a signed-in user, an automatic rule, or an API-key caller.

TaskStatus enum

Lifecycle of a Task. PENDING → LEASED (claimed) → COMPLETED | FAILED; PENDING or LEASED → CANCELLED. An expired lease returns the Task to PENDING lazily, at the next claim. Tasks are never deleted.

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

AnalysisFrameInput input

A frame — the scope of an analysis. `windowEnd` omitted / null means rolling "to present". Array members are order-insensitive (canonicalised server-side).

CaseFigureInput input

One figure a case's source gives.

CaseProposalInput input

One case a web Worker proposes on completing an `event.impact_prior.web` Task (V4).

ConversationMessageInput input

One message to create or replace, matched by id.

ConversationTurnUsageInput input

What one CLEAR Agent turn used. Recorded on its Answer.

CreateAlertInput input

CreateAnalysisAutomationInput 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.

GroundMessageFailureInput input

One failure marker from a clear-pipeline ground drain.

GroundMessageTranscriptInput input

One transcription write-back from the ground_transcribe worker.

GroundPromotionOverridesInput input

Reviewer edits applied to the signal a thread is promoted into (reviewGroundThread approve_public only). Omitted, null or blank fields keep the default derived from the thread (thread title; the joined message text as description; no severity; no location). The signal's rawData provenance is never affected.

GroundThreadDraftInput input

One enrichment draft from the Dagster hotline-enrichment job. Null fields leave the existing draft value on the thread unchanged.

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

ReportFigureInput input

RequestAnalysisInput input

SaveAgentWorkingMemoryInput input

Replace your Agent working memory. Omitted fields stay unchanged.

SignalsPageInput input

SubmitSignalLocationChallengeInput input

SubscribeToAlertsBatchInput input

SubscribeToAlertsInput input

TaskUsageInput input

Spend a Worker reports when completing a Task. Cost is computed by the caller from its own price table.

TeamAssignmentInput input

One (team, role) assignment passed to inviteUser.

UpdateAlertInput input

UpdateAlertSubscriptionInput input

UpdateAnalysisAutomationInput 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

UpdateSignalContentInput input

UpdateTeamInput input

UpdateWebhookSubscriptionInput input

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

UpsertAnalysisInput input

UpsertConversationInput input

Create a Conversation with a caller-supplied id, or update its title or metadata.

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.

UpsertReportFiguresInput input

Replace-on-reingest payload for one report's figures (pipeline-only).

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.

AgentBudget object

Your daily CLEAR Agent budget. Spend is the sum of your turns' cost since UTC midnight; the budget resets at the next UTC midnight.

AgentWorkingMemory object

What the CLEAR Agent keeps about you across Threads (its working memory). Yours only: no one else, admins included, can read or write it.

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.

Analysis object

A single frame-scoped analysis snapshot. Cache read path — always the current row for its frame unless `asOf` is supplied for a historical read.

AnalysisAutomation object

A subscription that keeps one frame's analysis current on a cadence (ADR-0007 §5). The analysis row is shared; the scheduler regenerates each frame at the minimum cadence across its subscribers. Automations are always rolling ("to present"), so they carry no `windowEnd`.

AnalysisRequest object

An on-demand analysis generation request (ADR-0007 §4). A user enqueues a frame that may not exist yet; a pipeline sensor drains `pendingAnalyses`, generates + upserts the analysis, and marks the request `GENERATED`. Scheduled refreshes use `AnalysisAutomation` instead of this one-shot queue.

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.

CaseProposal object

One historical case a web Worker found while enriching an Event (V4): a past incident like it, the source that reports it, the figures it gives, and the CLEAR Event it describes when CLEAR already holds one. The unit an analyst accepts or rejects, one by one, in the Inbox and on the Event page.