Endpoints · Tags

Tags

Tags são rótulos transversais que conectam posts por assunto. Use estes endpoints para nuvens de tags, páginas de assunto e navegação relacionada. Cada tag traz a contagem de posts em _count.posts.

Listar tags

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

Requer X-API-Key

Retorna todas as tags do blog em data (array), com a contagem de posts de cada uma.

Quando usar

Renderizar uma nuvem de tags ou filtros por assunto.
Gerar páginas de tag (uma por assunto).
Dimensionar visualmente as tags pela contagem de posts.

Exemplo de requisição

curl "https://api.draftin.io/public/tags" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const res = await fetch("https://api.draftin.io/public/tags", {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data: tags } = await res.json(); // Tag[]

import type { Tag } from "./types";

async function listarTags(): Promise<Tag[]> {
  const res = await fetch("https://api.draftin.io/public/tags", {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  const { data } = (await res.json()) as { data: Tag[] };
  return data;
}

const res = await fetch("https://api.draftin.io/public/tags", {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data: tags } = await res.json();
// monta uma nuvem de tags, ignorando as vazias
const usadas = tags.filter((t) => (t._count?.posts ?? 0) > 0);
console.log(usadas.map((t) => t.name));

Exemplo de resposta

200 OK — { success, data: Tag[] }

{
  "success": true,
  "data": [
    {
      "id": "clxxx301",
      "name": "javascript",
      "blogId": "clxxx789",
      "createdAt": "2026-05-02T08:00:00.000Z",
      "updatedAt": "2026-05-18T11:45:00.000Z",
      "_count": { "posts": 3 }
    }
  ]
}

Respostas possíveis

Status	Significado
200 OK	Lista de tags (`data`: array de `Tag`).
401 Unauthorized	Chave de API inválida ou ausente.
500 Internal Server Error	Erro interno; repita com backoff.

Obter tag por ID

GET https://api.draftin.io /public/tags/{id}

Requer X-API-Key

Recupera uma única tag pelo seu identificador.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único da tag.

Exemplo de requisição

curl "https://api.draftin.io/public/tags/clxxx301" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const id = "clxxx301";
const res = await fetch(`https://api.draftin.io/public/tags/${id}`, {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const tag = res.ok ? (await res.json()).data : null;

async function getTag(id: string): Promise<Tag | null> {
  const res = await fetch(`https://api.draftin.io/public/tags/${id}`, {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  const { data } = (await res.json()) as { data: Tag };
  return data;
}

Exemplo de resposta

200 OK — { success, data: Tag }

{
  "success": true,
  "data": {
    "id": "clxxx301",
    "name": "javascript",
    "blogId": "clxxx789",
    "createdAt": "2026-05-02T08:00:00.000Z",
    "updatedAt": "2026-05-18T11:45:00.000Z",
    "_count": { "posts": 3 }
  }
}

Respostas possíveis

Status	Significado
200 OK	Tag encontrada (`data`: objeto `Tag`).
401 Unauthorized	Chave de API inválida ou ausente.
404 Not Found	Tag não encontrada.
500 Internal Server Error	Erro interno; repita com backoff.

Listar posts de uma tag

GET https://api.draftin.io /public/tags/{id}/posts

Requer X-API-Key

Retorna os posts publicados associados à tag, paginados por page/pageSize, com os itens em data e os metadados em meta.pagination.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	ID da tag. (parâmetro de rota)
page	integer	Não	Número da página (começa em 1). Padrão: `1`
pageSize	integer	Não	Quantidade de posts por página. Padrão: `10`

Exemplo de requisição

curl "https://api.draftin.io/public/tags/clxxx301/posts?page=1&pageSize=10" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const id = "clxxx301";
const res = await fetch(
  `https://api.draftin.io/public/tags/${id}/posts?page=1&pageSize=10`,
  { headers: { "X-API-Key": process.env.DRAFTIN_API_KEY } },
);
const { data: posts, meta } = await res.json();
console.log(meta.pagination.total, "posts com a tag");

import type { Envelope, Post } from "./types";

async function postsDaTag(id: string, page = 1, pageSize = 10) {
  const url = new URL(`/public/tags/${id}/posts`, "https://api.draftin.io");
  url.searchParams.set("page", String(page));
  url.searchParams.set("pageSize", String(pageSize));

  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  return (await res.json()) as Envelope<Post[]>; // data + meta.pagination
}

Exemplo de resposta

200 OK — { success, data, meta.pagination }

{
  "success": true,
  "data": [
    {
      "id": "clxxx101",
      "title": "Introdução ao JavaScript",
      "slug": "introducao-ao-javascript",
      "status": "PUBLISHED",
      "publishedAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 3,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

Respostas possíveis

Status	Significado
200 OK	Posts da tag (`data`: array de `Post`; `meta.pagination` canônico).
400 Bad Request	Parâmetros de paginação inválidos (`page`/`pageSize`).
401 Unauthorized	Chave de API inválida ou ausente.
404 Not Found	Tag não encontrada.
500 Internal Server Error	Erro interno; repita com backoff.

Campos do objeto Tag

idstring

Identificador único da tag.

namestring

Nome da tag (ex.: javascript).

blogIdstring

ID do blog dono da tag.

createdAtstring · date-time

Data/hora de criação.

updatedAtstring · date-time

Data/hora da última atualização.

_countobject

Contadores agregados. Contém posts (integer): quantidade de posts associados a esta tag.

Boas práticas

Filtre tags vazias com _count.posts > 0 antes de exibir.
Cacheie a lista de tags; ela é estável e reaproveitada em muitas páginas.
Combine com posts para "conteúdo relacionado": leia as tags de um post e busque outros da mesma tag.

Casos de uso comuns

Nuvem de tags na sidebar com tamanho proporcional a _count.posts.
Página de assunto: /public/tags/{id}/posts para listar tudo de um tema.
Posts relacionados: usar as tags do post atual para sugerir leituras.