> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heyhumm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Ontology via API

> Review and update your business ontology through the Humm Config API with versioned changes.

Use this workflow when you want to refine how Humm understands your business entities, relationships, metrics, and glossary terms.

## Before You Begin

You will need:

* Your organization ID
* A Humm API token
* The Config API base URL, usually `https://config.heyhumm.ai/api`

<Note>
  Ontology updates create a new version. Fetch the current ontology first, make your edits locally, and include a short `change_log` when you save.
</Note>

## Recommended Flow

1. Fetch the current ontology
2. Save the JSON or YAML locally
3. Draft your changes
4. Review the diff
5. Apply the `PUT`
6. Verify the new version

## 1. Fetch the Current Ontology

JSON:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://config.heyhumm.ai/api/organization/$ORG_ID/ontology" \
  --header "Authorization: Bearer $HUMM_PAT"
```

YAML:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://config.heyhumm.ai/api/organization/$ORG_ID/ontology?format=yaml" \
  --header "Authorization: Bearer $HUMM_PAT"
```

## 2. Apply the Update

You can send either `ontology` JSON or `yaml`. YAML is often easier to diff and review.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  --url "https://config.heyhumm.ai/api/organization/$ORG_ID/ontology" \
  --header "Authorization: Bearer $HUMM_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "change_log": "Add Subscription entity and define NRR",
    "yaml": "metadata:\n  organization_name: Acme Corp\nbusiness_entities:\n  - name: Subscription\n    type: Thing\n    description: Recurring customer contract\nrelationships: []\ndata_entity_mappings: {}\nkey_metrics:\n  - name: Net Revenue Retention\n    description: Revenue retained from existing customers including expansion\n    involved_entities:\n      - Subscription\nbusiness_glossary:\n  NRR: Net Revenue Retention\nbusiness_rules: []\n"
  }'
```

## Python Example

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import difflib
import os
import requests
import yaml

base_url = "https://config.heyhumm.ai/api"
headers = {"Authorization": f"Bearer {os.environ['HUMM_PAT']}"}
org_id = os.environ["ORG_ID"]

current = requests.get(
    f"{base_url}/organization/{org_id}/ontology",
    params={"format": "yaml"},
    headers=headers,
    timeout=30,
)
current.raise_for_status()
current_yaml = current.json()["yaml"]

ontology = yaml.safe_load(current_yaml) or {}
glossary = dict(ontology.get("business_glossary") or {})
glossary["NRR"] = "Net Revenue Retention"
ontology["business_glossary"] = glossary
proposed_yaml = yaml.safe_dump(ontology, sort_keys=False, default_flow_style=False)

print("\n".join(difflib.unified_diff(
    current_yaml.splitlines(),
    proposed_yaml.splitlines(),
    fromfile="before.yaml",
    tofile="after.yaml",
    lineterm="",
)))

approved = input("Apply ontology update? [y/N] ").strip().lower() == "y"
if approved:
    res = requests.put(
        f"{base_url}/organization/{org_id}/ontology",
        headers={**headers, "Content-Type": "application/json"},
        json={
            "yaml": proposed_yaml,
            "change_log": "Add NRR glossary term",
        },
        timeout=30,
    )
    res.raise_for_status()
    print(res.json()["version"])
```

## TypeScript Example

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const baseUrl = "https://config.heyhumm.ai/api";

async function updateOntology(orgId: string, token: string) {
  const current = await fetch(
    `${baseUrl}/organization/${orgId}/ontology`,
    { headers: { Authorization: `Bearer ${token}` } },
  );

  if (!current.ok) throw new Error(`Fetch failed: ${current.status}`);
  const body = await current.json();
  const ontology = body.ontology ?? {};
  const proposedOntology = {
    ...ontology,
    business_glossary: {
      ...(ontology.business_glossary ?? {}),
      NRR: "Net Revenue Retention",
    },
  };

  console.log("Preview only:");
  console.log({
    before: ontology.business_glossary ?? {},
    after: proposedOntology.business_glossary,
  });

  const res = await fetch(`${baseUrl}/organization/${orgId}/ontology`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      ontology: proposedOntology,
      change_log: "Add NRR glossary term",
    }),
  });

  if (!res.ok) throw new Error(`Update failed: ${res.status}`);
  return res.json();
}
```

## Prompt Your Assistant

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use the Humm Config API to update our ontology.

Organization:
- Use this organization ID: $ORG_ID

Change request:
- Add or update the ontology based on the change I describe

Workflow:
1. Fetch the current ontology in YAML form first
2. Save the current YAML locally as a backup
3. Review the current ontology before editing:
   - metadata
   - business_entities
   - relationships
   - key_metrics
   - business_glossary
   - business_rules
4. Draft the proposed YAML locally
5. Keep the change narrow and intentional:
   - preserve existing structure and formatting when possible
   - add only the entities, relationships, metrics, glossary terms, or rules needed for this change
   - do not rename unrelated concepts
6. Validate the proposal before applying it:
   - relationships should reference real entities
   - descriptions should stay concise
   - the change should fit the existing ontology instead of rewriting it broadly
7. Show me:
   - the YAML diff
   - a short summary of what changed
   - any validation concerns or assumptions
8. Wait for my approval before calling PUT
9. Include a clear change_log in the write request
10. After the write succeeds, re-fetch:
   - the current ontology
   - the ontology versions list
11. Confirm:
   - the version number increased
   - the saved ontology matches the approved diff
   - the version history includes the intended change_log

Constraints:
- Do not call PUT until I approve the diff
- Prefer YAML for review unless I explicitly ask for JSON
- If the request is ambiguous, identify the missing business detail before making edits
```

## Verification

After saving, verify both the current ontology and version history:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://config.heyhumm.ai/api/organization/$ORG_ID/ontology" \
  --header "Authorization: Bearer $HUMM_PAT"
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request GET \
  --url "https://config.heyhumm.ai/api/organization/$ORG_ID/ontology/versions" \
  --header "Authorization: Bearer $HUMM_PAT"
```

Confirm:

* The returned ontology matches the approved changes
* The version number increased
* The version history includes your `change_log`

## Notes

* YAML is easier to review when you want a human in the loop.
* JSON is a better fit if you generate ontology updates programmatically.
* Do not append duplicate top-level YAML keys like `business_glossary` to the end of the document. Parse and update the existing structure instead, or send the merged JSON ontology payload.
* Keep changes narrow and intentional. Large ontology rewrites are harder to review and debug.