GraphQL

GraphQL is AudienceKit’s main API. The schema is built with graphql-ruby in api/app/graphql and supports Relay-style global object IDs.

Endpoints

Endpoint	Credentials	Use it for
POST /v1/audience/:audience_id/graphql	A JWT signed in on that audience or on the platform, or an API key for that audience	Everything about one audience
POST /v1/tenants/graphql	A platform admin JWT	Tenant management: listing and creating audiences, subdomains and domains

The two endpoints serve different schemas. Tenant management is its own schema, so its mutations don’t exist on an audience endpoint, and an audience’s records (venues, people, locales, theme) don’t exist on the tenants endpoint.

Send a JSON body with query, and optionally variables and operationName:

curl https://api.audiencekit.io/v1/audience/$AUDIENCE_ID/graphql \
  -H "Authorization: JWT $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Venues { audience { name } venues { id hidden locale { name } page { name } } }",
    "operationName": "Venues"
  }'

An unknown audience ID returns 404 Not Found. An API key, or a JWT signed in on another audience, returns 403 Forbidden on an audience’s endpoint. The tenants endpoint returns 401 Unauthorized to anything but a platform admin JWT.

Queries

On an audience endpoint, audience returns that audience, and locales, venues and people return only its records. On /v1/tenants/graphql, audiences lists every audience and audience(id:) fetches one. me returns the signed-in user, or null for API keys.

query Audience {
  audience {
    id
    name
    subdomain
    domains { dnsName }
    theme { preset tagline light { name value } dark { name value } }
  }
}

Object IDs

IDs are Relay global IDs, so node(id:) and nodes(ids:) can fetch any object. On an audience endpoint they return null for objects that belong to a different audience.

Mutations

Every mutation requires an admin JWT. Others get an error with the message “Administrator access required”. Mutations follow the Relay convention: one input argument, with an optional clientMutationId that is echoed back.

Mutations that take an audienceId default to the endpoint’s audience. On an audience endpoint, passing a different audienceId is an error; on /v1/tenants/graphql you must pass one. Subdomains change only on the tenants endpoint.

mutation Rebrand($input: AudienceThemeUpdateInput!) {
  updateAudienceTheme(input: $input) {
    audience { theme { preset tagline } }
  }
}

{
  "input": {
    "theme": {
      "preset": "hot_mess",
      "tagline": "Queer nights out, all in one place.",
      "light": [{ "name": "accent", "value": "#b8236f" }]
    }
  }
}

When a record fails validation, the error’s extensions carry the field errors. See Errors.

The full list of types, queries and mutations is in the GraphQL reference.

Limits

A query may contain at most 5,000 tokens, and validation stops after 100 errors.

Keep the schema dump current

The API checks in api/schema.graphql and api/schema.json (audience endpoints) and api/tenants_schema.graphql and api/tenants_schema.json (tenant management). The admin console’s Relay compiler and the GraphQL reference are built from the dumps, so regenerate them whenever you change a type, and copy the .graphql files to admin/data/:

cd api
bin/rails graphql:schema:dump graphql:tenants:schema:dump
cp schema.graphql tenants_schema.graphql ../admin/data/