API de Conocimiento de Dominio

Conocimiento de Dominio expone una superficie REST para conceptos, capa semantica, ontologia y revision de sugerencias de IA.

Para la vista funcional del producto, jornadas y posicionamiento, consulta Conocimiento de Dominio.

Authentication and Scope

• todas las rutas exigen JWT;
• el alcance efectivo siempre es la company del token autenticado;
• team no es la particion primaria del conocimiento hoy.

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	Lista conceptos con paginacion y filtros
GET	/api/v1/domain-knowledge/concepts/:id	Obtiene un concepto
POST	/api/v1/domain-knowledge/concepts	Crea concepto
PATCH	/api/v1/domain-knowledge/concepts/:id	Actualiza concepto
DELETE	/api/v1/domain-knowledge/concepts/:id	Archiva concepto

Supported query params:

• page
• per_page
• search
• status
• type

Suggestions

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/suggestions	Lista sugerencias pendientes
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/generate	Genera sugerencia para concepto
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/promote-semantic	Sugiere promocion a capa semantica
POST	/api/v1/domain-knowledge/suggestions/concepts/:id/promote-ontology	Sugiere promocion a ontologia
POST	/api/v1/domain-knowledge/suggestions/semantic/:id/generate	Genera sugerencia para item semantico
POST	/api/v1/domain-knowledge/suggestions/ontology/nodes/:id/generate	Genera sugerencia para nodo
POST	/api/v1/domain-knowledge/suggestions/ontology/relations/:id/generate	Genera sugerencia para relacion
POST	/api/v1/domain-knowledge/suggestions/:id/accept	Acepta sugerencia
POST	/api/v1/domain-knowledge/suggestions/:id/reject	Rechaza sugerencia

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	Lista items semanticos
POST	/api/v1/domain-knowledge/semantic	Crea item semantico
PATCH	/api/v1/domain-knowledge/semantic/:id	Actualiza item semantico
DELETE	/api/v1/domain-knowledge/semantic/:id	Archiva item semantico

Ontology

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/ontology/nodes	Lista nodos
POST	/api/v1/domain-knowledge/ontology/nodes	Crea nodo
PATCH	/api/v1/domain-knowledge/ontology/nodes/:id	Actualiza nodo
DELETE	/api/v1/domain-knowledge/ontology/nodes/:id	Archiva nodo
GET	/api/v1/domain-knowledge/ontology/relations	Lista relaciones
POST	/api/v1/domain-knowledge/ontology/relations	Crea relacion
PATCH	/api/v1/domain-knowledge/ontology/relations/:id	Actualiza relacion
DELETE	/api/v1/domain-knowledge/ontology/relations/:id	Archiva relacion

Jobs

Method	Endpoint	Description
GET	/api/v1/domain-knowledge/jobs	Lista jobs de enriquecimiento
GET	/api/v1/domain-knowledge/jobs/:id	Obtiene el estado del job
POST	/api/v1/domain-knowledge/jobs/enrich	Crea un job asíncrono de enriquecimiento

Validation Rules

• name y description son obligatorios al crear los recursos principales
• description acepta hasta 4096 caracteres
• aliases[], tags[], related_catalog_assets[] y source_concept_ids[] tienen un maximo de 20 items
• el status de creacion acepta draft o active
• predicate es obligatorio en relaciones ontologicas
• entity, metric y dimension exigen al menos un source_concept_id
• los jobs exigen al menos un target_id

AI configuration

Las rutas de generacion devuelven 503 cuando OPENROUTER_API_KEY no esta configurada.

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": "Ingresos netos",
    "description": "Ingresos despues de descuentos y devoluciones",
    "status": "active",
    "type": "metric_hint",
    "aliases": ["net revenue"],
    "tags": ["finanzas"]
  }'

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": "No refleja la regla oficial de la empresa"
  }'