Pipeline de API: dar herramientas a tu oráculo

Índice: Pipelines de API — índice

Objetivo: dar herramientas a tu oráculo: describir tus propios endpoints HTTP como tarjetas y guardar como secretos las claves que necesitan, y luego conectar ambos a la agenda del oráculo.

Una tarjeta de endpoint de API es una llamada HTTP que el oráculo puede hacer; su operation_id es el nombre de la herramienta y su request_schema los argumentos. Un secreto guarda una clave; los endpoints lo referencian por nombre y el valor solo se rellena en el momento de la llamada.

Pasos

1. Guarda la clave.

POST /v0/my/secrets
Idempotency-Key: sec-0a9d…
{"key_name": "secret_shop_api_token", "value": "sk-example-123", "host": "api.example.com",
 "title": "Shop API token", "workspaces": ["470000000000000400"]}
→ {"nonce": "470000000000000410", "key_name": "secret_shop_api_token", "host": "api.example.com",
   "title": "Shop API token", "created_at": "…", …}

• key_name: secret_ + [a-z0-9_], de 8 a 64 caracteres; la convención es secret_<name>_<role>.
• value es de solo escritura: ninguna llamada lo devuelve. Para cambiarlo, elimina el secreto y crea otro.
• host: el valor solo se envía a este host. Indícalo siempre.
• workspaces (obligatorio, al menos uno tuyo): dónde se archiva el secreto.

2. Describe el endpoint.

POST /v0/my/api_endpoints
Idempotency-Key: ep-77b3…
{"title": "Check order status", "content": "Returns the status of one order. Use when a customer asks where their order is.",
 "operation_id": "orders_status", "method": "GET",
 "path": "https://api.example.com/v1/orders/{id}",
 "request_schema": {"type": "object", "properties": {"id": {"type": "string"}}, "required": ["id"]}}
→ {"nonce": "470000000000000420", "card_type": "api_endpoint", …}

• Obligatorios: title, operation_id, method, path. method se pasa a mayúsculas (GET, POST, PATCH, PUT, DELETE).
• path: una URL completa, o una ruta que empieza por / más domain (el host al que va).
• Referencia un secreto donde el servicio espera su clave como {{secret_<key name>}}, o por rol como {{secret_*_<role>}} (debe haber exactamente un secreto conectado con ese rol). No se pueden mezclar en un endpoint secretos ligados a hosts distintos.
• content le dice al oráculo cuándo usarlo; response_schema es opcional.

3. Conéctalo a la agenda. PATCH /v0/my/agendas/{agenda} {"api_endpoints": ["470000000000000420"], "secrets": ["470000000000000410"]} — cada lista reemplaza la anterior. Pipeline de API: escribir una agenda para tus oráculos

4. Gestionar.

• Endpoints: PATCH /v0/my/api_endpoints/{nonce} (cualquier campo de arriba, handle, visibilidad), DELETE …, GET /v0/my/api_endpoints, los públicos con GET /v0/graph/api_endpoints (+ /{nonce}).
• Secretos: GET /v0/my/secrets (nombres y hosts, nunca valores), PATCH /v0/my/secrets/{nonce} (title, content, host, visibilidad), DELETE /v0/my/secrets/{nonce}.

En segundo plano

• El valor del secreto se descifra solo cuando el oráculo llama al endpoint, y va solo al host del secreto.
• Quien tenga write sobre un endpoint puede editar su texto, pero no cambiar a dónde envía ni añadir referencias a secretos; solo el dueño puede cambiar domain, host, la visibilidad o los derechos.

Reglas

• 400: title is required; operation_id, method and path are required; value is required; a secret must be placed into a workspace; nombre de clave: must start with secret_, length must be 8..=64, only [a-z0-9_] allowed.
• 403: only the card owner can change where the endpoint sends; only the card owner can add secret references: …; campos del dueño cambiados por alguien con acceso concedido.
• En el momento de la llamada, un rol de secreto ausente o ambiguo, o secretos ligados a hosts distintos, detienen la llamada.

Superficie de la API