Skip to content

Custom Ontologies API

Create and manage tenant-scoped ontologies, resolve ontology bundles for uploads, and control ontology filtering behavior (strict vs guided).

Base URL

BASE_URL = "https://api.fermi.dev/public/v1"

Why this API exists

Custom ontologies let teams define domain vocabulary (for example legal or finance) and use it to:

  • filter document content in strict mode
  • annotate matching graph nodes with category labels
  • scope semantic queries to ontology-relevant brain nodes

Ontology payload fields

Field Type Meaning
ontologyId string Unique lowercase ID. Used in upload requests via ontologyIds
displayName string Human-readable category label written to Neo4j (category / categories)
entityTypes string[] Domain entity types (for direct type matching)
legalTerms string[] Keywords/phrases matched in text
requiredFields string[] Terms indicating required data points for the domain
version integer Version marker set by caller on create/update

Create ontology

POST /ontologies

Create-only endpoint.

{
  "ontologyId": "legal_ontology_v1",
  "displayName": "Legal Ontology v1",
  "entityTypes": ["Actor", "Sponsor", "Regulator"],
  "legalTerms": ["shall", "must", "prohibited"],
  "requiredFields": ["date", "amount"],
  "version": 1
}

Responses

  • 201 created
  • 400 invalid payload
  • 409 ontology with this ontologyId is already active for this tenant

!!! note "Re-creating a previously deleted ontology id" Delete is soft (see Delete ontology). If an ontologyId was deleted earlier, you can POST /ontologies again with the same id — it will replace the deleted record with a fresh active ontology. createdAt / createdBy are reset to the new creation time. You will only get 409 if there is a current active ontology with that id.

Update ontology

PATCH /ontologies/{ontologyId}

Partial update endpoint. Only provided fields are changed; omitted fields are left untouched.

{
  "displayName": "Legal Ontology v1 - Updated",
  "legalTerms": ["shall", "must", "may", "prohibited"],
  "version": 2
}

Responses

  • 200 updated
  • 404 ontology not found, or it has been soft-deleted (re-create via POST /ontologies first)

!!! note - version is caller-controlled. It is updated only if provided in payload. - PATCH only operates on active ontologies. A soft-deleted id will return 404; use POST /ontologies to re-create it instead.

List ontologies

GET /ontologies

Returns active ontologies for tenant.

Get ontology by ID

GET /ontologies/{ontologyId}

Returns full ontology details.

Delete ontology

DELETE /ontologies/{ontologyId}

Soft-deletes the ontology. The record is retained in storage with status = "deleted" and is hidden from GET /ontologies, GET /ontologies/{ontologyId}, and ontology resolution.

Responses

  • 200 deleted (or already deleted)
  • 404 ontology not found

!!! info "After delete" - The same ontologyId becomes available for re-use via POST /ontologies (see the note in Create ontology). - Documents previously processed with this ontology keep their existing Neo4j annotations; only future uploads stop seeing it.

Resolve ontology selection (pre-upload)

POST /ontologies/resolve

Use this to validate and expand upload ontology selection into a resolved ontology bundle.

{
  "tenantId": "org_123",
  "ontologyIds": ["legal_ontology_v1", "finance_ontology_v1"],
  "ontologyMode": "strict",
  "documentGroup": "corporate_deals"
}

Returns:

  • normalized ontologyIds
  • effective ontologyMode
  • documentGroup
  • ontologyBundle (full ontology definitions used by pipeline)

If unknown IDs are sent, returns 400.

Legacy upsert endpoint

POST /ontologies/upsert

Legacy endpoint kept for backward compatibility. Prefer:

  • POST /ontologies for create
  • PATCH /ontologies/{ontologyId} for update

Strict vs guided mode

Mode Effect in pipeline
strict Hard filter: non-matching chunks/entities are removed before Neo4j write
guided Soft lens: all content retained; matching nodes are annotated

Both modes can write ontology metadata to matching nodes:

  • category (first matched ontology display name)
  • categories (all matched ontology display names)
  • ontology_ids, ontology_mode, ontology_term_hits

Matching basis

Ontology matching is term and type driven:

  • entity type/subtype compared with entityTypes
  • text fields scanned for entityTypes + legalTerms + requiredFields
  • whole-word style normalized matching

For multi-ontology uploads, each node can match multiple ontologies.

Validation and limits

  • max ontology IDs per upload request: 8
  • max entityTypes: 64
  • max legalTerms: 256
  • max requiredFields: 128
  • max term length: 128
  • invalid ontologyId format: 400
  • missing all three term lists on create: 400

Upload integration

Document uploads can include:

  • ontologyIds
  • ontologyMode
  • documentGroup

See Document Connector for multipart examples and behavior.