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/argument

Extract structured legal reasoning. This endpoint returns the core problema_juridico, the ratio_decidendi, and the exact decision_texto (what was ordered). It supports automatic query expansion to match Spanish accents.

Headers

Query parameters

curl "https://api.yellowtips.com/v1/legal/argument?q=pension&sentido=concede&limit=2" \
  -H "X-API-Key: yt_live_abc123..."

{
  "status": "success",
  "data": {
    "query": "pension",
    "fts_query": "pensi*",
    "filters": {
      "sentido": "concede",
      "derecho": null
    },
    "limit": 2,
    "count": 1,
    "plan": "pro",
    "results": [
      {
        "id": "T-334-24",
        "sentido": "concede",
        "derechos": "[\"discapacidad\",\"pension\",\"salud\"]",
        "problema_juridico": "en resolver si: Colpensiones vulneró los derechos...",
        "ratio_decidendi": "",
        "decision_texto": "Primero. REVOCAR la Sentencia proferida el 17 de enero...",
        "snippet_problema": "...la pensión de sobrevivientes...",
        "titulo": "Sentencia T-334/24 – Tutela",
        "fecha": "2024-08-12",
        "ponente": "Diana Constanza Fajardo Rivera",
        "fuente_url": "https://www.corteconstitucional.gov.co/relatoria/2024/T-334-24.htm"
      }
    ]
  }
}

GET /v1/legal/argument/hybrid

Hybrid search that combines BM25 lexical matching (SQLite FTS5) with vector semantic search (Cloudflare Vectorize + @cf/baai/bge-m3), fused via Reciprocal Rank Fusion (RRF, k=60). Best endpoint for natural-language queries like "me despidieron por estar enfermo".

Exact citations such as T-229/25 are auto-detected and resolved via direct primary-key lookup, bypassing the AI/Vectorize stack for sub-10ms latency.

Headers

Query parameters

curl "https://api.yellowtips.com/v1/legal/argument/hybrid?q=me%20despidieron%20por%20estar%20enfermo&limit=3" \
  -H "X-API-Key: yt_live_abc123..."

{
  "status": "success",
  "data": {
    "query": "me despidieron por estar enfermo",
    "fts_query": "me OR despidier* OR estar OR enfer*",
    "filters": { "sentido": null, "derecho": null },
    "limit": 3,
    "fusion": "rrf",
    "rrf_k": 60,
    "branches": {
      "lexical":  { "count": 30, "failed": false },
      "semantic": { "count": 30, "failed": false, "error": null }
    },
    "degraded": false,
    "count": 3,
    "plan": "pro",
    "results": [
      {
        "id": "T-225-26",
        "score": 0.0328,
        "branches": ["lexical", "semantic"],
        "sentido": "concede",
        "titulo": "Sentencia T-225/26 - Tutela",
        "fecha": "2026-04-15",
        "semantic_score": 0.523,
        "snippet_problema": "...me despidieron por enfermo..."
      }
    ]
  }
}

curl "https://api.yellowtips.com/v1/legal/argument/hybrid?q=T-229/25" \
  -H "X-API-Key: yt_live_abc123..."

{
  "status": "success",
  "data": {
    "query": "T-229/25",
    "query_type": "citation",
    "normalized_id": "T-229-25",
    "fusion": "citation_lookup",
    "branches": {
      "lexical":  { "count": 1, "failed": false },
      "semantic": { "count": 0, "failed": false, "skipped": true }
    },
    "degraded": false,
    "count": 1,
    "results": [
      {
        "id": "T-229-25",
        "score": 1.0,
        "branches": ["citation"],
        "titulo": "Sentencia T-229/25 - Tutela"
      }
    ]
  }
}

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. Aquí hay tres ejemplos reales que puedes correr contra el endpoint /v1/legal/search:

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.