# Icosa Codes

> Current identifiers for concepts in the Icosa structural personality model. Catalog 1.0, dated 2026-09-20, 1,217 published concepts, 1,217 active. Read-only, public, no authentication.

Mappings are structural correspondences, never equivalences. An Icosa code is not a diagnosis, not an independently recognized payer billing code, and never a substitute for an external code.

## Code grammar

Every code is `ICOSA-<NAMESPACE>-<KEY>`. This catalog lists every published code, retired ones included: a code string is never deleted, reused or reassigned. A retired row carries `status: retired`, `retired_on` and, where something supersedes it, `replaced_by`; its FHIR concept is `inactive`. Numeric namespaces are contiguous from `0001` in domain order.

## Namespaces

Counts are published codes per namespace, with the current assignments beside them.

- `ICOSA-AXIS-*` (9 published, 9 active) — capacities and domains, the two axes of the grid. Example: https://codes.icosa.org/ICOSA-AXIS-B
- `ICOSA-BSN-*` (39 published, 39 active) — basins, basin types, and systemic basins. Example: https://codes.icosa.org/ICOSA-BSN-0007
- `ICOSA-CAV-*` (168 published, 168 active) — cascades and cascade types. Example: https://codes.icosa.org/ICOSA-CAV-0137
- `ICOSA-CMP-*` (32 published, 32 active) — compensations, a hidden deficit paired with the surplus covering it. Example: https://codes.icosa.org/ICOSA-CMP-0019
- `ICOSA-DFM-*` (173 published, 173 active) — dyadic formation cores. Example: https://codes.icosa.org/ICOSA-DFM-0001
- `ICOSA-DYN-*` (84 published, 84 active) — dyadic dynamics. Example: https://codes.icosa.org/ICOSA-DYN-0030
- `ICOSA-HAR-*` (20 published, 20 active) — harmonies, one capacity crossed with one domain. Example: https://codes.icosa.org/ICOSA-HAR-VS
- `ICOSA-HPR-*` (190 published, 190 active) — harmony pairs, two distinct harmonies in canonical order. Example: https://codes.icosa.org/ICOSA-HPR-OEBE
- `ICOSA-INT-*` (21 published, 21 active) — interactions between traps, basins, compensations, and cascades. Example: https://codes.icosa.org/ICOSA-INT-0001
- `ICOSA-PAT-*` (368 published, 368 active) — patterns. Example: https://codes.icosa.org/ICOSA-PAT-0128
- `ICOSA-PTH-*` (18 published, 18 active) — paths. Example: https://codes.icosa.org/ICOSA-PTH-0001
- `ICOSA-QUIZ-*` (2 published, 2 active) — quizzes. Example: https://codes.icosa.org/ICOSA-QUIZ-Q20
- `ICOSA-TEST-*` (5 published, 5 active) — assessment instruments. Example: https://codes.icosa.org/ICOSA-TEST-D40
- `ICOSA-TRP-*` (88 published, 88 active) — traps and trap types. Example: https://codes.icosa.org/ICOSA-TRP-0001

## Endpoints

- [Whole catalog](https://codes.icosa.org/catalog.json): every concept with its mappings, one request. Its `count` and `namespaces` cover every published code and `active_count` the current assignments. Fetch this once instead of walking codes individually.
- [One concept](https://codes.icosa.org/ICOSA-HAR-BE.json): append `.json` to any code. Without the extension the same URL serves an HTML page.
- [FHIR CapabilityStatement](https://codes.icosa.org/fhir/metadata): the machine-readable description of this API (FHIR R5).
- [Sitemap](https://codes.icosa.org/sitemap.xml): every code URL.

## FHIR terminology operations

Standard FHIR R5. `$lookup`, `$validate-code`, and `$subsumes` on `/fhir/CodeSystem`; `$validate-code` and `$expand` on `/fhir/ValueSet`; `$translate` on `/fhir/ConceptMap`. Both GET (query parameters) and POST (a `Parameters` resource) are accepted.

- https://codes.icosa.org/fhir/CodeSystem/$lookup?system=https://codes.icosa.org&code=ICOSA-HAR-BE
- https://codes.icosa.org/fhir/ValueSet/harmonies/$expand

## Correspondence systems

- [Ayurveda](https://codes.icosa.org/concept-maps/ayurveda): no official external code set; identifiers are Icosa-assigned references.
- [Homeopathy](https://codes.icosa.org/concept-maps/homeopathy): no official external code set; identifiers are Icosa-assigned references.
- [ICD-10-CM](https://codes.icosa.org/concept-maps/icd-10-cm): carries official external codes.
- [ICD-11 MMS](https://codes.icosa.org/concept-maps/icd-11-mms): carries official external codes.
- [Named Clinical Phenomena and Related Constructs](https://codes.icosa.org/concept-maps/clinical): no official external code set; identifiers are Icosa-assigned references.
- [Traditional Chinese Medicine](https://codes.icosa.org/concept-maps/tcm): no official external code set; identifiers are Icosa-assigned references.

## Optional

- [Authentication](https://codes.icosa.org/auth.md): there is none. Read why before building an auth flow.
- [Agent skill](https://codes.icosa.org/.well-known/agent-skills/icosa-codes/SKILL.md): the code grammar and query recipes as an installable skill.