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
• 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/bulk-accept	Accept multiple visible suggestions in one request
POST	/api/v1/domain-knowledge/suggestions/:id/reject	Reject suggestion

POST /api/v1/domain-knowledge/suggestions/:id/accept now accepts optional override_payload for concept review flows, allowing the reviewer to adjust fields before approval.

Current target_type values:

• concept
• concept_create
• semantic
• semantic_create
• ontology_node
• ontology_node_create
• ontology_relation
• ontology_relation_create

concept_create representa uma sugestao pendente para criar um novo conceito draft apos revisao humana. ontology_relation_create representa uma sugestao pendente para criar uma nova relacao de ontologia; ela pode depender de nos sugeridos e ainda nao aceitos.

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

Concept Generation

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/concepts/generation/prerequisites	Read generation prerequisites, business domains and accepted file types
POST	/api/v1/domain-knowledge/concepts/generation/jobs	Create async concept generation job from business domains, optional text and optional file
GET	/api/v1/domain-knowledge/concepts/generation/jobs/:id	Poll async concept generation job status

Concept generation may run in multiple internal batches until the useful context is exhausted or a technical stop condition is reached; it is not limited to a fixed public cap of 10 concepts per execution.

Generation jobs send the current active and draft concepts as existing context to the model. The model must classify each candidate as either enrichment of an existing concept or creation of a new one. When a job succeeds with at least one valid suggestion, its batch replaces the previous pending batch-generated concept and concept_create suggestions for the same company. If the job finishes with zero valid suggestions or fails, the previous pending batch remains unchanged.

Ontology Generation

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/ontology/generation/prerequisites	Read ontology generation prerequisites, eligible synced connections and entity_hint concept count
POST	/api/v1/domain-knowledge/ontology/generation/jobs	Create async ontology generation job from all entity_hint concepts and one selected connection
GET	/api/v1/domain-knowledge/ontology/generation/jobs/:id	Poll async ontology generation job status

Ontology generation uses all company concepts with type = entity_hint plus the full tabular catalog of one selected synced connection. The job creates only pending suggestions for ontology nodes and relations, including ontology_relation_create when a new edge must be reviewed before publication.

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
• concept generation requires at least one configured business_domain
• concept generation accepts at most one file per job
• accepted file extensions for concept generation: .docx, .xlsx, .csv, .tsv, .txt, .md
• ontology generation requires at least one entity_hint concept
• ontology generation requires one eligible synced connection with tabular metadata
• ontology_relation_create can only be accepted after its dependent ontology_node_create suggestions have been accepted

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
Concept generation API	Available
Ontology generation 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