Skip to main content

GraphQL

Ovok exposes FHIR R4 resources through a GraphQL endpoint. A query selects the fields a screen needs; returned objects retain their FHIR resource shape. GraphQL changes how a client reads and writes data, not the underlying resource model or project authorization.

Use queries and pagination to read resources, and mutations for schema-backed writes. The resource catalogs document the live sandbox root fields and search arguments. For resource structure, search parameter meaning, and REST interactions, use FHIR resources, FHIR basics, and Ovok primitives.

Endpoint​

Send a POST request to the environment FHIR R4 GraphQL endpoint:

https://api.sandbox.ovok.com/fhir/R4/$graphql

Authenticate with an Ovok access token and send a JSON body containing query; pass values separately under variables:

curl --fail-with-body --silent --show-error \
  --request POST \
  --url 'https://api.sandbox.ovok.com/fhir/R4/$graphql' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"query":"query SchemaCheck { __schema { queryType { name } mutationType { name } } }"}'

A confidential ClientApplication can obtain a client_credentials token for server-side exploration. Keep its secret in a secure local environment or secret manager; never put it in a browser or mobile bundle, docs, source control, or logs. Patient-facing applications should use Ovok authentication and SDKs. See Authentication, React SDK, and Mobile SDK.

Get a sandbox token​

Set OVOK_CLIENT_ID and OVOK_CLIENT_SECRET in your local environment from a secure source. This command keeps the returned token in OVOK_TOKEN instead of printing it:

OVOK_TOKEN="$(
  curl --fail-with-body --silent --show-error \
    --request POST \
    --url 'https://api.sandbox.ovok.com/oauth2/token' \
    --user "${OVOK_CLIENT_ID}:${OVOK_CLIENT_SECRET}" \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=client_credentials' \
  | jq -er '.access_token'
)"

The client-credentials token represents the client application, not a patient or practitioner. Give that client only the project permissions required for the integration.

Explore the schema​

Introspection returns schema metadata, not patient records. In the sandbox, the root query and mutation types are QueryType and MutationType. The schema snapshot checked on 8 October 2026 exposes 146 FHIR R4 resource types and 16 Ovok platform types. Each type has read, list, and connection queries plus create, update, patch, and delete mutations: 486 query fields and 648 mutation fields in total.

The graphql-introspection project feature was enabled for this documentation pass. The same introspection request also succeeded before the feature was added, so the flag is not an introspection access switch. Whether an environment allows introspection is controlled by its platform configuration. Read the feature behavior before relying on it in another environment.

Start with a schema-only check:

query SchemaRoots {
  __schema {
    queryType { name }
    mutationType { name }
  }
}

To inspect a resource type and its fields:

query InspectPatientType {
  __type(name: "Patient") {
    name
    fields {
      name
      type { kind name ofType { kind name } }
    }
  }
}

Introspection describes what the endpoint schema accepts. It does not prove that the current token can read or write a resource. AccessPolicy, project scope, and operation-specific checks still apply.

Browse the reference​

The catalog is a snapshot of the sandbox schema checked on 8 October 2026. Environments can expose different fields. Re-introspect the endpoint you will use and compare results with the published FHIR R4 resource reference.