Introduction

The API is organized around resources such as people, groups, courses, and events. A resource has a stable type and id, attributes that describe it, and relationships to other resources.

Requests

Send production requests to https://api.celula.in over HTTPS.

Header	Value	When to send it
X-CIN-API-Token	<client_token>	Every request from an approved external integration.
Authorization	Bearer <access_token>	Authenticated /v1 requests.
Accept	application/vnd.api+json	All JSON:API resource requests.
Content-Type	application/vnd.api+json	Requests with a JSON:API body.
X-Request-Id	A unique request identifier	Optional; useful for tracing and support.

The client token identifies an approved, allowlisted external integration. It does not identify a person or grant access to church data; protected operations also require the appropriate Authorization credential.

The API currently also accepts application/json on routes that enforce content negotiation. Use application/vnd.api+json unless an operation explicitly documents a different media type.

Resource documents

A single-resource response places the resource object in data. Collection responses place an array in data and can include pagination information in meta. Related resources can appear in the top-level included array.

Write operations

Create and update requests wrap attributes and relationships in a top-level data member. The id is normally omitted when creating a resource and required when updating one.

The operation page is authoritative for required fields, accepted relationships, and validation rules.

Query parameters

Collection operations commonly use JSON:API-style query parameters:

• page[number] and page[size] select a page.
• filter[field] filters by a resource-specific field.
• sort supplies a comma-separated list of resource-specific sort fields.
• fields[type] requests a sparse fieldset where supported.

Support, defaults, and limits vary by resource. Only use a query parameter when it appears on that operation’s page.

Data conventions

• Resource identifiers are strings. Most persisted resources use 24-character hexadecimal identifiers, but clients must not derive meaning from their format.
• Timestamps are returned as ISO 8601 strings unless an operation documents a different representation.
• Attribute and relationship names are case-sensitive.
• Clients should ignore response members they do not recognize so additive API changes do not break an integration.

Resource request

curl https://api.celula.in/v1/people/me \
  --header "X-CIN-API-Token: $CELULAIN_CLIENT_TOKEN" \
  --header "Authorization: Bearer $CELULAIN_ACCESS_TOKEN" \
  --header "Accept: application/vnd.api+json"

Resource response

{
  "data": {
    "type": "people",
    "id": "66c5f13e7e70d42c6a9a8b01",
    "attributes": {
      "name": "Ana Souza"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "66c5f0ec7e70d42c6a9a8afa"
        }
      }
    }
  }
}

Write document

{
  "data": {
    "type": "people",
    "id": "66c5f13e7e70d42c6a9a8b01",
    "attributes": {
      "name": "Ana Maria Souza"
    }
  }
}