Referencia de API

Introducción

La API de Kodus te permite integrar las funcionalidades de inteligencia legal directamente en tus aplicaciones, flujos de trabajo o sistemas internos.

La API es RESTful, usa JSON para requests y responses, y requiere autenticación mediante API Key.

URL Base


https://api.koduslegal.com/v1

Autenticación

Todas las solicitudes deben incluir tu API Key en el header:


Authorization: Bearer tu_api_key_aqui

Para obtener tu API Key:

Iniciá sesión en koduslegal.com
Andá a Configuración → API
Hacé clic en “Generar API Key”

⚠️ Importante: Nunca compartas tu API Key ni la incluyas en código del lado del cliente (frontend). Usala solo en servidores backend.

Límites de uso

Plan	Solicitudes por minuto	Solicitudes por día
Gratuito	10	100
Profesional	60	5,000
Empresa	300	50,000

Códigos de respuesta

Código	Significado
`200`	Solicitud exitosa
`400`	Error en los parámetros enviados
`401`	API Key inválida o faltante
`403`	No tenés permiso para este recurso
`429`	Límite de solicitudes excedido
`500`	Error interno del servidor

Endpoints

POST /api/ask

Hacé preguntas en lenguaje natural sobre derecho costarricense. Equivalente al Chat Inteligente de la plataforma.

Request:


curl -X POST https://api.koduslegal.com/v1/ask \
  -H "Authorization: Bearer tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "¿Cuál es el plazo de prescripción para cobro de alquileres en Costa Rica?",
    "include_sources": true,
    "language": "es"
  }'

Parámetros del body:

Parámetro	Tipo	Requerido	Descripción
`question`	string	✅	La pregunta en lenguaje natural
`include_sources`	boolean	❌	Incluir fuentes citadas (default: `true`)
`language`	string	❌	Idioma de la respuesta: `es` o `en` (default: `es`)
`session_id`	string	❌	ID de sesión para mantener contexto entre preguntas

Response (200):


{
  "answer": "Según el artículo 868 del Código Civil de Costa Rica, el plazo de prescripción para el cobro de alquileres es de tres años, contados a partir de la fecha de vencimiento de cada mensualidad.",
  "sources": [
    {
      "title": "Código Civil de Costa Rica",
      "type": "ley",
      "reference": "Artículo 868",
      "date": "1888-01-01",
      "url": "https://koduslegal.com/doc/codigo-civil-868"
    }
  ],
  "confidence": 0.94,
  "session_id": "sess_abc123"
}

GET /api/search

Busca documentos legales usando búsqueda semántica, full-text o híbrida.

Request:


curl -X GET "https://api.koduslegal.com/v1/search?q=proteccion+datos+personales&type=ley&limit=10" \
  -H "Authorization: Bearer tu_api_key"

Parámetros de query:

Parámetro	Tipo	Requerido	Descripción
`q`	string	✅	Consulta de búsqueda
`type`	string	❌	Filtrar por tipo: `ley`, `decreto`, `resolucion`, `directriz`
`date_from`	string	❌	Fecha mínima (formato: `YYYY-MM-DD`)
`date_to`	string	❌	Fecha máxima (formato: `YYYY-MM-DD`)
`entity`	string	❌	Filtrar por entidad emisora
`limit`	integer	❌	Número de resultados (default: `10`, max: `50`)
`offset`	integer	❌	Desplazamiento para paginación (default: `0`)

Response (200):


{
  "results": [
    {
      "id": "doc_ley8968",
      "title": "Ley N° 8968 — Ley de Protección de la Persona frente al Tratamiento de sus Datos Personales",
      "type": "ley",
      "date": "2011-07-07",
      "relevance_score": 0.98,
      "excerpt": "La presente ley es de orden público y tiene como objetivo garantizar a cualquier persona, independientemente de su nacionalidad y residencia, el respeto a su derecho a la autodeterminación informativa...",
      "url": "https://koduslegal.com/doc/ley-8968",
      "related_docs": ["doc_decreto37554", "doc_prodhab_2023"]
    }
  ],
  "total": 47,
  "limit": 10,
  "offset": 0
}

GET /api/alerts

Lista las alertas configuradas en tu cuenta.

Request:


curl -X GET "https://api.koduslegal.com/v1/alerts?status=active" \
  -H "Authorization: Bearer tu_api_key"

Parámetros de query:

Parámetro	Tipo	Requerido	Descripción
`status`	string	❌	Filtrar por estado: `active`, `paused`, `all` (default: `all`)
`limit`	integer	❌	Número de resultados (default: `20`)
`offset`	integer	❌	Desplazamiento para paginación (default: `0`)

Response (200):


{
  "alerts": [
    {
      "id": "alert_001",
      "name": "Regulaciones Fintech",
      "topic": "Regulación de servicios financieros digitales",
      "entity": "SUGEF",
      "doc_type": null,
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "last_triggered": "2024-03-01T08:15:00Z",
      "trigger_count": 4
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

POST /api/analyze

Subí un documento para análisis con IA. Retorna resumen, entidades y riesgos.

Request:


curl -X POST https://api.koduslegal.com/v1/analyze \
  -H "Authorization: Bearer tu_api_key" \
  -F "file=@contrato.pdf" \
  -F "analysis_type=complete" \
  -F "language=es"

Parámetros (multipart/form-data):

Parámetro	Tipo	Requerido	Descripción
`file`	file	✅	Documento a analizar (PDF, DOCX, TXT)
`analysis_type`	string	❌	`quick` o `complete` (default: `complete`)
`language`	string	❌	Idioma del análisis: `es` o `en` (default: `es`)

Response (200):


{
  "id": "analysis_789",
  "status": "completed",
  "document": {
    "filename": "contrato.pdf",
    "type": "contrato_compraventa",
    "pages": 12
  },
  "summary": "Contrato de compraventa de bien inmueble entre Juan Pérez (vendedor) e Inmobiliaria Los Robles S.A. (compradora) por ₡85,000,000. Incluye condición suspensiva por aprobación de crédito bancario.",
  "entities": [
    {
      "type": "persona_fisica",
      "name": "Juan Pérez Solano",
      "role": "vendedor",
      "id_number": "1-0987-0654"
    },
    {
      "type": "persona_juridica",
      "name": "Inmobiliaria Los Robles S.A.",
      "role": "compradora",
      "id_number": "3-101-789012"
    },
    {
      "type": "monto",
      "value": 85000000,
      "currency": "CRC",
      "description": "Precio de venta"
    }
  ],
  "risks": [
    {
      "level": "high",
      "clause": "Cláusula 8",
      "description": "No hay cláusula de resolución alternativa de conflictos",
      "recommendation": "Agregar cláusula arbitral o de mediación"
    },
    {
      "level": "medium",
      "clause": "Cláusula 3",
      "description": "Plazo de entrega sin penalidad por incumplimiento",
      "recommendation": "Definir penalidades por mora"
    }
  ],
  "legal_framework": [
    "Código Civil, artículos 1007-1140",
    "Ley de Arrendamientos Urbanos y Suburbanos (Ley 7527)"
  ]
}

SDKs y librerías

Próximamente ofreceremos SDKs oficiales para:

JavaScript/TypeScript (Node.js)
Python
C# (.NET)

Mientras tanto, podés usar cualquier cliente HTTP para interactuar con la API.

Soporte

¿Necesitás ayuda con la API?

📧 Email: api@koduslegal.com
📖 Ejemplos: github.com/kodus-legal/api-examples
💬 Chat: Usá el Chat Inteligente y preguntá por la API