# Health and discovery

Canonical page: https://docs.ovok.com/primitives/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 [#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`.

```bash
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 [#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 [#openid-connect-discovery]

`GET /.well-known/openid-configuration`

Returns the OpenID Provider metadata described by [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). OAuth and OpenID Connect client libraries read it to find sign-in endpoints and supported features.

```bash
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](#json-web-key-set). |
| `introspection_endpoint` | `https://<identity-host>/oauth2/introspect` | Reports whether a token is active ([RFC 7662](https://www.rfc-editor.org/rfc/rfc7662)). |
| `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 [#json-web-key-set]

`GET /.well-known/jwks.json`

Returns the public signing keys ([RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)). Use them to verify access and ID tokens locally.

```bash
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 [#smart-configuration]

`GET /.well-known/smart-configuration`<br />
`GET /fhir/R4/.well-known/smart-configuration`

Returns the [SMART App Launch configuration](https://hl7.org/fhir/smart-app-launch/conformance.html). 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.

```bash
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](#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 [#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.

```bash
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 [Primitives reference](/primitives) while this endpoint is unavailable.

---

## FHIR CapabilityStatement [#fhir-capabilitystatement]

`GET /fhir/R4/metadata`

Returns the server's [FHIR CapabilityStatement](https://hl7.org/fhir/R4/capabilitystatement.html). 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.

```bash
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:

```bash
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](#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 [#operations-ovok-implements]

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

### Useful queries [#useful-queries]

```bash
# 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](/api/fhir/r4) reference for the standard resource definitions. The live CapabilityStatement is the source of truth for capabilities advertised by the selected environment.
