For App Developers

Needs & Commitments

The Global.Church API supports a three-step engagement lifecycle that connects gaps to action:

Need — an organization declares that work is needed within a particular scope (an engagement accelerator, a people group, a country).
Commitment — an organization commits to act in a specific scope. A commitment may respond to a prior need, or stand alone.
Engagement attestation — an organization attests that engagement has occurred. The attestation may optionally fulfill a commitment.

Every step writes to a Supabase table backing the API and propagates to the knowledge graph in near-real-time. SPARQL queries can traverse gc:concernsNeed (Commitment → Need) and at:fulfillsCommitment (Attestation → Commitment) to walk the full chain.

Authentication

All write endpoints in this lifecycle (POST /v0/needs, POST /v0/commitments, POST /v0/engagement-claims/submit, the /status endpoints) act on behalf of a signed-in person, who must be a steward of the organization referenced by orgUri in the Home; the API checks this on every write, and refuses with 503 when the Home cannot be reached. Each call carries two credentials:

Authorization: Bearer <key> — your API key.
x-home-id-token: <token> — the person's sign-in token, the id_token your app received when they signed in through the Home.

The gateway verifies the token's signature, issuer, audience and expiry, and refuses the request with 401 when it is missing or not valid. The acting person is the token's subject: the API sets userId from it, and any userId sent in the request is ignored. The token identifies a signed-in person, so it belongs in server-side calls, never in browser code.

Read endpoints (GET /v0/needs, GET /v0/commitments, GET /v0/engagement-claims) require the API key but no sign-in token.

Step 1 — Declare a need

Code
 
curl -X POST https://api.global.church/v0/needs \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "x-home-id-token: $HOME_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/example-mission",
    "orgName": "Example Mission",
    "needDescription": "Audio scripture in Kazakh dialect XYZ for oral-preference communities along the eastern border.",
    "accelerators": ["SRA-AUD"],
    "concernsPeopleGroupRop3": ["115648"],
    "concernsCountryCode": ["KZ"]
  }'

Code
 
{ "needId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234", "status": "open" }

Required fields: orgUri, orgName, needDescription, and a non-empty accelerators array of Phases of Engagement Toolkit domain codes (PRA … MKT, the twelve top concepts of poe:EngagementAcceleratorScheme — see Engagement Accelerators).

Optional concernsPeopleGroupRop3 (ROP3 codes) and concernsCountryCode (ISO alpha-2) narrow the scope. A need may carry multiple accelerators, multiple people groups, and multiple countries.

Need statuses

Status	Meaning
`open`	Default at creation. The need has not been met.
`partially_met`	One or more commitments have addressed part of the need.
`met`	The need has been fully addressed.
`withdrawn`	The declaring organization has rescinded the need.

Transition with POST /v0/needs/status:

Code
 
curl -X POST https://api.global.church/v0/needs/status \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "x-home-id-token: $HOME_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "needId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234",
    "status": "partially_met"
  }'

Any status is reachable from any other so users can correct mistakes; there is no enforced state machine.

Step 2 — Make a commitment

A commitment may respond to a known need or stand alone. To respond to a need, include concernsNeedId:

Code
 
curl -X POST https://api.global.church/v0/commitments \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "x-home-id-token: $HOME_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/audio-scripture-org",
    "orgName": "Audio Scripture Org",
    "commitmentDescription": "Produce and distribute the Kazakh-XYZ Audio New Testament by Q4 2027.",
    "acceleratorScope": ["SRA-AUD"],
    "concernsNeedId": "8c464360-9a6f-4c28-9d12-0b3f8e7a1234",
    "concernsPeopleGroupRop3": ["115648"],
    "concernsCountryCode": ["KZ"],
    "targetCompletionDate": "2027-12-31"
  }'

Code
 
{ "commitmentId": "6a91f5c4-3e22-4db8-bc34-7e9af0124567", "status": "declared" }

Required: orgUri, orgName, commitmentDescription, acceleratorScope. Optional: concernsNeedId, concernsPeopleGroupRop3, concernsCountryCode, targetCompletionDate (ISO YYYY-MM-DD).

If concernsNeedId is supplied, the API verifies the need exists. The need's owning organization need not match the committing organization — any organization may commit against any open need.

Commitment statuses

Status	Meaning
`declared`	Default at creation. Commitment is recorded but no funding or work has begun.
`funded`	Resources have been allocated.
`in_progress`	Work has begun.
`fulfilled`	The commitment has been completed.
`partially_fulfilled`	Some scope was completed; some remains.
`abandoned`	The committing organization has discontinued.
`expired`	The target completion date passed without fulfillment.

Transition with POST /v0/commitments/status (mirrors the need status endpoint).

Step 3 — Attest engagement (optionally fulfilling a commitment)

When engagement happens on the ground, the acting organization files an engagement attestation. To link the attestation to a prior commitment, include fulfillsCommitmentId:

Code
 
curl -X POST https://api.global.church/v0/engagement-claims/submit \
  -H "Authorization: Bearer $GC_API_KEY" \
  -H "x-home-id-token: $HOME_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgUri": "https://data.global.church/org/audio-scripture-org",
    "orgName": "Audio Scripture Org",
    "peopleGroupRop3": "115648",
    "peopleGroupRog3": "KAZ",
    "peopleGroupName": "Kazakh, Northern",
    "countryCode": "KZ",
    "countryName": "Kazakhstan",
    "engagementAccelerators": ["SRA-AUD"],
    "description": "Initial 50-chapter recording deployed via SD-card distribution.",
    "fulfillsCommitmentId": "6a91f5c4-3e22-4db8-bc34-7e9af0124567"
  }'

Code
 
{ "claimId": "f1d4ab1a-7c80-4f6c-a4f5-2b9d4c0a5678", "status": "active" }

Any organization may attest fulfillment of any commitment. The attestation records who attested (claimedByUserId and orgUri); the commitment retains its own committing organization.

Walking the chain in SPARQL

After the three calls above, this query returns the full Need → Commitment → Attestation triangle:

Code
 
PREFIX gc:   <https://ontology.global.church/core#>
PREFIX at:   <https://agentictrustlabs.dev/ns/agentic-trust#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

SELECT ?need ?needDesc ?cmt ?cmtDesc ?att ?attDesc
WHERE {
  GRAPH <https://data.global.church/needs/> {
    ?need a at:Need ;
          gc:needDescription ?needDesc .
  }
  GRAPH <https://data.global.church/commitments/> {
    ?cmt a at:Commitment ;
         gc:concernsNeed ?need ;
         gc:commitmentDescription ?cmtDesc .
  }
  GRAPH <https://data.global.church/engagement-claims/> {
    ?att a gc:EngagementAttestation ;
         at:fulfillsCommitment ?cmt ;
         gc:claimDescription ?attDesc .
  }
}

Listing and filtering

GET /v0/needs, GET /v0/commitments, and GET /v0/engagement-claims all support filtering by orgUri and status. GET /v0/commitments additionally accepts concernsNeedId to find every commitment responding to a particular need. See the API Reference for the full parameter list per endpoint.