How Graph Cast works

Graph Cast is a managed cloud service for modeling, validating, storing, and querying impact measurement data structured according to the Common Impact Data Standard (CIDS). It exposes a standard REST API with domain-level building blocks — organizations, outcomes, indicators, reports — so you can manage impact data in a graph database without needing to understand graph query languages, RDF serialization, or CIDS internals. You build on Graph Cast the same way you’d build on any conventional API; CIDS conformance and the underlying graph infrastructure are handled for you.

API      https://api.cast.commonapproach.org
Console  https://app.cast.commonapproach.org

Interactive OpenAPI documentation is served by the API itself at /docs. The console is where you manage namespaces and API keys, try endpoints in the Playground, and open CIDS data in the browser.

Authentication

Every data request carries two headers:

Header	Purpose
X-API-Key	Your API key — ties the request to your tenant
X-Namespace	The target dataset — explicit on every call, no default

Create and manage keys in the console under API → Settings. Keys are shown once at creation and stored only as a hash — copy immediately.

Keys can optionally be restricted to specific namespaces, so a key issued for one integration can never touch another namespace’s data, even by accident.

Tenants and namespaces

Your tenant is derived from your API key. It is never sent by the client and never guessable. Within a tenant you create namespaces: fully isolated datasets. Use them per environment, per portfolio, per customer — your call.

Every data request names its namespace via the X-Namespace header. There is no default, and an unknown namespace is a hard 404. Namespaces must be created explicitly before use (POST /namespaces).

Getting data in

The CRUD lane

Build a theory of change incrementally with flat JSON: organization → outcomes → indicators → indicator reports. Each create supplies the entity’s own URI — Graph Cast never invents identifiers (see Identifiers).

This is the path for form-based or spreadsheet-driven intake, where data arrives field by field.

The capsule lane

Upload a complete CIDS/SFF JSON-LD document — an “impact data capsule.” Capsules are validated as a whole, stored atomically, and can be rolled back atomically. Everything a capsule carries — organization profiles, addresses, people, team profiles, funding statuses — is preserved verbatim and included in exports.

This is the path for data that already exists in CIDS form, such as an export from another aligned platform.

Both lanes write into the same graph. An entity is the same entity in both lanes when it has the same URI.

Validation

Capsules are validated against a focused subset of the official CIDS Basic Tier SHACL shapes before anything is stored. A violation rejects the entire capsule and stores nothing. Warnings are accepted and reported.

Validation reports are written in plain language — they’re designed to be forwarded verbatim to whoever produced the file. Details in Working with capsules.

CRUD-lane writes are validated at the field level: missing required fields, malformed URIs, and invalid references are caught immediately and return a clear error.

Getting data out

Table reads

/rows/indicator-reports — flat, denormalized rows across your whole dataset, with filters for theme, fund, organization, and date range. Each row carries its indicator, outcome, themes, and organization, so the graph joins are already done. Built for dashboards and portfolio analysis.

Tree reads

/orgs/{id}?expand=… and /orgs/{id}/everything — one organization and its full theory of change as a nested document: outcomes containing indicators containing reports. Built for organization detail views.

Export

/export — everything in a namespace (or one organization’s subgraph) as CIDS JSON-LD or N-Quads, returning exactly the identifiers that were submitted.

Where next

• Quickstart — from API key to first query in ten minutes.
• Identifiers — how entity identity works. Read this before integrating.
• Capsules — uploading, validation, rollback, and modelling funds.
• Querying — table reads, facets, filters, and tree reads.
• API reference — the error contract and the full endpoint table.
• Console — namespaces, keys, the Playground, and checking what your integration produced.