Chaves de API

Métodos, campos dos pedidos e respostas.

Guia completo

Esta secção contém 5 métodos. Abra o método para consultar as condições de acesso, os campos do pedido e a resposta.

Método e caminho	Descrição	Acesso
`GET /api/v1/keys`	Lista — chaves de API	Token da área pessoal
`POST /api/v1/keys`	Criação de uma chave de API	Token da área pessoal
`DELETE /api/v1/keys/:id`	Eliminação — chaves de API	Token da área pessoal
`GET /api/v1/keys/:id`	Obtenção por identificador — chaves de API	Token da área pessoal
`PUT /api/v1/keys/:id`	Alteração de uma chave de API	Token da área pessoal

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

Acesso: token da área pessoal

GET/api/v1/keys

Leitura; o ID é obtido da sua resposta anterior

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

Parâmetros de consulta

O campo	Tipo	Obrigatório	Validação / descrição
`sort_by`	`string`	não	; por predefinição: created_at
`sort_order`	`string`	não	; por predefinição: desc
`search`	`string`	não
`status`	`string`	não
`page`	`integer`	não	; por predefinição: 1; positive; page_size/limit <=1000
`page_size`	`integer`	não	; por predefinição: 20; positive; page_size/limit <=1000
`limit`	`integer`	não	; por predefinição: 20; positive; page_size/limit <=1000

Não é necessário corpo do pedido. Transmita os parâmetros indicados acima no URL.

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: APIKey. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com 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)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a resposta contém o valor secreto key; não publique valores reais.

POST /api/v1/keys — Criação de uma chave de API

Acesso: token da área pessoal

POST/api/v1/keys

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`name`	`string`	sim	required
`custom_key`	`string`	não	; Valor personalizado opcional da chave; pode ser null
`ip_whitelist`	`array`	não	; Lista de IP permitidos
`ip_blacklist`	`array`	não	; Lista de IP bloqueados
`quota`	`number`	não	; Limite de despesas da chave em USD; pode ser null
`expires_in_days`	`integer`	não	; Prazo de validade em dias; pode ser null
`rate_limit_5h`	`number`	não	; pode ser null
`rate_limit_1d`	`number`	não	; pode ser null
`rate_limit_7d`	`number`	não	; pode ser null

Modelo do corpo do pedido

{
  "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 os seus dados de entrada e o respetivo tipo. Substitua os valores e mantenha apenas os campos opcionais necessários; não envie marcadores de texto no lugar de números, booleanos, objetos ou arrays.

Esquema do pedido: CreateAPIKeyRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: APIKey. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com 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)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

Particularidades: Idempotency-Key é suportado; a repetição devolve a resposta guardada com X-Idempotency-Replayed.

Particularidades: a resposta contém o valor secreto key; não publique valores reais.

DELETE /api/v1/keys/:id — Eliminação — chaves de API

Acesso: token da área pessoal

DELETE/api/v1/keys/:id

Parâmetros do caminho

O campo	Tipo	Obrigatório	Validação / descrição
`id`	`integer`	sim

Não é necessário corpo do pedido.

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquema da resposta, com valores ilustrativos

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

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

Particularidades: a resposta contém o valor secreto key; não publique valores reais.

GET /api/v1/keys/:id — Obtenção por identificador — chaves de API

Acesso: token da área pessoal

GET/api/v1/keys/:id

Leitura; o ID é obtido da sua resposta anterior

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

Parâmetros do caminho

O campo	Tipo	Obrigatório	Validação / descrição
`id`	`integer`	sim

Não é necessário corpo do pedido. Transmita os parâmetros indicados acima no URL.

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: APIKey. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com 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)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a resposta contém o valor secreto key; não publique valores reais.

PUT /api/v1/keys/:id — Alteração de uma chave de API

Acesso: token da área pessoal

PUT/api/v1/keys/:id

Parâmetros do caminho

O campo	Tipo	Obrigatório	Validação / descrição
`id`	`integer`	sim

Campos JSON / formulário

O campo	Tipo	Obrigatório	Validação / descrição
`name`	`string`	não
`status`	`string`	não	omitempty,oneof=active inactive
`ip_whitelist`	`array`	não	; IP permitidos: null não altera a lista, um array vazio limpa-a; pode ser null
`ip_blacklist`	`array`	não	; IP bloqueados: null não altera a lista, um array vazio limpa-a; pode ser null
`quota`	`number`	não	; Limite de despesas da chave em USD; 0 — sem limite; pode ser null
`expires_at`	`string`	não	; Data e hora de expiração no formato ISO 8601; pode ser null
`reset_quota`	`boolean`	não	; Repor a parte utilizada do limite de despesas; pode ser null
`rate_limit_5h`	`number`	não	; pode ser null
`rate_limit_1d`	`number`	não	; pode ser null
`rate_limit_7d`	`number`	não	; pode ser null
`reset_rate_limit_usage`	`boolean`	não	; Repor o consumo dos limites por janela; pode ser null

Modelo do corpo do pedido

{
  "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 do pedido: UpdateAPIKeyRequest

Resposta

A resposta JSON contém code, message e data. O conteúdo de data é descrito nos esquemas abaixo.

Esquemas de dados da resposta: APIKey. Os campos e os tipos estão nas páginas «Esquemas de dados».

Esquema da resposta, com 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)"
  }
}

Particularidades: todos os dados pessoais e objetos estão limitados ao sujeito do JWT.

Particularidades: a operação altera o estado ou prossegue uma autorização de utilização única; o exemplo descreve o contrato e não é executado.

Particularidades: a resposta contém o valor secreto key; não publique valores reais.

Particularidades: enquanto existirem pedidos por concluir com reserva associados à chave, o respetivo limite de despesas não pode ser reduzido nem reposto. Envie apenas os campos que pretende alterar.

Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.Contactar o suporte