---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/"
path_to_agent_file: "https://agents.1health.io/public/demo/api/agents.md"
kind: "guide"
html: "https://agents.1health.io/public/demo/api/index.html"
source_version: "43d07c0335624b7661c2872315a5f184e8c3d832"
generated_at: "2026-08-27T03:35:58.960659+00:00"
---

# 1Health API — Agent Site Guide

This is the root site guide for the `demo` environment's `/api/` subtree. Fetch this one file first to orient yourself on this environment — the URL grammar, this environment's base URL, the auth quickstart, the shared error envelope, pagination conventions, version coverage, and pointers to the manifest, sitemap, and `llms.txt` are all covered below. If you were not told which environment to use, start from the [global site guide](https://agents.1health.io/api/agents.md) instead — never assume.

## URL Grammar & Param-Fold Rule

Path parameters are folded into filesystem-safe directory names using an underscore-substitution grammar: `_id_` ⇔ `{id}` — a path segment written as `{name}` in the OpenAPI route becomes `_name_` in the published site tree. Curly braces never appear in a published URL.

The param-fold rule is reflexive: a route whose own final segment is static documents itself, and collection and item operations on the same resource land in one file, not two.

## Section Reference

Every per-route `agents.md` this site publishes follows this fixed section order, in this order, every time:

Overview → Authorization → Path Parameters → Query Parameters → Request Body → Responses → Example → Child Routes → Navigation

## Base URL

This environment's real API host: https://demo.1health.io/api

Need a different environment? Start from the [global site guide](https://agents.1health.io/api/agents.md) — it explains all of them and when to ask the user, rather than assuming.

## Authentication

See the [auth quickstart](./authentication/agents.md) for how to register, acquire credentials, and authenticate requests against this API.

## Shared Error Envelope

This is the one and only place in the published site where the error envelope is documented. Per-route `Responses` sections do not repeat the shared error-response shape — they list only that endpoint's own specific trigger conditions and reference this section for the shared envelope shape.

**Open item:** the platform's exact error-response JSON schema is not yet confirmed against the real backend's error-handling code as of this file's drafting. Rather than fabricate field names, this section intentionally states the referencing contract only, pending confirmation of the real shape against the backend.

## Pagination

Pagination is zero-based via a `page` query parameter, with `size` defaulting to 50.

## Version Coverage & Deprecation Policy

This environment publishes `v1`, `v2`, and `v3` routes. Data Warehouse routes will be published here once Open Question #8 is resolved — pending, not yet live. Any operation flagged `deprecated: true` in source is excluded from generation entirely; it never appears anywhere in this published tree.

## GraphQL & WebSocket

`/api/graphql` and `/api/v1/notification` exist on this platform but are out of scope for auto-generated documentation. This is a pointer to their existence only — no further reference documentation for either is generated or linked from this site.

## Manifest, Sitemap & Discovery

- [Manifest](./manifest.md) — the complete route manifest.
- [Sitemap](../sitemap.xml) — the crawlable sitemap.
- [llms.txt](../llms.txt) — the LLM-discovery pointer file.

## Feedback & Support

**Placeholder:** no real feedback/support contact has been supplied for this section yet. Product owes a real contact (email or Slack channel) before this section ships with real content.