Saltar al contenido
Referencia de API
Referencia de API

Crear un guardarraíl

Cree un modelo, proveedor y política de presupuesto reutilizables.

Ver Markdown

Cree un modelo, proveedor y política de presupuesto reutilizables.

Endpoint

POST /api/v1/guardrails
URL base
https://runapi.ai
Versión de la API
v1
Autenticación
Authorization: Bearer YOUR_MANAGEMENT_API_KEY
Autorización
Requiere una Clave de API de administración con rol de administrador de cuenta.
02

Solicitud

Cuerpo JSON

Envíe valores únicamente en la ubicación de solicitud indicada.

Cuerpo JSON12 campos
alert_threshold_percentinteger
Opcional

Porcentaje del umbral de alerta del presupuesto.

Valor predeterminado: 80 Rango: 1 - 100
allowed_modelsarray | null
Opcional

Lista de permitidos del modelo.

allowed_providersarray | null
Opcional

Lista de proveedores permitidos.

blocked_modelsarray | null
Opcional

Lista de bloqueados del modelo, que tiene precedencia sobre la lista de permitidos.

blocked_providersarray | null
Opcional

Lista de proveedores bloqueados.

credit_limit_behaviorstring
Opcional

Modo de aplicación del presupuesto. Las asignaciones por etiqueta requieren block.

Valores permitidos: block, alert_only Valor predeterminado: block
credit_limit_centsinteger | null
Opcional

Límite de gasto total en centavos de USD.

credit_limit_reset_intervalstring | null
Opcional

Periodicidad del límite total. Null significa vitalicio cuando hay un importe.

Valores permitidos: daily, weekly, monthly
descriptionstring
Opcional

Descripción libre opcional.

enabledboolean
Opcional

Si la barrera de protección está activada.

Valor predeterminado: true
model_budgetsarray | null
Opcional

Reglas de presupuesto por modelo.

namestring
Obligatorio

Nombre de Guardrail único dentro de la cuenta.

03

Respuesta de éxito

HTTP 201

POST /api/v1/guardrails

JSON 
{
  "alert_threshold_percent": 80,
  "allowed_models": [
    "gpt-5.4"
  ],
  "allowed_providers": [],
  "assignment_count": 1,
  "blocked_models": [],
  "blocked_providers": [],
  "created_at": "2026-07-27T10:00:00.000Z",
  "credit_limit_behavior": "block",
  "credit_limit_cents": 50000,
  "credit_limit_reset_interval": "monthly",
  "description": "Production policy",
  "enabled": true,
  "id": "guardrail_123",
  "model_budgets": [
    {
      "credit_limit_cents": 10000,
      "credit_limit_reset_interval": "monthly",
      "match_mode": "include",
      "models": [
        "gpt-5.4"
      ]
    }
  ],
  "name": "Production budget"
}
04

Respuesta de error (401)

HTTP 401
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Authentication required"
}
05

Respuesta de error (403)

HTTP 403
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Management API key required"
}
06

Respuesta de error (403)

HTTP 403
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Mensaje de error legible por personas.",
      "type": "string"
    }
  },
  "required": [
    "error"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Account admin required"
}
07

Respuesta de error (400)

HTTP 400
Esquema de respuesta
JSON 
{
  "oneOf": [
    {
      "properties": {
        "error": {
          "description": "Mensaje de error legible por personas.",
          "type": "string"
        }
      },
      "required": [
        "error"
      ],
      "type": "object",
      "unevaluatedProperties": false
    },
    {
      "properties": {
        "error": {
          "description": "Resumen de validación legible por personas.",
          "type": "string"
        },
        "errors": {
          "additionalProperties": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
          "type": "object"
        }
      },
      "required": [
        "error",
        "errors"
      ],
      "type": "object",
      "unevaluatedProperties": false
    }
  ]
}

Ejemplo de respuesta

JSON 
{
  "error": "page must be an integer"
}
08

Respuesta de error (422)

HTTP 422
Esquema de respuesta
JSON 
{
  "properties": {
    "error": {
      "description": "Resumen de validación legible por personas.",
      "type": "string"
    },
    "errors": {
      "additionalProperties": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "description": "Mensajes de validación con clave por campo de solicitud público, con un array de cadenas legibles por personas para cada campo.",
      "type": "object"
    }
  },
  "required": [
    "error",
    "errors"
  ],
  "type": "object",
  "unevaluatedProperties": false
}

Ejemplo de respuesta

JSON 
{
  "error": "Validation failed",
  "errors": {
    "base": [
      "Validation failed"
    ]
  }
}
09

Ejemplo de cURL

CURL 
curl -X POST https://runapi.ai/api/v1/guardrails \
  -H 'Authorization: Bearer YOUR_MANAGEMENT_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production budget","description":"Production policy","enabled":true,"credit_limit_cents":50000,"credit_limit_reset_interval":"monthly","credit_limit_behavior":"block","alert_threshold_percent":80,"allowed_models":["gpt-5.4"],"model_budgets":[{"match_mode":"include","models":["gpt-5.4"],"credit_limit_cents":10000,"credit_limit_reset_interval":"monthly"}]}'