Docs › START HERE › Build Your First Integration

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.

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.

Docs › GET STARTED › Introduction

Introduction

Welcome to the CLEAR API - your gateway to humanitarian intelligence.

The CLEAR API gives you programmatic access to signals, events, alerts, data sources, and geographic location data through a single GraphQL endpoint. Whether you’re building a monitoring dashboard, integrating alerts into your workflow, or analysing humanitarian patterns, this API has you covered.

Everything here is accessible via GraphQL at /graphql. You send a query describing exactly the data you want, and you get back precisely that — nothing more, nothing less.

What You Can Do

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.

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.

NotificationStatus enum

OrgMemberRole enum

Role within an organisation.

SignalOrderBy enum

StatsGroupBy enum

TeamMemberRole enum

Role within a team.

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

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

EntityStatsInput input

EventsPageInput input

FindOrCreateLandmarkL4Input input

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

InviteUserInput input

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

SubscribeToAlertsBatchInput input

SubscribeToAlertsInput input

TeamAssignmentInput input

One (team, role) assignment passed to inviteUser.

UpdateAlertInput input

UpdateAlertSubscriptionInput input

UpdateCrisisPopulationInput input

UpdateDataSourceInput input

UpdateEventInput input

UpdateLocationInput input

UpdateOrganisationInput input

Fields for updating an existing organisation.

UpdateProfileInput input

UpdateTeamInput input

UpsertLocationMetadataInput input

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

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.

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.

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.

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.

RotateDevUserApiKeyResult object

Result of the admin-only `rotateDevUserApiKey` mutation.

Signal object

A signal derived from a data source.

SignalsPage object

StatsBucket object

Team object

A team within an organisation, scoped to specific locations.

TeamMember object

Links a user to a team with a team-level role.

TranslationCoverage object

Per-(entity_type, locale) coverage snapshot used by the admin dashboard to see how much of the catalog has been translated. - canonicalCount: total entities of this type that *could* be translated (i.e. exist in the canonical table). - translatedCount: number with a row in the translations sidecar for this locale. The fraction translatedCount / canonicalCount is the live coverage for that (type, locale) cell — anything < 1.0 means the next read of one of the missing entities by a user on that locale will fall back to canonical English (and trigger the lazy-on-read enqueue, see utils/translation-loader.ts).

TranslationRow object

A single translation row, returned by the admin/pipeline-only translations(entityType, entityId) query so the pipeline can compare stored source-hashes against the canonical row and decide which fields (if any) need re-translating.

UpsertTranslationsResult object

Result of upserting one or more locale rows for a given entity. Carries the locales that were written so the caller (typically clear-pipeline) can confirm coverage without a follow-up read.

User object

A registered user with role-based access. PII fields (`email`, `phoneNumber`, `role`, `isActive`) and the private relation set (`alerts`, `notifications`, `organisations`, `teamMemberships`, `feedbacks`, `comments`, `escalations`) are gated server-side: - PII: returned when caller IS the user, is a global admin, OR shares at least one organisation with the user. Otherwise null (PII) or empty array (private relations). - Private relations: returned only when caller IS the user OR is a global admin. Sharing an organisation does NOT grant access to another member's inbox / comment history. Schema makes these fields nullable so the gate can return null when the caller is not authorised, instead of throwing — a logged-in analyst browsing an event's comments shouldn't see a hard error on the commenter's email.

UserActivitySummary object

UserAlert object

Tracks an alert delivered to a user — view status.

UserComment object

A user comment on a signal, event, or crisis, with reply support.

UserEngagementMetrics object

Point-in-time engagement summary derived from auth.login activity. All three windows are trailing from `asOf` (inclusive).

UserFeedback object

User feedback on a signal, event, or crisis — rating and optional text.