API de Conhecimento de Dominio

Conhecimento de Dominio expoe uma superficie REST para conceitos, camada semantica, ontologia e revisao de sugestoes de IA.

Para a visao funcional do modulo, jornadas e posicionamento no produto, veja Conhecimento de Dominio.

Authentication and Scope

• todas as rotas exigem JWT;
• o escopo efetivo e sempre a company do token autenticado;
• team nao e a particao primaria do conhecimento hoje.

Permissions

Action	Description
concepts:list/get/create/update/delete	Concept operations
semantic:list/create/update/delete	Semantic layer operations
ontology:list/create/update/delete	Ontology operations
knowledge_reviews:list	List pending suggestions
knowledge_reviews:generate	Generate AI suggestions
knowledge_reviews:review	Accept or reject suggestions

Important rule

Accepting a suggestion requires knowledge_reviews:review and also the target resource create or update permission.

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

Query params currently supported:

• 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"
  }'

Status

Topic	Status
Concepts API	Available
Semantic API	Available
Ontology API	Available
Suggestion review API	Available
Async enrichment jobs	Planned
More advanced semantic fields	Planned
Formal ontology relation types	Planned