Health and discovery

These endpoints need no authentication. Use them to check whether the API is available, discover sign-in endpoints, and find the FHIR capabilities exposed by a server.

Operation	Method	Path
Health check	GET	/healthcheck
Health check alias	GET	/
Health check alias	GET	/_health
Readiness check	GET	/healthcheck/ready
OpenID Connect discovery	GET	/.well-known/openid-configuration
JSON Web Key Set	GET	/.well-known/jwks.json
SMART configuration	GET	/.well-known/smart-configuration
SMART configuration	GET	/fhir/R4/.well-known/smart-configuration
OpenAPI document	GET	/openapi.json
FHIR CapabilityStatement	GET	/fhir/R4/metadata

---

Health check

GET /healthcheck

Reports whether the API and its dependencies are healthy, and identifies the running build. The same health response is served at / and /_health.

curl -sS "https://api.sandbox.ovok.com/healthcheck"

Field	Type	Example	Description
ok	boolean	true	True only when every dependency below is healthy.
dependencies.redis.ok	boolean	true	Whether Redis answered within two seconds.
dependencies.fhirStore.ok	boolean	true	Whether the FHIR store answered within two seconds and reported healthy.
version	string or null	null	Release version, or null when the build did not set one.
buildEnv	string or null	production	Runtime environment reported by the build; this can differ from the hostname used to reach the API.
commitHash	string or null	b336f80	First seven characters of the deployed commit. Use it to confirm a deployment is live.
buildDate	string or null	null	Build timestamp, or null when the build did not set one.
runningSince	string	ISO 8601 timestamp	When this server process started. It changes after a restart or deployment.

Health versus readiness

The status code from /healthcheck is 200 even when a dependency is down, so inspect ok in the response body. A load balancer or monitor that needs a failing HTTP status should call GET /healthcheck/ready; it returns 503 when a dependency is unavailable.

Any origin may call the health check. Its response includes Access-Control-Allow-Origin: *.

---

OpenID Connect discovery

GET /.well-known/openid-configuration

Returns the OpenID Provider metadata described by OpenID Connect Discovery 1.0. OAuth and OpenID Connect client libraries read it to find sign-in endpoints and supported features.

curl -sS "https://api.sandbox.ovok.com/.well-known/openid-configuration"

Field	Example	Description
issuer	https://<identity-host>/	Token issuer identifier. The iss claim in a token must match it exactly.
authorization_endpoint	https://<identity-host>/oauth2/authorize	Where to send the user to sign in with the authorization code flow.
token_endpoint	https://<identity-host>/oauth2/token	Where to exchange a code, refresh token, or client credentials for tokens.
userinfo_endpoint	https://<identity-host>/oauth2/userinfo	Returns claims for the signed-in user when called with an access token.
jwks_uri	https://<identity-host>/.well-known/jwks.json	Public keys used to verify token signatures. See JSON Web Key Set.
introspection_endpoint	https://<identity-host>/oauth2/introspect	Reports whether a token is active (RFC 7662).
registration_endpoint	https://<identity-host>/oauth2/register	Dynamic client registration endpoint.
grant_types_supported	authorization_code, refresh_token	OAuth grant types accepted by the token endpoint.
response_types_supported	code	response_type values accepted by the authorization endpoint.
scopes_supported	openid, profile, email	OpenID Connect scopes advertised by this provider.
token_endpoint_auth_methods_supported	client_secret_basic, private_key_jwt	Client authentication methods accepted by the token endpoint.
id_token_signing_alg_values_supported	ES256, RS256	Algorithms that may be used to sign ID tokens.
code_challenge_methods_supported	S256	PKCE methods accepted. Use S256.
subject_types_supported	pairwise, public	Subject identifier types the issuer can produce.
request_object_signing_alg_values_supported	none	Algorithms accepted for request objects.

The response is sent with Cache-Control: no-store. Use the metadata returned here rather than constructing issuer or endpoint URLs from the API base URL; the identity service may use a different hostname.

---

JSON Web Key Set

GET /.well-known/jwks.json

Returns the public signing keys (RFC 7517). Use them to verify access and ID tokens locally.

curl -sS "https://api.sandbox.ovok.com/.well-known/jwks.json"

Field	Example	Description
keys[].kid	<key-id>	Key ID. A token header's kid identifies the key that signed it.
keys[].kty	RSA	Key type.
keys[].alg	RS256	Signing algorithm.
keys[].use	sig	Key purpose; sig means signature verification.
keys[].n, keys[].e	<base64url-encoded-modulus>, AQAB	RSA modulus and exponent, base64url-encoded.

Select the key whose kid matches the token header. Keys can rotate; if a token names an unknown kid, fetch the JWKS again before rejecting it.

---

SMART configuration

GET /.well-known/smart-configuration
GET /fhir/R4/.well-known/smart-configuration

Returns the SMART App Launch configuration. Both paths return the same document. SMART clients discover configuration relative to the FHIR base URL (https://api.sandbox.ovok.com/fhir/R4), so clients should use the FHIR-relative path.

curl -sS "https://api.sandbox.ovok.com/fhir/R4/.well-known/smart-configuration"

Field	Example	Description
issuer, jwks_uri	https://<identity-host>/, https://<identity-host>/.well-known/jwks.json	Issuer and public signing-key location, as in OpenID Connect discovery.
authorization_endpoint, token_endpoint, introspection_endpoint	/oauth2/authorize, /oauth2/token, /oauth2/introspect on the returned identity host	Authorization, token, and token-introspection endpoints.
grant_types_supported	client_credentials, authorization_code, refresh_token	Accepted grants. client_credentials is used by backend services.
token_endpoint_auth_methods_supported	client_secret_basic, private_key_jwt	Client authentication methods; private_key_jwt is intended for asymmetric backend clients.
token_endpoint_auth_signing_alg_values_supported	RS256, RS384, ES384	Algorithms accepted for private_key_jwt client assertions.
scopes_supported	patient/*.rs, user/*.cruds, openid, fhirUser	SMART and OpenID scopes. patient/*.rs reads and searches the launch patient's data; user/*.cruds reflects interactions allowed by the user's permissions.
response_types_supported	code	Supported response types; this configuration lists the authorization code flow.
capabilities	launch-ehr, launch-standalone, permission-v1, permission-v2	SMART features such as EHR and standalone launch, public and confidential clients, and v1 and v2 scope syntax.
code_challenge_methods_supported	S256	PKCE methods.

The response is sent with Cache-Control: no-store.

---

OpenAPI document

GET /openapi.json

This path currently returns 404 Not Found in the checked environments. If the route is enabled later, the response body will be an OpenAPI document.

curl -i "https://api.sandbox.ovok.com/openapi.json"

The checked environments return 404 Not Found; no response body is documented here because its shape was not included in the captured response. Use the published API reference while this endpoint is unavailable.

---

FHIR CapabilityStatement

GET /fhir/R4/metadata

Returns the server's FHIR CapabilityStatement. It describes supported resource types, interactions, search parameters, operations, security, and the FHIR base URL. Ovok also includes an extension listing public non-FHIR endpoints.

curl -sS "https://api.sandbox.ovok.com/fhir/R4/metadata" -H 'Accept: application/fhir+json'

The full response is about 370 KB and lists 146 resource types. This query prints a useful overview; remove the jq filter to save the complete response:

curl -sS "https://api.sandbox.ovok.com/fhir/R4/metadata" | jq '{
  resourceType,
  status,
  kind,
  fhirVersion,
  format,
  software,
  implementation,
  rest: [.rest[] | {
    mode,
    security: {
      cors: .security.cors,
      services: [.security.service[].coding[].code],
      oauthUris: [.security.extension[].extension[] | {rel: .url, url: .valueUri}]
    },
    resourceCount: (.resource | length),
    patient: [.resource[] | select(.type == "Patient") | {
      type,
      profile,
      interactions: [.interaction[].code],
      versioning,
      searchParameterCount: (.searchParam | length)
    }][0]
  }]
}'

The response is a FHIR CapabilityStatement. The jq command above selects a compact overview; the full response includes these key sections:

Field	Example	Description
resourceType	CapabilityStatement	Identifies the FHIR resource.
id, name, title	ovok-server, OvokCapabilityStatement	Identify the statement as Ovok's CapabilityStatement.
url	https://api.sandbox.ovok.com/fhir/R4/metadata	Address from which this statement is served.
version, software.version	<deployed-commit>	First seven characters of the deployed commit, also shown as commitHash in the health check.
date	ISO 8601 timestamp	When the FHIR resource definitions behind the statement were last built.
kind	instance	Indicates that this statement describes the running server.
implementation.url	https://api.sandbox.ovok.com/fhir/R4/	FHIR base URL; FHIR request paths are relative to it.
fhirVersion	4.0.1	FHIR version, here R4.
format, patchFormat	json, application/json-patch+json	Supported resource formats and PATCH content type.
rest[].security.service	OAuth, SMART-on-FHIR	Advertised security schemes.
rest[].security.extension	authorize, token endpoint URIs	OAuth authorization and token endpoints for SMART clients. Use the returned URIs.
rest[].interaction	transaction, batch	Server-wide interactions, such as FHIR transaction and batch Bundles.
rest[].searchParam	_count (number)	Search parameters valid across resource types.
rest[].resource[].type	Observation	A supported FHIR resource type.
rest[].resource[].interaction	read, create, update, search-type	REST interactions advertised for that type.
rest[].resource[].versioning, conditional*	versioned, conditionalCreate: true	Version handling and conditional create, update, and delete support.
rest[].resource[].searchParam	_id (token), _lastUpdated (date)	Search parameters and their types for a specific resource type.
rest[].resource[].operation	lastn	Extended operations supported on a resource type.
extension (ovok-public-api)	Endpoint method, path, and group	Ovok's public non-FHIR endpoints. FHIR clients can ignore this extension.

Operations Ovok implements

Resource	Operation	Level
Observation	$lastn	type
Questionnaire	$populate	instance
QuestionnaireResponse	$extract	instance
Patient	$enable-signals	instance

Useful queries

# Every resource type the server supports
curl -sS "https://api.sandbox.ovok.com/fhir/R4/metadata" | jq -r '.rest[0].resource[].type'

# Every Ovok public endpoint, as "METHOD /path"
curl -sS "https://api.sandbox.ovok.com/fhir/R4/metadata" | jq -r '
  .extension[] | select(.url | endswith("ovok-public-api")) | .extension[]
  | (.extension | map({(.url): (.valueCode // .valueString)}) | add) | "\(.method) \(.path)"'

The CapabilityStatement is rebuilt at most every five minutes, so a change after deployment may take up to five minutes to appear. If the FHIR store is unavailable, this request returns 503; a partial statement is not returned. Retry after the store recovers.

See the FHIR resources reference for the standard resource definitions. The live CapabilityStatement is the source of truth for capabilities advertised by the selected environment.