Domain Knowledge API

Domain Knowledge exposes a REST surface for concepts, semantic layer, ontology, and AI suggestion review.

For the functional product view, journeys, and positioning, see Domain Knowledge.

Authentication and Scope

• all routes require JWT;
• the effective scope is always the authenticated token company;
• team is not the primary knowledge partition today.

Permissions

• concepts:list/get/create/update/delete
• semantic:list/create/update/delete
• ontology:list/create/update/delete
• knowledge_reviews:list
• knowledge_reviews:generate
• knowledge_reviews:review

Resource Shapes

Concept

• name
• description
• status: draft | active | archived
• type: term | rule | entity_hint | metric_hint | policy_hint
• aliases[]
• tags[]
• source
• confidence
• related_catalog_assets[]

Semantic Item

• kind: entity | metric | dimension | mapping
• name
• description
• status
• formula
• grain
• filters[]
• aggregation
• mapped_tables[]
• mapped_columns[]
• mapped_relations[]
• source_concept_ids[]
• depends_on_concepts[]
• depends_on_metrics[]
• depends_on_entities[]
• validation_errors[]

Ontology Node

• name
• description
• node_type: class | role | event | object | state
• status
• parent_node_id
• aliases[]
• attributes[]
• constraints[]
• source_concepts[]
• mapped_semantic_entities[]
• mapped_catalog_assets[]

Ontology Relation

• subject_node_id
• predicate
• object_node_id
• description
• cardinality
• relation_type
• confidence
• evidence[]
• status

Suggestion

• target_type
• target_id
• target_name
• concept_id
• concept_name
• suggested_payload
• explanation
• evidence[]
• confidence
• model
• prompt_version
• status
• request_id
• job_id
• review_note

Current status values:

• pending
• accepted
• rejected
• superseded

Job

• target_type: concept | semantic | ontology_node | ontology_relation
• target_ids[]
• status: queued | running | succeeded | failed | cancelled
• processed_count
• total_count
• last_error
• request_id

Endpoints

Concepts

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/concepts	List concepts with pagination and filters
GET	/api/v1/domain-knowledge/concepts/:id	Fetch one concept
POST	/api/v1/domain-knowledge/concepts	Create concept
PATCH	/api/v1/domain-knowledge/concepts/:id	Update concept
DELETE	/api/v1/domain-knowledge/concepts/:id	Archive concept

Supported query params:

• page
• per_page
• search
• status
• type

Suggestions

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/suggestions	List pending suggestions
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/generate	Generate concept suggestion
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/promote-semantic	Suggest promotion to semantic layer
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/promote-ontology	Suggest promotion to ontology
POST	/api/v1/domain-knowledge/suggestions/semantic/:id/generate	Generate semantic suggestion
POST	/api/v1/domain-knowledge/suggestions/ontology/nodes/:id/generate	Generate node suggestion
POST	/api/v1/domain-knowledge/suggestions/ontology/relations/:id/generate	Generate relation suggestion
POST	/api/v1/domain-knowledge/suggestions/:id/accept	Accept suggestion
POST	/api/v1/domain-knowledge/suggestions/:id/reject	Reject suggestion

Current target_type values:

• concept
• semantic
• semantic_create
• ontology_node
• ontology_node_create
• ontology_relation

Semantic Layer

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/semantic	List semantic items
POST	/api/v1/domain-knowledge/semantic	Create semantic item
PATCH	/api/v1/domain-knowledge/semantic/:id	Update semantic item
DELETE	/api/v1/domain-knowledge/semantic/:id	Archive semantic item

Ontology

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/ontology/nodes	List nodes
POST	/api/v1/domain-knowledge/ontology/nodes	Create node
PATCH	/api/v1/domain-knowledge/ontology/nodes/:id	Update node
DELETE	/api/v1/domain-knowledge/ontology/nodes/:id	Archive node
GET	/api/v1/domain-knowledge/ontology/relations	List relations
POST	/api/v1/domain-knowledge/ontology/relations	Create relation
PATCH	/api/v1/domain-knowledge/ontology/relations/:id	Update relation
DELETE	/api/v1/domain-knowledge/ontology/relations/:id	Archive relation

Jobs

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/jobs	List enrichment jobs
GET	/api/v1/domain-knowledge/jobs/:id	Get job status
POST	/api/v1/domain-knowledge/jobs/enrich	Create async enrichment job

Validation Rules

• name and description are required when creating the main resources
• description accepts up to 4096 characters
• aliases[], tags[], related_catalog_assets[], and source_concept_ids[] have a maximum of 20 items
• create status accepts draft or active
• predicate is required for ontology relations
• entity, metric, and dimension require at least one source_concept_id
• jobs require at least one target_id

AI configuration

Suggestion generation routes return 503 when OPENROUTER_API_KEY is not configured.

Examples

Create a concept:

curl -X POST https://api.console.solucao42.com.br/api/v1/domain-knowledge/concepts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Net revenue",
    "description": "Revenue after discounts and refunds",
    "status": "active",
    "type": "metric_hint",
    "aliases": ["net sales"],
    "tags": ["finance"]
  }'

Reject a suggestion:

curl -X POST https://api.console.solucao42.com.br/api/v1/domain-knowledge/suggestions/SUGGESTION_ID/reject \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "review_note": "This does not reflect the company official rule"
  }'