> For the complete documentation index, see [llms.txt](https://synthesys-2.gitbook.io/synthesys-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/health-wip.md). # Health \[WIP] The health endpoint is a lightweight liveness check intended for monitoring, deployment verification, and any tool that needs to confirm the API process is reachable and responding. It performs no work against the backing store and does not authenticate or authorise. A successful response means the HTTP layer is up; it does **not** guarantee that every downstream dependency is healthy. ### When to use it There are three good reasons to call the health endpoint: 1. **Continuous monitoring.** Point your uptime checker at it on a 30–60 second interval. The endpoint is intentionally cheap so this won't add meaningful load to the API. 2. **Post-deploy smoke test.** A successful health check after a deploy confirms the new binary booted and is serving HTTP. Pair it with a follow-up call to a read endpoint (`GET /funds/shareclass/all`) to confirm the backing store is reachable too. 3. **CI integration tests.** Use it as the first call in any integration test suite to fail fast if the test environment isn't up before you waste cycles on the rest of the suite. And one bad reason: **don't use it as a load-balancer health check** when load-balancing across instances that depend on the backing store. A green health response from this endpoint does not promise that the next data-bearing call will succeed. For load-balancer checks, prefer hitting a read endpoint that exercises the data path. ### Health check **`GET /health`** #### Response Returns process state in `data`: json ```json { "isError": false, "errorMsg": null, "data": { "status": "ok", "timestamp": "2024-03-24T12:00:00.000Z", "env": "production" } } ``` | Field | Type | Notes | | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `status` | string | `"ok"` when the process is serving. No other values are emitted today | | `timestamp` | string | ISO-8601 timestamp at which the response was generated. Useful for detecting clock skew between your monitoring host and the API host | | `env` | string | The environment identifier (e.g. `production`, `staging`, `development`). Use this to assert that your application is talking to the host you think it is | #### Examples **curl:** bash ```bash curl -s $BASE/health | jq . ``` **Node.js:** javascript ```javascript async function isHealthy() { try { const res = await fetch(`${BASE}/health`, { signal: AbortSignal.timeout(5_000) }); if (!res.ok) return false; const payload = await res.json(); return payload.isError === false && payload.data?.status === 'ok'; } catch { return false; } } if (!(await isHealthy())) { console.error('Synthesys API is unreachable or unhealthy'); process.exit(1); } ``` **Python:** python ```python import requests def is_healthy(): try: r = requests.get(f"{BASE}/health", timeout=5) if not r.ok: return False payload = r.json() return payload.get("isError") is False and payload.get("data", {}).get("status") == "ok" except requests.RequestException: return False if not is_healthy(): raise SystemExit("Synthesys API is unreachable or unhealthy") ``` ### Patterns * **Set a short timeout.** Five seconds is generous; if the health endpoint is slow, something is wrong even if it eventually returns 200. Don't let a sluggish health check mask a real problem behind a long timeout. * **Check `env` in deploy verification scripts.** A trivial bug — wrong base URL in your deploy step — can be caught by asserting `env === "production"` immediately after deploy. * **Don't alert on a single failed check.** Network blips happen. A reasonable alerting policy is "alert if N failed checks in M seconds" rather than "alert on any single failure." ### Common errors The health endpoint should not produce errors under normal conditions. If you see anything other than a `2xx` with `isError: false`, the API process is in trouble and the response shape may not match the documented envelope. * **Connection refused / timeout** — the process is down or the network path is broken. This is the failure case the endpoint is designed to detect. * **`502 Bad Gateway` / `503 Service Unavailable`** — a load balancer or reverse proxy is up but the API process behind it is not. Same investigative path as the previous case. * **`5xx` with a non-envelope body** — an unhandled crash early in request processing. Capture the raw response body in your alert payload for the on-call engineer. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://synthesys-2.gitbook.io/synthesys-docs/network-overview/api-reference/health-wip.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.