API Documentation

Context APIs for AI agents in LATAM & Spain. This guide covers authentication, endpoints, and error handling.

Quick start

Make your first request in 30 seconds.

curl https://api.yellowtips.com/health

You should see:

{"status":"success","data":{"service":"yellowtips-api","version":"0.3.0"}}

Authentication

All endpoints under /v1/* require an API key in the X-API-Key header.

X-API-Key: yt_live_abc123...

GET /health

Returns the service status. No authentication required.

{
  "status": "success",
  "data": {
    "service": "yellowtips-api",
    "version": "0.3.0"
  }
}

POST /v1/legal/verify-citation

Verifies a legal citation in three layers: existence, relevance and temporality (dead law detection).

Headers

Request body

curl -X POST https://api.yellowtips.com/v1/legal/verify-citation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: yt_live_abc123..." \
  -d '{
    "citation": "Sentencia C-1234 de 2014",
    "jurisdiction": "CO",
    "proposition": "derecho de retracto"
  }'

{
  "status": "success",
  "data": {
    "citation": "Sentencia C-1234 de 2014",
    "jurisdiction": "CO",
    "citation_id": "C-1234-2014",
    "citation_text": "Sentencia C-1234 de 2014",
    "court": "Corte Constitucional",
    "year": 2014,
    "existence_check": "confirmed",
    "relevance_check": "unverified",
    "temporality_check": "dead_law",
    "superseded_by": "C-567-2019",
    "overall_confidence": "low",
    "note": "Derogada por Sentencia C-567 de 2019",
    "plan": "free",
    "timestamp": "2026-10-23T18:34:37.858Z"
  }
}

{
  "status": "success",
  "data": {
    "citation": "Sentencia C-567 de 2019",
    "citation_id": "C-567-2019",
    "existence_check": "confirmed",
    "relevance_check": "likely_relevant",
    "temporality_check": "valid",
    "overall_confidence": "high",
    "note": "Vigente. Reemplaza a C-1234 de 2014"
  }
}

{
  "status": "partial",
  "data": {
    "citation": "Sentencia X-9999 de 2020",
    "existence_check": "not_found",
    "temporality_check": "unknown",
    "overall_confidence": "low",
    "error": {
      "code": "E_CITATION_NOT_FOUND",
      "message": "Citation not found in our database..."
    }
  }
}

GET /v1/legal/search

Full-text search across our jurisprudence database with BM25 relevance ranking, powered by SQLite FTS5. Results include a snippet with matching terms wrapped in <mark> tags — ready to render.

Headers

Query parameters

curl "https://api.yellowtips.com/v1/legal/search?q=despido%20sin%20justa%20causa&limit=3" \
  -H "X-API-Key: yt_live_abc123..."

{
  "status": "success",
  "data": {
    "query": "despido sin justa causa",
    "fts_query": "\"despido sin justa causa\"",
    "tipo": null,
    "limit": 3,
    "count": 3,
    "plan": "pro",
    "results": [
      {
        "id": "T-123-26",
        "titulo": "Sentencia T-123/26 – Tutela",
        "fecha": "2026-05-07",
        "ponente": "Lina Marcela Escobar Martínez",
        "tipo": "T",
        "tipo_proceso": "Tutela",
        "fuente_url": "https://www.corteconstitucional.gov.co/relatoria/2026/T-123-26.htm",
        "snippet": "...despido sin justa causa...",
        "rank": -4.115677207344352
      }
    ],
    "timestamp": "2026-10-24T15:44:26.100Z"
  }
}

Rendering snippets

The snippet field contains <mark> tags around matching terms. Render it as HTML to highlight results:

<p dangerouslySetInnerHTML={{ __html: result.snippet }} />
// → "...despido sin justa causa..."

Relevance ranking

Results are ordered by rank (BM25 score). More negative = more relevant. Use it only to sort results within a single query — do not compare rank values across queries.

Casos de uso: Derecho Laboral

El corpus está especialmente denso en temas laborales. Estas son las coberturas reales sobre las 1.308 tutelas de la Corte Constitucional indexadas (2023–2026):

Ejemplo: estabilidad laboral reforzada

curl "https://api.yellowtips.com/v1/legal/search?q=estabilidad%20laboral%20reforzada&limit=3" \
  -H "X-API-Key: yt_live_abc123..."

{
  "status": "success",
  "data": {
    "query": "estabilidad laboral reforzada",
    "fts_query": "\"estabilidad laboral reforzada\"",
    "count": 3,
    "results": [
      {
        "id": "T-XXX-25",
        "titulo": "Sentencia T-XXX/25 – Tutela",
        "fecha": "2025-XX-XX",
        "ponente": "...",
        "tipo": "T",
        "snippet": "...estabilidad laboral reforzada...",
        "fuente_url": "https://www.corteconstitucional.gov.co/relatoria/2025/T-XXX-25.htm"
      }
    ]
  }
}

Ejemplo: despido de mujer embarazada

curl "https://api.yellowtips.com/v1/legal/search?q=despido%20mujer%20embarazada&limit=3" \
  -H "X-API-Key: yt_live_abc123..."

Ejemplo: fuero sindical

curl "https://api.yellowtips.com/v1/legal/search?q=fuero%20sindical&limit=3" \
  -H "X-API-Key: yt_live_abc123..."

Error codes

Jurisdictions

Yellow Tips is Colombia-first. The current corpus covers rulings from the Colombian Constitutional Court (Corte Constitucional) only.