GraphQL

The GraphQL API allows you to query and manipulate your database data using a dynamically generated schema. Each table in your schema is automatically mapped to GraphQL types, queries, and mutations.

Endpoint and Authentication

HTTP

The HTTP endpoint is schema-specific (see Schemas for more information):

POST https://api.centia.io/api/graphql/schema/{schema_name}

Authentication is handled via a Bearer token in the Authorization header (see OAuth for more information).

POST https://api.centia.io/api/graphql/schema/public
Authorization: Bearer <your_token>
Content-Type: application/json

{
  "query": "query { ... }"
}

WebSocket

All GraphQL operations — queries, mutations, and subscriptions — are also available over WebSocket:

wss://event.centia.io?token=<your_token>

Send operations as JSON messages with type, schema, and query:

{
  "type": "subscribe",
  "id": "q1",
  "schema": "public",
  "query": "query { getArtists { artist_id legal_name } }"
}

This works identically for mutations:

{
  "type": "subscribe",
  "id": "m1",
  "schema": "public",
  "query": "mutation { insertArtists(objects: [{ legal_name: \"Jane Doe\" }]) { artist_id } }"
}

Introspection

You can use standard GraphQL introspection to explore the available types and fields. This is useful for tools like GraphiQL or Apollo Studio.

query {
  __schema {
    types {
      name
    }
  }
}

Queries

For every table in your database, the API provides a query field named get[TableName] (in camelCase).

Basic Query

To fetch records from a table named artists:

Request, basic query
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "query { getArtists { artist_id legal_name } }"
}

Filtering

The where argument supports complex filtering using logical and comparison operators. Simple equality filters are also supported.

Simple Equality:

{ getArtists(where: { artist_id: 1 }) { legal_name } }

Supported Operators:

eq: Equal
neq: Not equal
gt: Greater than
gte: Greater than or equal
lt: Less than
lte: Less than or equal
in: Included in array
like: Case-sensitive pattern match
ilike: Case-insensitive pattern match

Logical Operators:

and: Logical AND
or: Logical OR
not: Logical NOT

Request, filtered query
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "query { getArtists(where: { and: [ { legal_name: { ilike: \"%Linus%\" } }, { instrument: { eq: \"guitar\" } } ] }) { legal_name instrument } }"
}

Pagination

Use limit and offset for pagination.

Request, pagination
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "query { getArtists(limit: 10, offset: 20) { artist_id legal_name } }"
}

Relationships

If there are foreign key constraints between tables, the GraphQL API automatically exposes them as nested fields.

Request, relationships
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "query { getAlbums { title bands { name subgenre } } }"
}

Mutations

The API provides insert, update, and delete mutations for each table.

Insert

Use insert[TableName] to add new records. You can provide a single record via data or multiple records via objects.

Request, insert mutation
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "mutation { insertArtists(objects: [{ legal_name: \"John Doe\", instrument: \"Piano\" }]) { artist_id legal_name } }"
}

Update

Use update[TableName] to modify existing records. Use the where argument to specify which records to update and data for the new values.

Request, update mutation
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "mutation { updateArtists(where: { artist_id: { eq: 1 } }, data: { instrument: \"Electric Guitar\" }) { artist_id instrument } }"
}

Delete

Use delete[TableName] to remove records.

Request, delete mutation
POST https://api.centia.io/api/graphql/schema/public
Content-Type: application/json
Authorization: Bearer <your_token>

{
  "query": "mutation { deleteArtists(where: { artist_id: { eq: 1 } }) { artist_id } }"
}

Subscriptions

Subscriptions let you receive real-time database change events (INSERT, UPDATE, DELETE) over the WebSocket connection using GraphQL syntax.

Subscribing

After connecting to the WebSocket (see WebSocket above), send a message to register a subscription:

{
  "type": "subscribe",
  "id": "sub1",
  "schema": "public",
  "query": "subscription { ArtistsMessageAdded { artist_id legal_name instrument } }"
}

The server responds with an acknowledgement:

{
  "type": "subscribe_ack",
  "id": "sub1"
}

Subscription Field Names

Each table gets three subscription fields following the pattern {TableName}Message{Event}:

{TableName}MessageAdded — triggered on INSERT
{TableName}MessageUpdated — triggered on UPDATE
{TableName}MessageDeleted — triggered on DELETE

The table name is in PascalCase, matching the same convention as queries and mutations.

Filtering

Use the where argument to only receive events matching specific conditions. The same JSON object syntax used in queries and mutations is supported:

Subscribe with filter
{
  "type": "subscribe",
  "id": "sub2",
  "schema": "public",
  "query": "subscription { ArtistsMessageUpdated(where: {instrument: {eq: \"guitar\"}}) { artist_id legal_name instrument } }"
}

Supported operators:

eq, neq, gt, gte, lt, lte, in, like, ilike

Logical operators:

AND, OR, NOT

Subscribe with complex filter
{
  "type": "subscribe",
  "id": "sub3",
  "schema": "public",
  "query": "subscription { ArtistsMessageAdded(where: {OR: [{instrument: {eq: \"guitar\"}}, {instrument: {eq: \"piano\"}}]}) { artist_id legal_name } }"
}

A SQL-style string syntax is also supported:

Subscribe with string filter
{
  "type": "subscribe",
  "id": "sub4",
  "schema": "public",
  "query": "subscription { ArtistsMessageAdded(where: \"instrument = 'guitar'\") { artist_id legal_name } }"
}

note

Subscription filtering only works with scalar column types (integer, float, boolean, string, etc.). Complex types such as geometric types, range types, and JSON are not supported in subscription where clauses.

Column Selection

The fields you select in the subscription body determine which columns are included in the event payload. Only matching columns are returned.

JavaScript Example

const ws = new WebSocket(
  `wss://event.centia.io?token=${encodeURIComponent(token)}`
);

ws.onopen = () => {
  // Query over WebSocket
  ws.send(JSON.stringify({
    type: "subscribe",
    id: "q1",
    schema: "public",
    query: `query { getArtists { artist_id legal_name } }`
  }));

  // Subscribe to real-time events
  ws.send(JSON.stringify({
    type: "subscribe",
    id: "sub1",
    schema: "public",
    query: `subscription {
      ArtistsMessageAdded(where: {instrument: {eq: "guitar"}}) {
        artist_id
        legal_name
        instrument
      }
    }`
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Received:", data);
};

Data Types

The GraphQL API supports various PostgreSQL data types, mapping them to appropriate GraphQL types:

Scalars: integer, float, boolean, string, JSON , ID, Date, Time, DateTime.
Geometric Types: Point, Line, Lseg, Box, Circle, Path, Polygon.
Range Types: Int4range, Int8range, Numrange, Tsrange, Tstzrange, Daterange.
Arrays: Any type can be returned as a list (e.g., [String], [Int]).

Any complex types can be used as input arguments for mutations. Type hints are not required because the schemas are dynamically generated from the database relations.

Se also Types.

Consider a generated schema like this:

Schema
type Tours {
  id: ID!
  artist_name: String!
  tour_name: String!
  from_to: Daterange!
}

"""
Date is accepted in almost any reasonable format, including ISO 8601, SQL-compatible, traditional POSTGRES, and others.
"""
scalar Date

"""Range type for daterange, with lower and upper bounds of type Date."""
type Daterange {
  lower: Date
  upper: Date
  lowerInclusive: Boolean
  upperInclusive: Boolean
}

type Mutation {
  insertTours(data: JSON, objects: [JSON]): [Tours]
  updateTours(id: ID, where: JSON, data: JSON): [Tours]
  deleteTours(id: ID, where: JSON): [Tours]
}

Then you can insert a new tour using the following mutation. The Daterange field is represented as JSON:

Operation
mutation InsertTours($data: JSON) {
  insertTours(data: $data) {
    id
    from_to {
      lower
      upper
    }
  }
}

variables
{
  "data": {
    "artist_name": "Guns n’ Roses",
    "tour_name": "Europe: Summer 2026",
    "from_to": {
      "lower": "2010-04-06",
      "upper": "2011-03-07",
      "lowerInclusive": true,
      "upperInclusive": true
    }
  }
}

Endpoint and Authentication​

HTTP​

WebSocket​

Introspection​

Queries​

Basic Query​

Filtering​

Pagination​

Relationships​

Mutations​

Insert​

Update​

Delete​

Subscriptions​

Subscribing​

Subscription Field Names​

Filtering​

Column Selection​

JavaScript Example​

Data Types​

Endpoint and Authentication

HTTP

WebSocket

Introspection

Queries

Basic Query

Filtering

Pagination

Relationships

Mutations

Insert

Update

Delete

Subscriptions

Subscribing

Subscription Field Names

Filtering

Column Selection

JavaScript Example

Data Types