Draftn.io docs · api
Endpoints · Busca

Busca

A busca faz uma pesquisa textual (full-text) sobre título e subtítulo dos posts publicados do blog. É a base para um campo de pesquisa no seu site, retornando resultados enxutos e prontos para listar.

Buscar posts

GET https://api.draftin.io /public/search

Requer X-API-Key

Pesquisa posts publicados por título/subtítulo. Exige um termo (q) com no mínimo 3 caracteres e retorna um envelope SearchResponse com os resultados em data e os metadados em meta.

Quando usar

  • Alimentar um campo de busca no cabeçalho ou em uma página dedicada.
  • Oferecer autocomplete de artigos (lembre o mínimo de 3 caracteres).
  • Listar resultados com capa e data sem precisar carregar o post inteiro.

Query parameters

ParâmetroTipoObrigatórioDescrição
qstringSimTermo de busca. Mínimo de 3 caracteres — abaixo disso a requisição é rejeitada com 400.
limitintegerNãoQuantidade de resultados por página. Máximo 50.
Padrão: 10
offsetintegerNãoQuantos resultados pular (paginação por deslocamento).
Padrão: 0

Exemplo de requisição

curl "https://api.draftin.io/public/search?q=javascript&limit=10&offset=0" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

Exemplo de resposta

200 OK — SearchResponse
{
  "data": [
    {
      "id": "clxxx101",
      "title": "Introdução ao JavaScript",
      "subtitle": "Do zero ao primeiro script",
      "slug": "introducao-ao-javascript",
      "coverUrl": "https://cdn.exemplo.com/capa.jpg",
      "publishedAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "meta": { "q": "javascript", "limit": 10, "offset": 0, "count": 1 }
}

Campos de data[] (SearchResultItem)

idstring
ID do post.
titlestring
Título do post.
subtitlestringnullable
Subtítulo, quando houver.
slugstring
Slug para montar o link do resultado.
coverUrlstringnullable
URL da imagem de capa, quando houver.
publishedAtstring · date-timenullable
Data/hora de publicação (ISO 8601, UTC).

Campos de meta

qstring
O termo de busca processado.
limitinteger
Limite aplicado nesta página.
offsetinteger
Deslocamento aplicado nesta página.
countinteger
Quantidade de itens retornados em data nesta página.

Erro de validação

Sem q ou com menos de 3 caracteres, a API responde 400:

400 Bad Request
{
  "error": "Parâmetro \"q\" obrigatório (mínimo 3 caracteres)"
}

Respostas possíveis

StatusSignificado
200
OK
Resultados da busca (envelope SearchResponse).
400
Bad Request
Parâmetro q ausente ou com menos de 3 caracteres.
401
Unauthorized
Chave de API inválida ou ausente.

Boas práticas

  • Valide no cliente antes de chamar. Só dispare a busca a partir de 3 caracteres — evita 400 desnecessário.
  • Use debounce em campos de digitação para reduzir chamadas durante o typing.
  • Pagine com limit/offset (limite máximo 50) e use meta.count para saber quando parar.
  • Faça a busca no servidor para não expor a chave no front-end.

Casos de uso comuns

  • Barra de pesquisa com resultados instantâneos (após 3 caracteres + debounce).
  • Página "/buscar?q=…" com paginação e contagem por página.
  • Pré-visualização rica de resultados usando coverUrl e subtitle.