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

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

Frequency enum

How often a user receives alert notifications.

InvitationStatus enum

Status of an invitation.

NotificationStatus enum

OrgMemberRole enum

Role within an organisation.

TeamMemberRole enum

Role within a team.

AcceptInviteInput input

AddCommentInput input

AddFeedbackInput input

AlertDigestInput input

AlertNotifyInput input

CreateAlertInput input

CreateApiKeyInput input

Input for creating a new API key.

CreateBulkNotificationsInput input

CreateCrisisFromEventsInput input

CreateDataSourceInput input

CreateEventInput input

CreateLocationInput input

CreateManualSignalInput input

CreateNotificationInput input

CreateOrganisationInput input

Fields for creating a new organisation.

CreateSignalInput input

CreateTeamInput input

InviteUserInput input

ReplyToCommentInput 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

Alert object

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

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.

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.

Crisis object

A crisis aggregates multiple events into a single coherent narrative.

DataSource object

An external data source that feeds signals into the system.

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

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.

FeatureFlag object

A feature toggle that controls runtime behavior.

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.

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.

Signal object

A signal derived from a data source.

Team object

A team within an organisation, scoped to specific locations.

TeamMember object

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

User object

A registered user with role-based access.

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.

UserFeedback object

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