Claves 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 API	Token del panel de control
`POST /api/v1/keys`	Crear una clave API	Token del panel de control
`DELETE /api/v1/keys/:id`	Eliminar claves API	Token del panel de control
`GET /api/v1/keys/:id`	Obtener una clave API por identificador	Token del panel de control
`PUT /api/v1/keys/:id`	Modificar una clave API	Token del panel de control

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

Acceso: token del panel de control

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 API

Acceso: token del panel de control

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 IP permitidas
`ip_blacklist`	`array`	no	; Lista de 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. Sustituye los valores y conserva solo los campos opcionales que necesites; los marcadores de cadena no se envían en lugar de números, boolean, objetos o arrays.

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 claves API

Acceso: token del panel de control

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 API por identificador

Acceso: token del panel de control

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 API

Acceso: token del panel de control

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	; IP permitidas: null no cambia la lista y un array vacío la borra; puede ser null
`ip_blacklist`	`array`	no	; IP bloqueadas: null no cambia la lista y un array vacío la borra; 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 de caducidad en formato ISO 8601; puede ser null
`reset_quota`	`boolean`	no	; Reiniciar la parte gastada 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 periodos; 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 con soporte