API reference

Every route, one contract

The v1 contract: each route with its parameters, scope and errors. Every response below is what the sandbox returns, on synthetic data, for the request beside it.

Base URL: https://api.dermliving.com/v1
Environment: Set by the key; no key is the sandbox
Format: JSON
Contract: /openapi.yaml

Sandbox requests need no key, so the samples below send no Authorization header. A key, when you have one, goes in Authorization: Bearer. See Authentication for scopes and Versioning for the version header.

Conditions

Structured records for each condition: names, codes, morphology and sites.

GET`/conditions`

List conditions

Search conditions by name, synonym or code. Results are cursor-paginated.

Scopeconditions:readTry it in the playground

Parameter	Description
`query`query · string	Name, synonym or code to match.
`limit`query · integer	Results per page.Default 20 · 1 to 100
`cursor`query · string	The next_cursor from a previous page.

Errors400 VALIDATION_ERROR401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl "https://api.dermliving.com/v1/conditions?query=eczema" \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": [
    {
      "id": "cond_atopic_dermatitis",
      "name": "Atopic dermatitis",
      "synonyms": ["Atopic eczema", "AD"],
      "codes": [
        {
          "system": "ICD-10-CM",
          "code": "L20.9",
          "display": "Atopic dermatitis, unspecified"
        },
        {
          "system": "ICD-11",
          "code": "EA80.Z",
          "display": "Atopic eczema, unspecified"
        }
      ],
      "morphology": [
        "xerosis",
        "erythematous papules",
        "excoriation",
        "lichenification"
      ],
      "sites": {
        "infant": ["face", "scalp", "extensor surfaces"],
        "adult": [
          "antecubital fossa",
          "popliteal fossa",
          "neck",
          "hands"
        ]
      },
      "course": "chronic, relapsing",
      "evidence_count": 5,
      "source_ids": ["src_sbx_ad_overview"]
    },
    {
      "id": "cond_seborrheic_dermatitis",
      "name": "Seborrheic dermatitis",
      "synonyms": ["Seborrheic eczema"],
      "codes": [
        {
          "system": "ICD-10-CM",
          "code": "L21.9",
          "display": "Seborrheic dermatitis, unspecified"
        }
      ],
      "morphology": ["erythematous patches", "greasy scale"],
      "evidence_count": 0,
      "source_ids": []
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "meta": {
    "request_id": "req_LH03TAgWSG",
    "knowledge_version": "kv_2026_10_01"
  }
}

GET`/conditions/{id}`

Retrieve a condition

Fetch one structured condition record from the current or a pinned knowledge version.

Scopeconditions:readTry it in the playground

Parameter	Description
`id`path · string · required	Condition id.

Errors404 NOT_FOUND401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl https://api.dermliving.com/v1/conditions/cond_atopic_dermatitis \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": {
    "id": "cond_atopic_dermatitis",
    "name": "Atopic dermatitis",
    "synonyms": ["Atopic eczema", "AD"],
    "codes": [
      {
        "system": "ICD-10-CM",
        "code": "L20.9",
        "display": "Atopic dermatitis, unspecified"
      },
      {
        "system": "ICD-11",
        "code": "EA80.Z",
        "display": "Atopic eczema, unspecified"
      }
    ],
    "morphology": [
      "xerosis",
      "erythematous papules",
      "excoriation",
      "lichenification"
    ],
    "sites": {
      "infant": ["face", "scalp", "extensor surfaces"],
      "adult": [
        "antecubital fossa",
        "popliteal fossa",
        "neck",
        "hands"
      ]
    },
    "course": "chronic, relapsing",
    "evidence_count": 5,
    "source_ids": ["src_sbx_ad_overview"]
  },
  "meta": {
    "request_id": "req_H1VuO83FY8",
    "knowledge_version": "kv_2026_10_01"
  }
}

Terminology

Resolve lay terms, abbreviations and codes to concepts, with ambiguity flagged.

GET`/terminology/map`

Map terminology

Resolve free text or a code to ranked concept candidates. Ambiguous input is flagged, never guessed.

Scopeterminology:readTry it in the playground

Parameter	Description
`text`query · string · required	A term, abbreviation or ICD-10-CM / ICD-11 code.

Errors400 VALIDATION_ERROR401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl "https://api.dermliving.com/v1/terminology/map?text=eczema" \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": {
    "input": "eczema",
    "ambiguous": true,
    "note": "Lay umbrella term. Confirm the intended concept.",
    "candidates": [
      {
        "concept_id": "cond_atopic_dermatitis",
        "name": "Atopic dermatitis",
        "match": "lay_term",
        "score": 0.81,
        "codes": ["ICD-10-CM L20.9", "ICD-11 EA80.Z"]
      },
      {
        "concept_id": "icd10cm_L30.9",
        "name": "Dermatitis, unspecified",
        "match": "index_term",
        "score": 0.64,
        "codes": ["ICD-10-CM L30.9"]
      }
    ]
  },
  "meta": {
    "request_id": "req_QVMUOiGE6V",
    "knowledge_version": "kv_2026_10_01"
  }
}

Evidence

Ranked passages and the sources behind them, with license and checksum.

POST`/evidence/search`

Search evidence

Retrieve ranked passages with source, version, locator and checksum. Full text is a licensed entitlement.

Scopeevidence:readTry it in the playground

Parameter	Description
`query`body · string · required	What to search for. At least 3 characters.
`limit`body · integer	Passages to return.Default 3 · 1 to 10
`include_full_text`body · boolean	Return full passages. Requires evidence:full_text.Default false

Errors400 VALIDATION_ERROR401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.json

1{
2  "query": "atopic dermatitis in adults",
3  "limit": 3
4}

Response200 · OK

{
  "data": [
    {
      "id": "ev_7Hq2",
      "score": 0.77,
      "snippet": "…atopic dermatitis most often involves flexural skin, including the antecubital…",
      "source": {
        "id": "src_sbx_ad_overview",
        "version": "sv_2026_09_14"
      },
      "locator": "Distribution, para 2",
      "checksum": "sha256:b2bb063ee133"
    },
    {
      "id": "ev_9Kd4",
      "score": 0.59,
      "snippet": "…a change called lichenification that is common at flexural sites in adults.",
      "source": {
        "id": "src_sbx_ad_overview",
        "version": "sv_2026_09_14"
      },
      "locator": "Morphology, para 1",
      "checksum": "sha256:fa16ed7145ce"
    },
    {
      "id": "ev_9Jm4",
      "score": 0.5,
      "snippet": "Acne most commonly begins around puberty, though it can persist into or…",
      "source": {
        "id": "src_sbx_acne_overview",
        "version": "sv_2026_09_25"
      },
      "locator": "Onset, para 1",
      "checksum": "sha256:2c4301163586"
    }
  ],
  "meta": {
    "request_id": "req_u5p0PkqAwI",
    "knowledge_version": "kv_2026_10_01"
  }
}

GET`/evidence/{id}`

Retrieve evidence

Fetch one passage's provenance: source, version, locator, checksum and license.

Scopeevidence:readTry it in the playground

Parameter	Description
`id`path · string · required	Evidence id.

Errors404 NOT_FOUND401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl https://api.dermliving.com/v1/evidence/ev_7Hq2 \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": {
    "id": "ev_7Hq2",
    "snippet": "…atopic dermatitis most often involves flexural skin, including the antecubital…",
    "source": {
      "id": "src_sbx_ad_overview",
      "version": "sv_2026_09_14",
      "title": "Atopic dermatitis: clinical overview"
    },
    "locator": "Distribution, para 2",
    "checksum": "sha256:b2bb063ee133",
    "license": "lic_sbx_synthetic",
    "knowledge_versions": ["kv_2026_10_01", "kv_2026_09_01"]
  },
  "meta": {
    "request_id": "req_S7pmsYCqCU",
    "knowledge_version": "kv_2026_10_01"
  }
}

GET`/sources/{id}`

Retrieve a source

Fetch a source's publisher, versions and the uses its license permits.

Scopeevidence:readTry it in the playground

Parameter	Description
`id`path · string · required	Source id.

Errors404 NOT_FOUND401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl https://api.dermliving.com/v1/sources/src_sbx_ad_overview \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": {
    "id": "src_sbx_ad_overview",
    "title": "Atopic dermatitis: clinical overview",
    "publisher": "DermLiving Sandbox Reference",
    "synthetic": true,
    "versions": ["sv_2026_09_14", "sv_2026_08_30"],
    "license": {
      "id": "lic_sbx_synthetic",
      "store": true,
      "embed": true,
      "display_snippets": true,
      "display_full_text": "entitlement",
      "train": false
    },
    "passages": 5,
    "first_in": "kv_2026_09_01"
  },
  "meta": {
    "request_id": "req_ljwAu01diu",
    "knowledge_version": "kv_2026_10_01"
  }
}

Knowledge

Grounded answers with claim-level citations, abstentions and pinned versions.

POST`/knowledge/ask`

Ask a question

Answer with claim-level citations, or abstain with a reason. Unsupported claims are removed before the response.

Scopeknowledge:queryTry it in the playground

Parameter	Description
`question`body · string · required	A reference question. At least 3 characters.
`knowledge_version`body · string	Pin a snapshot. Defaults to the current version.

Errors400 VALIDATION_ERROR401 INVALID_API_KEY403 INSUFFICIENT_SCOPE404 VERSION_NOT_FOUND429 RATE_LIMITED

request.json

1{
2  "question": "Where does atopic dermatitis usually appear in adults?"
3}

Response200 · OK

{
  "data": {
    "status": "grounded",
    "answer": "In adults, atopic dermatitis favors flexural skin, the neck, face and hands. [1] Chronic scratching at these sites commonly causes lichenification. [2]",
    "citations": [
      {
        "id": "cit_1",
        "evidence_id": "ev_7Hq2",
        "source": {
          "id": "src_sbx_ad_overview",
          "version": "sv_2026_09_14"
        },
        "locator": "Distribution, para 2",
        "checksum": "sha256:b2bb063ee133",
        "license": "lic_sbx_synthetic"
      },
      {
        "id": "cit_2",
        "evidence_id": "ev_9Kd4",
        "source": {
          "id": "src_sbx_ad_overview",
          "version": "sv_2026_09_14"
        },
        "locator": "Morphology, para 1",
        "checksum": "sha256:fa16ed7145ce",
        "license": "lic_sbx_synthetic"
      }
    ],
    "claims": [
      {
        "id": "clm_1",
        "text": "In adults, atopic dermatitis favors flexural skin, the neck, face and hands.",
        "citations": ["cit_1"]
      },
      {
        "id": "clm_2",
        "text": "Chronic scratching at these sites commonly causes lichenification.",
        "citations": ["cit_2"]
      }
    ],
    "removed_claims": []
  },
  "meta": {
    "request_id": "req_tX09J4dyUA",
    "knowledge_version": "kv_2026_10_01"
  }
}

GET`/knowledge/versions`

List knowledge versions

Immutable snapshots you can pin, newest first, with the release gates each one passed.

Scopeknowledge:queryTry it in the playground

No parameters.

Errors401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl https://api.dermliving.com/v1/knowledge/versions \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": [
    {
      "id": "kv_2026_10_01",
      "published_at": "2026-10-01",
      "status": "current",
      "sources": 4,
      "passages": 12,
      "gates": {
        "citation_validity": "pass",
        "claim_grounding": "pass",
        "curated_recall": "pass",
        "abstention": "pass",
        "tenant_isolation": "not_run",
        "tool_authorization": "pass"
      }
    },
    {
      "id": "kv_2026_09_01",
      "published_at": "2026-09-01",
      "status": "pinnable",
      "sources": 2,
      "passages": 4,
      "gates": {
        "citation_validity": "not_run",
        "claim_grounding": "not_run",
        "curated_recall": "not_run",
        "abstention": "not_run",
        "tenant_isolation": "not_run",
        "tool_authorization": "not_run"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "meta": {
    "request_id": "req_WxqkKCMW85",
    "knowledge_version": "kv_2026_10_01"
  }
}

Agents

The tool catalog agents call, over REST or the MCP server.

GET`/agent-tools`

List agent tools

The tool catalog, with each tool's scope and whether this key holds it.

Scopeagents:readTry it in the playground

No parameters.

Errors401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.sh

1curl https://api.dermliving.com/v1/agent-tools \
2  -H "DermLiving-Version: 2026-10-01"

Response200 · OK

{
  "data": [
    {
      "name": "search_conditions",
      "description": "Find conditions by name, synonym or code.",
      "required_scope": "conditions:read",
      "side_effects": false,
      "granted": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "A name, synonym or ICD-10-CM / ICD-11 code.",
            "minLength": 1
          },
          "limit": {
            "type": "integer",
            "description": "Results to return (1 to 100, default 20).",
            "minimum": 1,
            "maximum": 100
          }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    },
    {
      "name": "get_condition",
      "description": "Fetch a structured condition record.",
      "required_scope": "conditions:read",
      "side_effects": false,
      "granted": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "A condition id, such as cond_atopic_dermatitis.",
            "minLength": 1
          }
        },
        "required": ["id"],
        "additionalProperties": false
      }
    },
    {
      "name": "map_terminology",
      "description": "Resolve text or codes to concepts.",
      "required_scope": "terminology:read",
      "side_effects": false,
      "granted": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "A term, abbreviation or code. Ambiguous input is flagged, never guessed.",
            "minLength": 1
          }
        },
        "required": ["text"],
        "additionalProperties": false
      }
    },
    {
      "name": "search_evidence",
      "description": "Retrieve ranked passages with provenance.",
      "required_scope": "evidence:read",
      "side_effects": false,
      "granted": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "What to search for.",
            "minLength": 3
          },
          "limit": {
            "type": "integer",
            "description": "Passages to return (1 to 10, default 3).",
            "minimum": 1,
            "maximum": 10
          },
          "include_full_text": {
            "type": "boolean",
            "description": "Full passages instead of snippets. Needs the evidence:full_text entitlement."
          }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    },
    {
      "name": "ask_knowledge",
      "description": "Answer with claim-level citations, or abstain.",
      "required_scope": "knowledge:query",
      "side_effects": false,
      "granted": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string",
            "description": "A reference question. Never include patient identifiers.",
            "minLength": 3
          },
          "knowledge_version": {
            "type": "string",
            "description": "Pin a knowledge version, such as kv_2026_10_01. Defaults to the current one."
          }
        },
        "required": ["question"],
        "additionalProperties": false
      }
    }
  ],
  "meta": {
    "request_id": "req_76fKCquyI2",
    "knowledge_version": "kv_2026_10_01"
  }
}

POST`/agent-tools/execute`

Execute a tool

Run one catalog tool with validated arguments. Calls outside the key's scopes are refused and traced.

Scopeagents:executeTry it in the playground

Parameter	Description
`tool`body · enum · required	Tool name.One of `search_conditions`, `get_condition`, `map_terminology`, `search_evidence`, `ask_knowledge`
`arguments`body · object · required	The tool's arguments, as a JSON object.

Errors400 VALIDATION_ERROR404 TOOL_NOT_FOUND404 NOT_FOUND404 VERSION_NOT_FOUND401 INVALID_API_KEY403 INSUFFICIENT_SCOPE429 RATE_LIMITED

request.json

1{
2  "tool": "map_terminology",
3  "arguments": {
4    "text": "AD"
5  }
6}

Response200 · OK

{
  "data": {
    "tool": "map_terminology",
    "trace_id": "trc_oZu0hIkWAI",
    "result": {
      "input": "AD",
      "ambiguous": false,
      "context": "dermatology",
      "note": "Abbreviation resolved in dermatology context.",
      "candidates": [
        {
          "concept_id": "cond_atopic_dermatitis",
          "name": "Atopic dermatitis",
          "match": "abbreviation",
          "score": 0.94,
          "codes": ["ICD-10-CM L20.9", "ICD-11 EA80.Z"]
        }
      ]
    }
  },
  "meta": {
    "request_id": "req_phWYAeKKWm",
    "knowledge_version": "kv_2026_10_01"
  }
}

Error codes

A refusal is typed and worded, never a bare status. Every error shares one envelope; Errors shows its fields.

Status	Code	Retry	When
400	`VALIDATION_ERROR`	No	A parameter is missing, the wrong type or out of range.
401	`INVALID_API_KEY`	No	A key was sent but is malformed, unknown or revoked. Send no Authorization header for the keyless sandbox.
403	`INSUFFICIENT_SCOPE`	No	The caller (keyless, or a key) lacks the route's scope or an entitlement such as evidence:full_text.
404	`NOT_FOUND`	No	No record with that id exists in the requested knowledge version.
404	`ROUTE_NOT_FOUND`	No	No route matches the method and path.
404	`TOOL_NOT_FOUND`	No	The tool is not in the catalog.
404	`VERSION_NOT_FOUND`	No	The pinned knowledge_version does not exist.
429	`RATE_LIMITED`	Yes	Too many requests. Wait for Retry-After seconds.
500	`INTERNAL_ERROR`	Yes	Something failed on our side. Retry with backoff; the request id is in the body.

Base URL