How Lab works

Common Approach Lab (formerly Graph Cast) is Common Approach’s platform for impact data in the Common Impact Data Standard (CIDS): a place to build data capsules and bring impact data to life. It has two sides.

The console is the browser side. Report senders — charities, nonprofits, and purpose-driven businesses — build an impact data capsule from a reporting spreadsheet or PDF, keep it, and submit it to their funders. Report receivers — funders, grantmakers, investors, and finance intermediaries — collect the capsules sent to them, review them and give feedback, and explore, analyze, and visualize the data. Everything on this side runs in the browser on files saved to the account.
The API is the integration side, for developers. It is a conventional REST API over a graph store: push capsules in, keep them validated and isolated per tenant and namespace, and pull tables out for dashboards and warehouses. You build on it the same way you’d build on any JSON API — CIDS conformance and the graph infrastructure are handled for you, and you never write SPARQL or touch RDF serialization.

These pages document the API side, with one page on the console for the roles, the browser-side pages, and the places where the two sides meet.

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 choose a role, 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. The API item is shown to accounts with the Developer role (chosen on the Start page when you register, or under Settings later) and to Common Approach staff. 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. One sign-up creates one tenant, pinned to a data residency region (Canada today). 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).

One namespace is reserved: ~explorer holds the account’s capsule files — what the console’s browser-side pages open and what senders submit to receivers. Files there are never ingested into the graph, and every graph endpoint refuses that namespace. See the console for the bridges between the two.

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 — Lab 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: an export from another aligned platform, or a capsule an organization built and submitted through the console.

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. The same envelope serves dimension tables (/rows/organizations, /rows/outcomes, /rows/indicators, /rows/funding-statuses) and a versioned snapshot export of any table for scheduled pulls.

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, one capsule, or one organization’s subgraph as CIDS JSON-LD or N-Quads, returning exactly the identifiers that were submitted. Exports are delivered through a short-lived download URL; filtered exports (chosen organizations, a reporting period) run as background jobs.

Common Framework

The console’s Common Framework pages build an aggregation methodology over the indicators in a workspace. The API keeps those documents and their saved results per tenant under /methodologies, so integrations can read them.

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 — roles, the browser-side pages, namespaces, keys, the Playground, and checking what your integration produced.