Referência da API | Wambesha

A referência da API está disponível somente em inglês.

Referência da API — v1

https://api.wambesha.com · Autenticação Bearer · JSON

Todos os endpoints da v1, com seus parâmetros, um exemplo de solicitação e de resposta e os erros que podem retornar. As descrições dos endpoints estão em inglês.

Registro de alterações

Autenticação

Your API key, presented as a Bearer token. Keys are per-account and carry a plan; the plan decides which endpoints answer and what your quota is. Never embed a key in a browser client — it is a credential, and a browser cannot keep one.

HTTP

Authorization: Bearer $WAMBESHA_API_KEY

Quando um endpoint aceita a chave de demonstração pública, o trecho de código “Experimente” dele a inclui, por isso funciona como está; todos os outros trechos precisam da sua própria chave. A chave de demonstração serve apenas para experimentar a API: ela muda diariamente, pode ser desativada a qualquer momento e nunca deve ser usada em produção. Use sua própria chave em tudo o que você criar.

Cabeçalhos de resposta

X-Request-IDToda resposta autenticada
The id of this request, on every response - success or error. Quote it to support: it is how we find your request in our logs. An X-Request-ID you send is honoured and echoed back, so you can use your own; otherwise we generate one. /v1 error bodies carry no trace id of their own.
X-Quota-ResetToda resposta autenticada
RFC 3339 instant at which the billing period rolls. Present on every response to a request whose key was metered - every 2xx, every error a handler returned, and the quota 429. Absent on a refusal that happens before metering: a missing or unknown key (401), a restricted key or a plan that does not carry the endpoint (403), a public demo-key gate refusal, and the pre-authentication flood throttle.
X-Calls-RemainingToda resposta autenticada
Requests left in the period after this one, never below 0. Present whenever X-Quota-Reset is (see there for when a response carries no quota headers).
X-Verifications-RemainingToda resposta autenticada
How many verifications you can still make before a limit stops you. The daily limit and the monthly allowance are counted separately; this is whichever of the two runs out first. Sent whenever X-Quota-Reset is.
X-Quota-GraceToda resposta autenticada
true when THIS request fell inside the 10% grace band above a monthly ceiling. A grace request is served and is not billed; treat true as "back off now", not as headroom. Always true or false, never absent when the other quota headers are present.
Retry-AfterSomente em respostas 429
Seconds to wait before retrying. On every 429 - the quota hard stop, the public demo key's limits, and the pre-authentication flood throttle (which carries this header alone, because no key has been read yet).
X-Demo-Challenge-ModeSomente com a chave de demonstração
Sent only on responses to the public demo key. The value interactive asks the documentation page to show the visible verification widget - it is sent once a browser has made more than five runs in ten minutes or has received a 429. The page then repeats the header, X-Demo-Challenge-Mode: interactive, on its next request, with the widget's token in X-Demo-Challenge. Requests made with your own key never receive it.

Erros

Todo erro tem o mesmo corpo: o status HTTP, um código estável para sua lógica tratar, uma mensagem para pessoas e erros de campo quando um valor estava errado. Para identificar uma requisição ao entrar em contato conosco, informe o cabeçalho de resposta X-Request-ID dela.

Resposta registrada

Content-Type: application/json
X-Request-ID: 5f3c9a1e7b2d4c60

GET/v1/search

{
  "timestamp": "2026-09-27T12:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Enter at least 2 characters to search.",
  "path": "/v1/search",
  "errors": [
    {
      "field": "q",
      "rejectedValue": "a",
      "message": "Enter at least 2 characters to search."
    }
  ],
  "metadata": {
    "errorCode": "CATALOG_SEARCH_QUERY_TOO_SHORT"
  },
  "code": "validation-failed"
}

400

validation-failed400405
The request is not one this operation accepts - a parameter outside its rule, a missing required parameter, an unsupported language, or a method the route does not take.
O que fazerFix the request; errors names the parameter. Retrying it unchanged fails the same way.
cursor-invalid400
The cursor is malformed, stale, from a different filter set or sort, or past what your key may page.
O que fazerDrop the cursor and request the first page again.
unauthenticated401
No key, or a key that is unknown, malformed, expired or revoked - one answer for all of them. Also what a switched-off public demo key answers.
O que fazerSend a valid key as Authorization: Bearer <key>; if it was rotated, use its replacement.
forbidden403
The key is valid but a restriction its owner set - a scope, an IP allowlist, a referrer allowlist - excludes this request. Also a key rotating a key other than itself.
O que fazerCall from an allowed place or change the key's restrictions in the console.
plan-required403
Your plan does not include this operation or this freshness, or the public demo key was used for something it cannot reach.
O que fazerUpgrade the plan, or use your own key rather than the demo key.
challenge-required403
A browser call with the public demo key carried no valid bot-check token.
O que fazerComplete the check on the page and run the request again. Not sent to paying keys.
not-found404
Nothing matches the reference, or the reference is not a valid id.
O que fazerCheck the id; a merged record answers 200 with its survivor, so 404 means it never existed here.
conflict409
The request contradicts current state - a key already rotated, revoked or expired, or an identifier that matches several records.
O que fazerRead metadata.errorCode; rotate the replacement key, or disambiguate the identifier.
gone410
The record existed and has been removed. No reason is given, by design.
O que fazerDrop it from your mirror; /v1/changes reports it as removed.
quota-exhausted429
A plan ceiling is reached - requests (daily or monthly) or verifications. The message names which.
O que fazerWait for Retry-After (the daily window resets at midnight UTC, the monthly one at X-Quota-Reset), or upgrade. The refused call is not charged.
rate-limited429
Too many requests too fast - the per-address flood throttle, or the public demo key's own limits, temporary blocks and in-flight cap.
O que fazerWait Retry-After seconds, then slow down.
upstream-unavailable503
We could not meter or serve the request right now. Never served unmetered, never charged.
O que fazerRetry with exponential backoff.

Versionamento

A v1 nunca quebra a compatibilidade: caminhos, parâmetros obrigatórios e campos de resposta não mudam dentro da v1. Novos campos e endpoints podem ser adicionados e são anunciados primeiro no registro de alterações. Como funciona o versionamento

Endpoints

Discovery

Titles

People

Changes

Account