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
curl https://api.yellowtips.com/health

You should see:

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

Authentication

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

X-API-Key: yt_live_abc123...
Don't have a key? Request one at yellowtips.com — the Free plan includes 100 calls/month without a credit card.

GET /health

Returns the service status. No authentication required.

GET /health
Response
{
  "status": "success",
  "data": {
    "service": "yellowtips-api",
    "version": "0.2.0"
  }
}

POST /v1/legal/verify-citation

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

POST /v1/legal/verify-citation

Headers

Header Required Value
X-API-Key Yes Your API key (starts with yt_live_)
Content-Type Yes application/json

Request body

Field Type Required Description
citation string Yes The citation to verify (e.g. "Sentencia C-567 de 2019")
jurisdiction string Yes One of: MX, CO, AR, CL, PE, ES
proposition string No The legal proposition the citation is supposed to support
Example request
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"
  }'
Success response — dead law detected
{
  "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"
  }
}
Success response — valid citation
{
  "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"
  }
}
Partial response — citation not in database
{
  "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..."
    }
  }
}
Note: a not_found result does not mean the citation doesn't exist — it means our coverage is limited. We never fabricate a "valid" response when we can't verify.

Error codes

Code HTTP Meaning
E400 400 Missing or invalid request fields
E401 401 Invalid or missing API key
E404 404 Endpoint not found
E500 400 Invalid JSON body
E_CITATION_NOT_FOUND 200 (partial) Citation not found in our database

Jurisdictions

Currently supported:

More LATAM countries coming soon.