Claves de API

Métodos, campos de las solicitudes y respuestas.

Guía completa

Esta sección contiene 5 métodos. Abre un método para consultar las condiciones de acceso, los campos de la solicitud y la respuesta.

Método y ruta	Descripción	Acceso
`GET /api/v1/keys`	Lista de claves de API	Token del panel
`POST /api/v1/keys`	Crear una clave de API	Token del panel
`DELETE /api/v1/keys/:id`	Eliminar una clave de API	Token del panel
`GET /api/v1/keys/:id`	Obtener una clave de API por identificador	Token del panel
`PUT /api/v1/keys/:id`	Modificar una clave de API	Token del panel

GET /api/v1/keys — Lista de claves de API

Acceso: token del panel

GET/api/v1/keys

Lectura; el ID se obtiene de tu respuesta anterior

curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

Parámetros de consulta

El campo	Tipo	Obligatorio	Validación / descripción
`sort_by`	`string`	no	; valor predeterminado: created_at
`sort_order`	`string`	no	; valor predeterminado: desc
`search`	`string`	no
`status`	`string`	no
`page`	`integer`	no	; valor predeterminado: 1; valor positivo; page_size/limit <=1000
`page_size`	`integer`	no	; valor predeterminado: 20; valor positivo; page_size/limit <=1000
`limit`	`integer`	no	; valor predeterminado: 20; valor positivo; page_size/limit <=1000

No se necesita cuerpo de solicitud. Envía los parámetros anteriores en la URL.

Respuesta

La respuesta JSON contiene code, message y data. El contenido de data se describe en los esquemas siguientes.

Esquemas de datos de la respuesta: APIKey. Los campos y los tipos se describen en las páginas «Esquemas de datos».

Esquema de respuesta con valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Notas: todos los datos personales y los objetos quedan limitados al sujeto del JWT.

Notas: la respuesta contiene el valor secreto key; no publiques valores reales.

POST /api/v1/keys — Crear una clave de API

Acceso: token del panel

POST/api/v1/keys

Campos JSON / formulario

El campo	Tipo	Obligatorio	Validación / descripción
`name`	`string`	sí	required
`custom_key`	`string`	no	; Valor de clave personalizado opcional; puede ser null
`ip_whitelist`	`array`	no	; Lista de direcciones IP permitidas
`ip_blacklist`	`array`	no	; Lista de direcciones IP bloqueadas
`quota`	`number`	no	; Límite de gasto de la clave en USD; puede ser null
`expires_in_days`	`integer`	no	; Vigencia en días; puede ser null
`rate_limit_5h`	`number`	no	; puede ser null
`rate_limit_1d`	`number`	no	; puede ser null
`rate_limit_7d`	`number`	no	; puede ser null

Plantilla del cuerpo de la solicitud

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

PLACEHOLDER representa tu entrada y su tipo. Reemplaza los valores y conserva solo los campos opcionales que necesites; los marcadores de cadena no se envían en lugar de números, valores booleanos, objetos o arreglos.

Esquema de la solicitud: CreateAPIKeyRequest

Respuesta

La respuesta JSON contiene code, message y data. El contenido de data se describe en los esquemas siguientes.

Esquemas de datos de la respuesta: APIKey. Los campos y los tipos se describen en las páginas «Esquemas de datos».

Esquema de respuesta con valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Notas: todos los datos personales y los objetos quedan limitados al sujeto del JWT.

Notas: la operación cambia el estado o continúa una autorización de un solo uso; el ejemplo describe el contrato y no se ejecuta.

Notas: se admite Idempotency-Key; repetir la solicitud devuelve la respuesta guardada con X-Idempotency-Replayed.

Notas: la respuesta contiene el valor secreto key; no publiques valores reales.

DELETE /api/v1/keys/:id — Eliminar una clave de API

Acceso: token del panel

DELETE/api/v1/keys/:id

Parámetros de ruta

El campo	Tipo	Obligatorio	Validación / descripción
`id`	`integer`	sí

No se necesita cuerpo de solicitud.

Respuesta

La respuesta JSON contiene code, message y data. El contenido de data se describe en los esquemas siguientes.

Esquema de respuesta con valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

Notas: todos los datos personales y los objetos quedan limitados al sujeto del JWT.

Notas: la operación cambia el estado o continúa una autorización de un solo uso; el ejemplo describe el contrato y no se ejecuta.

Notas: la respuesta contiene el valor secreto key; no publiques valores reales.

GET /api/v1/keys/:id — Obtener una clave de API por identificador

Acceso: token del panel

GET/api/v1/keys/:id

Lectura; el ID se obtiene de tu respuesta anterior

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

Parámetros de ruta

El campo	Tipo	Obligatorio	Validación / descripción
`id`	`integer`	sí

No se necesita cuerpo de solicitud. Envía los parámetros anteriores en la URL.

Respuesta

La respuesta JSON contiene code, message y data. El contenido de data se describe en los esquemas siguientes.

Esquemas de datos de la respuesta: APIKey. Los campos y los tipos se describen en las páginas «Esquemas de datos».

Esquema de respuesta con valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Notas: todos los datos personales y los objetos quedan limitados al sujeto del JWT.

Notas: la respuesta contiene el valor secreto key; no publiques valores reales.

PUT /api/v1/keys/:id — Modificar una clave de API

Acceso: token del panel

PUT/api/v1/keys/:id

Parámetros de ruta

El campo	Tipo	Obligatorio	Validación / descripción
`id`	`integer`	sí

Campos JSON / formulario

El campo	Tipo	Obligatorio	Validación / descripción
`name`	`string`	no
`status`	`string`	no	omitempty,oneof=active inactive
`ip_whitelist`	`array`	no	; Direcciones IP permitidas: null no modifica la lista; un arreglo vacío la vacía; puede ser null
`ip_blacklist`	`array`	no	; Direcciones IP bloqueadas: null no modifica la lista; un arreglo vacío la vacía; puede ser null
`quota`	`number`	no	; Límite de gasto de la clave en USD; 0 significa sin límite; puede ser null
`expires_at`	`string`	no	; Fecha y hora de vencimiento en formato ISO 8601; puede ser null
`reset_quota`	`boolean`	no	; Reiniciar el consumo acumulado del límite de gasto; puede ser null
`rate_limit_5h`	`number`	no	; puede ser null
`rate_limit_1d`	`number`	no	; puede ser null
`rate_limit_7d`	`number`	no	; puede ser null
`reset_rate_limit_usage`	`boolean`	no	; Reiniciar el gasto acumulado en los límites por ventanas de tiempo; puede ser null

Plantilla del cuerpo de la solicitud

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

Esquema de la solicitud: UpdateAPIKeyRequest

Respuesta

La respuesta JSON contiene code, message y data. El contenido de data se describe en los esquemas siguientes.

Esquemas de datos de la respuesta: APIKey. Los campos y los tipos se describen en las páginas «Esquemas de datos».

Esquema de respuesta con valores ilustrativos

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Notas: todos los datos personales y los objetos quedan limitados al sujeto del JWT.

Notas: la operación cambia el estado o continúa una autorización de un solo uso; el ejemplo describe el contrato y no se ejecuta.

Notas: la respuesta contiene el valor secreto key; no publiques valores reales.

Notas: mientras la clave tenga solicitudes pendientes con saldo reservado, no se puede reducir su límite de gasto ni reiniciar el gasto acumulado. Envía solo los campos que quieras cambiar.

¿Tienes alguna pregunta? Envíanos el Request ID y una descripción; te ayudaremos a resolverla.Contactar a soporte