API para desarrolladores y agentes

Qué soporta hoy

Catálogo completo de endpoints

Las rutas se muestran con el prefijo completo. Los endpoints de socio aceptan `Authorization: Bearer rvk_...` o `x-api-key`.

Contrato rápido para agentes

Si tu agente no conoce el dominio, empieza por el manifest. Si conoce la API, empieza por discovery y luego OpenAPI. Usa public-intake con clave para formas desconocidas; usa `/persons` y `/entities` solo cuando tienes un registro canónico con link-back.

{
  "eventId": "venezuela-earthquakes-2026",
  "apiBaseUrl": "https://respuestave.org/api/v1",
  "manifest": "https://respuestave.org/federation.instance.json",
  "discovery": "https://respuestave.org/api/v1",
  "openapi": "https://respuestave.org/api/v1/openapi",
  "publicRoutes": [
    "GET /api/v1",
    "GET /api/v1/openapi",
    "GET /federation.instance.json",
    "GET /api/v1/badge?domain=",
    "GET /api/v1/public-intake"
  ],
  "keyManagement": "/desarrolladores/claves",
  "partnerAuth": [
    "Authorization: Bearer $RVK_API_KEY",
    "x-api-key: $RVK_API_KEY"
  ],
  "scopes": {
    "score": [
      "POST /api/v1/score"
    ],
    "match": [
      "POST /api/v1/match"
    ],
    "search": [
      "GET /api/v1/persons",
      "GET /api/v1/persons/status",
      "GET /api/v1/persons/changes",
      "GET /api/v1/entities",
      "GET /api/v1/entities/changes"
    ],
    "ingest": [
      "POST /api/v1/persons",
      "POST /api/v1/entities",
      "POST /api/v1/public-intake",
      "GET /api/v1/public-intake?id="
    ]
  },
  "syncRules": [
    "Treat matches as advisory; never auto-merge people.",
    "Use sourceUpdatedAt when changing person/entity status so stale source data cannot overwrite newer data.",
    "Use nextSince from changes responses as the next cursor.",
    "Send unknown/raw shapes to public-intake for operator review before canonical promotion."
  ],
  "privacyRules": [
    "cedula and photoPhash are match-only and never returned",
    "public responses use redacted records and fuzzed coordinates",
    "public-intake receipts never echo raw payloads or private contacts"
  ]
}

Ejemplos copiables

curl -s https://respuestave.org/api/v1/match \
  -H "Authorization: Bearer $RVK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "record": {
      "name": "Ana Diaz",
      "age": 31,
      "estado": "Lara",
      "municipio": "Barquisimeto"
    },
    "limit": 10
  }'

curl -s https://respuestave.org/api/v1/entities \
  -H "Authorization: Bearer $RVK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "hospital-central-123",
    "sourceUrl": "https://partner.example/hospital-central-123",
    "entity": {
      "kind": "hospital",
      "name": "Hospital Central",
      "estado": "Lara",
      "municipio": "Barquisimeto",
      "audienceScope": "in_venezuela",
      "countryCode": "VE",
      "channels": [
        {"type": "website", "url": "https://partner.example/hospital-central-123", "isPrimary": true}
      ],
      "needs": [
        {"category": "medical_supplies", "title": "Gasas y solucion salina", "urgency": "high"}
      ]
    }
  }'

curl -s https://respuestave.org/api/v1/public-intake \
  -H "Authorization: Bearer $RVK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "venezuela-earthquakes-2026",
    "source": "volunteer-discord",
    "sourceRecordId": "discord:message:123",
    "contentFingerprint": "sha256:...",
    "kind": "mixed",
    "processingHints": {
      "dedupeMode": "candidate_review_not_auto_merge",
      "promotionPath": "/api/v1/entities"
    },
    "data": "Hospital Central solicita agua y gasas. https://example.org/post/123"
  }'

curl -s "https://respuestave.org/api/v1/persons/changes?since=2026-06-26T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $RVK_API_KEY"

MCP para agentes

El servidor MCP incluido en este repo envuelve los flujos con clave de socio y la verificación de insignia. Para public-intake, llama la API HTTP con la misma clave de socio.

Herramientas MCP disponibles

{
  "mcpServers": {
    "respuesta-ve-federation": {
      "command": "node",
      "args": ["/absolute/path/to/respuesta-ve/mcp-server/index.mjs"],
      "env": {
        "RVK_API_KEY": "rvk_your_partner_key",
        "RVK_API_BASE": "https://respuestave.org/api/v1"
      }
    }
  }
}