Referencia de API
Decisiones HTTP, auth, contratos de respuesta y ejemplos TypeScript para Choice, Score y yes-no.
La API System One expone decisiones estructuradas por HTTP: opciones elegidas (Choice), puntuaciones sobre una rúbrica ordenada (Score) y probabilidad de sí o no (Noul). El contrato público vive en el documento OpenAPI de https://system-one.dev/openapi.json; esta página resume autenticación, puntos de conexión, cuerpos de petición y respuesta. Si integras desde TypeScript, el SDK es una vía equivalente con adaptadores y credenciales propias.
Preguntas frecuentes
¿Qué es la API System One?
La API de decisiones alojada para Choice, Score y Noul (yes-no). Autentícate con una clave de API y recibe decisiones tipadas para tus agentes.
¿Errores, idempotencia y versionado?
Consulta las páginas hijas bajo /docs/api/.
Autenticación
| Ajuste | Valor |
|---|---|
| URL base | https://system-one.dev/v1 |
| Extremo de decisión y extracción | POST https://system-one.dev/v1/systemone |
| Autenticación | Authorization: Bearer $SYSTEM_ONE_API_KEY |
| Formato de la petición | Content-Type: application/json |
| Modelo | Copia el identificador exacto (name) del catálogo de modelos actual. |
Crea una clave de API en la consola de System One. Las claves de plataforma que emite la consola llevan el prefijo so_live_. Guárdala en el campo de secretos de tu herramienta o en tu servidor, nunca en código de navegador, documentos compartidos ni capturas. Las peticiones consumen los créditos de tu cuenta.
El origen de la API es la aplicación principal, no el host de documentación. POST /v1/systemone exige una clave Bearer de System One; GET /v1/models es público e ignora cualquier Bearer del llamador. Una clave de un proveedor directo no es una clave de cuenta de System One.
POST /v1/systemone
Authorization: Bearer $SYSTEM_ONE_API_KEY
Content-Type: application/jsonPuntos de conexión
| Extremo | Autenticación | Cuota | Uso |
|---|---|---|---|
GET /v1/models | Pública | Cuota propia de 60 peticiones por IP hasheada por minuto | Catálogo actual { models: [...] } con detalles del modelo. No consume créditos de decisión. |
POST /v1/systemone | Clave Bearer de plataforma | Cuota de cuenta compartida de 120/minuto por defecto | Decisiones (questions) y extracción (fields). |
OPTIONS | Sin autenticar | — | Preflight CORS sobre ambos extremos, con estado 204. |
El preflight devuelve Access-Control-Allow-Origin: *, métodos permitidos GET, POST, OPTIONS y cabeceras permitidas Authorization, Content-Type, Idempotency-Key. Es autenticación Bearer, no autenticación por cookie entre orígenes: Access-Control-Allow-Credentials no está habilitado, así que una clave de cuenta de larga duración no debe incrustarse en código público del navegador.
El catálogo de modelos puede cambiar: copia el name exacto de GET /v1/models y mantén la selección abierta a entradas nuevas en lugar de incrustar un catálogo permanente. El documento OpenAPI es el contrato autoritativo; no documentes operaciones que no aparezcan allí.
Cuerpo de la petición
Reemplaza YOUR_MODEL_ID y guarda este cuerpo como request.json:
{
"model": "YOUR_MODEL_ID",
"state": { "message": "I was charged twice for one order." },
"questions": {
"team": {
"type": "choice",
"instructions": "Choose the reviewing team.",
"criteria": { "billing": "Payments and refunds", "support": "Technical help" }
},
"urgency": {
"type": "score",
"instructions": "Evaluate urgency with the ordered rubric.",
"criteria": ["Normal review", "Timely response", "Immediate human attention"]
},
"duplicate": {
"type": "noul",
"instructions": "Does the message report a duplicate charge?"
}
}
}Envíalo con tu clave y una clave de operación única, por ejemplo un UUID:
curl --include 'https://system-one.dev/v1/systemone' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_OPERATION_KEY' \
--data-binary @request.json| Campo | Qué enviar |
|---|---|
model | El name de la entrada elegida, una cadena no vacía de 128 caracteres como máximo. Envíalo siempre de forma explícita. |
state | Contexto compartido obligatorio: cadena, objeto JSON o array. "" está permitido. Un array es un contexto compartido, no un lote de peticiones. |
questions | Un objeto con 1–32 preguntas con nombre. |
questions.*.type | choice, score o noul. El tipo HTTP de una probabilidad de sí o no es noul, no boolean. |
questions.*.instructions | Explicación no vacía de la pregunta; algunos modelos la exigen. |
criteria de Choice | Objeto que mapea nombres de opción a descripciones. Máximo 255 opciones. |
criteria de Score | Array ordenado de 2–10 descripciones, empezando en el índice cero. |
criteria de Noul | Objeto opcional con claves true y/o false. |
Límites de servicio: cuerpo UTF-8 JSON de 65,536 bytes para modelos solo de texto y 13,631,488 bytes para modelos con imagen; respuesta de 1,048,576 bytes como máximo; 32 preguntas por petición; 1–255 opciones de Choice; 2–10 niveles de Score; longitud máxima de nombre y de modelo de 128 caracteres; profundidad JSON de 32; 20 claves activas; plazo compartido de 20 s.
Cuerpo de la respuesta
Este ejemplo ilustra las formas de respuesta, no una salida registrada. ACTUAL_MODEL_ID representa el nombre de modelo devuelto por el servicio:
{
"model": "ACTUAL_MODEL_ID",
"answers": {
"team": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.8, "support": 0.2 },
"confidence": 0.6
},
"urgency": {
"type": "score",
"score": 1.5,
"probabilities": { "0": 0.1, "1": 0.3, "2": 0.6 },
"confidence": 0.3,
"legend": { "0": "Normal review", "1": "Timely response", "2": "Immediate human attention" }
},
"duplicate": { "type": "noul", "noul": 0.8 }
},
"usage": { "input_tokens": 120, "output_tokens": 0 }
}Los nombres de las respuestas coinciden con los nombres de tus preguntas. Choice devuelve un nombre de opción; Score puede ser fraccional; noul es la probabilidad de verdadero, entre 0 y 1. La confianza es una estadística propia del modelo, no necesariamente la probabilidad de la opción elegida.
La facturación de plataforma no va en el cuerpo: se comunica en las cabeceras X-Request-Id, X-System-One-Credits, X-Idempotency-Replayed y X-RateLimit-*. Un usage ausente o con conteos nulos significa desconocido, no cero.
SDK
El SDK de System One es una vía de integración de primer nivel, con adaptadores y credenciales propias. El núcleo del SDK normaliza Noul como { type: 'boolean', probability } y el uso de tokens en camelCase, y no devuelve todos los campos crudos; para acceso HTTP completo usa Fetch o withResponse() del cliente oficial. El requestId del cliente oficial se refiere al seguimiento de TypeSafe: lee X-Request-Id explícitamente para el identificador de petición de System One.
Para una aplicación TypeScript, empieza por el inicio rápido del SDK alojado. Las preguntas de idempotencia y reintento están en Idempotencia y reintentos, y los códigos de error en Códigos de error API.
Para ver el saldo y la actividad de tu cuenta, abre la consola de System One. Para las reglas de versionado, consulta Versionado de API; para los tipos de decisión, Primitivas de decisión; y para el consumo de créditos, Facturación y créditos.