Chiavi API

Metodi, campi delle richieste e risposte.

Guida completa

La sezione contiene 5 metodi. Apri un metodo per vedere condizioni di accesso, campi della richiesta e risposta.

Metodo e percorso	Descrizione	Accesso
`GET /api/v1/keys`	Elenco — chiavi API	Token dell’area personale
`POST /api/v1/keys`	Creazione di una chiave API	Token dell’area personale
`DELETE /api/v1/keys/:id`	Eliminazione — chiavi API	Token dell’area personale
`GET /api/v1/keys/:id`	Recupero per identificatore — chiavi API	Token dell’area personale
`PUT /api/v1/keys/:id`	Modifica di una chiave API	Token dell’area personale

GET /api/v1/keys — Elenco — chiavi API

Accesso: token dell’area personale

GET/api/v1/keys

Lettura; l’ID si ricava dalla risposta precedente che hai ricevuto

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

Parametri query

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`sort_by`	`string`	no	; predefinito: created_at
`sort_order`	`string`	no	; predefinito: desc
`search`	`string`	no
`status`	`string`	no
`page`	`integer`	no	; predefinito: 1; positivo; page_size/limit <=1000
`page_size`	`integer`	no	; predefinito: 20; positivo; page_size/limit <=1000
`limit`	`integer`	no	; predefinito: 20; positivo; page_size/limit <=1000

Il corpo della richiesta non è necessario. Passa i parametri indicati sopra nell’URL.

Risposta

La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto.

Schemi dei dati della risposta: APIKey. Campi e tipi sono nelle pagine «Schemi dei dati».

Schema della risposta, valori illustrativi

{
  "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)"
  }
}

Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT.

Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali.

POST /api/v1/keys — Creazione di una chiave API

Accesso: token dell’area personale

POST/api/v1/keys

Campi JSON / modulo

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`name`	`string`	sì	required
`custom_key`	`string`	no	; Valore personalizzato facoltativo della chiave; può essere null
`ip_whitelist`	`array`	no	; Elenco degli IP consentiti
`ip_blacklist`	`array`	no	; Elenco degli IP bloccati
`quota`	`number`	no	; Limite di spesa della chiave in USD; può essere null
`expires_in_days`	`integer`	no	; Durata di validità in giorni; può essere null
`rate_limit_5h`	`number`	no	; può essere null
`rate_limit_1d`	`number`	no	; può essere null
`rate_limit_7d`	`number`	no	; può essere null

Modello del corpo della richiesta

{
  "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 indica il tuo input e il suo tipo. Sostituisci i valori e mantieni solo i campi facoltativi necessari; i segnaposto stringa non vanno inviati al posto di numeri, boolean, oggetti o array.

Schema della richiesta: CreateAPIKeyRequest

Risposta

La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto.

Schemi dei dati della risposta: APIKey. Campi e tipi sono nelle pagine «Schemi dei dati».

Schema della risposta, valori illustrativi

{
  "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)"
  }
}

Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT.

Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito.

Particolarità: Idempotency-Key è supportato; un invio ripetuto restituisce la risposta salvata con X-Idempotency-Replayed.

Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali.

DELETE /api/v1/keys/:id — Eliminazione — chiavi API

Accesso: token dell’area personale

DELETE/api/v1/keys/:id

Parametri del percorso

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`id`	`integer`	sì

Il corpo della richiesta non è necessario.

Risposta

La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto.

Schema della risposta, valori illustrativi

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

Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT.

Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito.

Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali.

GET /api/v1/keys/:id — Recupero per identificatore — chiavi API

Accesso: token dell’area personale

GET/api/v1/keys/:id

Lettura; l’ID si ricava dalla risposta precedente che hai ricevuto

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

Parametri del percorso

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`id`	`integer`	sì

Il corpo della richiesta non è necessario. Passa i parametri indicati sopra nell’URL.

Risposta

La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto.

Schemi dei dati della risposta: APIKey. Campi e tipi sono nelle pagine «Schemi dei dati».

Schema della risposta, valori illustrativi

{
  "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)"
  }
}

Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT.

Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali.

PUT /api/v1/keys/:id — Modifica di una chiave API

Accesso: token dell’area personale

PUT/api/v1/keys/:id

Parametri del percorso

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`id`	`integer`	sì

Campi JSON / modulo

Il campo	Tipo	Obbligatorio	Verifica / descrizione
`name`	`string`	no
`status`	`string`	no	omitempty,oneof=active inactive
`ip_whitelist`	`array`	no	; IP consentiti: null non modifica l’elenco, un array vuoto lo cancella; può essere null
`ip_blacklist`	`array`	no	; IP bloccati: null non modifica l’elenco, un array vuoto lo cancella; può essere null
`quota`	`number`	no	; Limite di spesa della chiave in USD; 0 — senza limite; può essere null
`expires_at`	`string`	no	; Data e ora di scadenza nel formato ISO 8601; può essere null
`reset_quota`	`boolean`	no	; Azzera la quota consumata del limite di spesa; può essere null
`rate_limit_5h`	`number`	no	; può essere null
`rate_limit_1d`	`number`	no	; può essere null
`rate_limit_7d`	`number`	no	; può essere null
`reset_rate_limit_usage`	`boolean`	no	; Azzera la spesa conteggiata nelle finestre; può essere null

Modello del corpo della richiesta

{
  "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)"
}

PLACEHOLDER indica il tuo input e il suo tipo. Sostituisci i valori e mantieni solo i campi facoltativi necessari; i segnaposto stringa non vanno inviati al posto di numeri, boolean, oggetti o array.

Schema della richiesta: UpdateAPIKeyRequest

Risposta

La risposta JSON contiene code, message e data. Il contenuto di data è descritto negli schemi sotto.

Schemi dei dati della risposta: APIKey. Campi e tipi sono nelle pagine «Schemi dei dati».

Schema della risposta, valori illustrativi

{
  "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)"
  }
}

Particolarità: Tutti i dati personali e gli oggetti sono limitati al soggetto JWT.

Particolarità: L’operazione modifica lo stato o prosegue un’autorizzazione monouso; l’esempio descrive il contratto e non viene eseguito.

Particolarità: La risposta contiene il valore segreto key; non pubblicare valori reali.

Particolarità: Finché la chiave ha richieste non concluse con una riserva, non è consentito ridurre il suo limite di spesa né azzerarne il consumo registrato. Trasmetti solo i campi che modifichi.

Hai altre domande? Invia il Request ID e una descrizione — ti aiuteremo a chiarire il problema.Contatta l’assistenza