GraphQL basics

One endpoint

All GraphQL operations go to a single endpoint:

POST https://api.test.geena.eu/graphql

The server accepts POST, GET, and multipart form transports. For nearly everything you want POST with Content-Type: application/json.

Scope wrapping

The root schema exposes each API scope as a nullable field:

type Query {
    admin:   AdminQuery
    business(orgId: ID!): BusinessQuery
    user:    UserQuery
    guest:   GuestQuery
}

type Mutation {
    admin:   AdminMutation
    business(orgId: ID!): BusinessMutation
    organizationCreate(input: OrganizationCreateInput!): OrganizationCreateResponse!
    user:    UserMutation
}

Every operation in the User API section is nested under user { ... }:

query {
  user {
    status { isRegistered isSealed }
  }
}

Request shape

curl -X POST https://api.test.geena.eu/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($id: ID!) { user { document { get(id: $id) { metadata { id name } } } } }",
    "variables": { "id": "..." }
  }'

Response shape

Success:

{
  "data": {
    "user": {
      "status": { "isRegistered": true, "isSealed": false }
    }
  }
}

Scope-level error — the scope field returns null and GraphQL errors are populated:

{
  "data": { "user": null },
  "errors": [
    { "message": "vault is sealed", "path": ["user","document","get"] }
  ]
}

Warning

Scope roots are nullable by design. If your client treats data.user as non-null it will crash on any scope-level error. Always check for null before dereferencing scope fields.

Transport-level errors

These do not return a GraphQL body — they’re plain HTTP errors from the middleware:

Code	Message	Cause
401	`Missing token`	no `Authorization` header
401	`Invalid token`	token expired, bad signature, or session gone

Anything else (validation errors, business-logic errors, permission errors) comes back as a 200 with the errors array populated.

File uploads

The file.upload mutation takes a GraphQL Upload! scalar. Use the GraphQL multipart request spec format. See the files/upload page for a minimal curl example.