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

GeoJSON scalar

GeoJSON object (RFC 7946)

JSON scalar

Arbitrary JSON value

AlertStatus enum

Publication status of an alert.

DetectionStatus enum

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

NotificationStatus enum

CreateAlertInput input

CreateApiKeyInput input

Input for creating a new API key.

CreateDataSourceInput input

CreateEventInput input

CreateLocationInput input

CreateNotificationInput input

CreateSignalInput input

UpdateAlertInput input

UpdateDataSourceInput input

UpdateEventInput input

UpdateLocationInput input

UpdateProfileInput input

Alert object

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

ApiKey object

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

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.

DataSource object

An external data source that feeds signals into the system.

DisasterType object

A disaster classification with GLIDE number.

Event object

An event grouping related signals into a coherent situation.

EventEscalation object

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

FeatureFlag object

A feature toggle that controls runtime behavior.

Location object

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

Notification object

OrganisationUser object

Links a user to an organisation with a role.

Signal object

A signal derived from a data source.

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 or event, with reply support.

UserFeedback object

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