✍️ Dev.to & Hashnode

O Dev.to roda sobre o Forem, plataforma open-source da própria Dev.to. A API é REST, autenticada por uma DEV API Key pessoal — não OAuth, não scopes, é uma chave única que dá acesso de escrita à sua conta.

Para gerar a chave: Settings → Extensions → DEV Community API Keys. Dê um nome descritivo (ex.: postiz-prod) e copie o valor — ele só aparece uma vez.

# Caminho na UI
https://dev.to/settings/extensions

# Bloco "DEV Community API Keys"
# 1. Project name: postiz-prod
# 2. Clique em "Generate API Key"
# 3. Copie o valor (formato hex de ~40 caracteres)

# Teste rápido — listar seus artigos (200 = chave válida)
curl -H "api-key: SEU_DEV_API_KEY" \
     https://dev.to/api/articles/me

Conceitos-chave

Para publicar um post, basta um POST em https://dev.to/api/articles com o header api-key e um JSON aninhado em {"article": {...}}. Os campos essenciais são title, body_markdown e published.

Com published: false, o post vira rascunho — útil para revisar antes de soltar. Com true, ele aparece no feed na hora.

# Publicar artigo no Dev.to
curl -X POST https://dev.to/api/articles \
  -H "api-key: $DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "article": {
      "title": "Subindo Postiz com Docker Compose",
      "body_markdown": "# Introdução\n\nNeste post mostro como...",
      "published": true,
      "tags": ["docker", "selfhosted", "devops"],
      "series": "MkBlogs"
    }
  }'

# Resposta esperada (201 Created)
# {
#   "id": 1234567,
#   "url": "https://dev.to/seu-user/subindo-postiz-...",
#   "slug": "subindo-postiz-com-docker-compose-XXXX",
#   "published_at": "2026-05-24T12:00:00Z"
# }

Conceitos-chave

Em vez de mandar título, tags e cover em campos JSON separados, o Forem aceita um frontmatter YAML embutido no body_markdown. Vantagem: o mesmo Markdown que você escreveria localmente publica direto, sem transformar nada.

O cover_image precisa ser uma URL pública (HTTPS) — o Dev.to não aceita upload binário pelo endpoint de articles. Use Cloudinary, R2, ou as próprias imagens hospedadas em outro post.

# body_markdown com frontmatter
---
title: Subindo Postiz com Docker Compose
published: true
description: Stack completo em 50 minutos.
tags: docker, selfhosted, devops
cover_image: https://cdn.example.com/covers/postiz-cover.png
canonical_url: https://meublog.dev/postiz-docker
series: MkBlogs
---

# Introdução

Neste post mostro como subir o Postiz...

## Setup

```yaml
services:
  postiz:
    image: ghcr.io/gitroomhq/postiz-app:latest
```

Quando há frontmatter, ele sobrescreve os campos do JSON externo. Padronize: ou tudo no frontmatter, ou tudo nos campos top-level — misturar gera confusão.

# Request com frontmatter (mais limpo)
curl -X POST https://dev.to/api/articles \
  -H "api-key: $DEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "article": {
    "body_markdown": "---\ntitle: Meu post\npublished: true\ntags: docker, devops\ncover_image: https://cdn.example.com/cover.png\n---\n\n# Conteúdo aqui"
  }
}
JSON

Conceitos-chave

O Hashnode escolheu outro caminho: GraphQL em um único endpoint, https://gql.hashnode.com/. Em vez de muitos endpoints REST, você manda uma query/mutation descrevendo exatamente o que quer.

A autenticação é via Personal Access Token, gerado em Account Settings → Developer → Generate New Token. Vai no header Authorization sem prefixo Bearer — sutileza fácil de errar.

# Smoke test — query "me" valida o token
curl -X POST https://gql.hashnode.com/ \
  -H "Authorization: $HASHNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { me { id username publications(first: 5) { edges { node { id title } } } } }"
  }'

# Resposta esperada
# {
#   "data": {
#     "me": {
#       "id": "654...",
#       "username": "seu-user",
#       "publications": {
#         "edges": [
#           { "node": { "id": "abc123", "title": "Meu Blog" } }
#         ]
#       }
#     }
#   }
# }

Conceitos-chave

A mutation publishPost recebe um PublishPostInput com title, contentMarkdown, publicationId e opcionais como tags, cover e canonical. Use sempre variáveis — nunca interpole strings na query.

# Mutation completa
mutation PublishPost($input: PublishPostInput!) {
  publishPost(input: $input) {
    post {
      id
      slug
      url
      publishedAt
    }
  }
}

# Variáveis (variables)
{
  "input": {
    "title": "Subindo Postiz com Docker Compose",
    "contentMarkdown": "# Introdução\n\nNeste post...",
    "publicationId": "abc123_id_da_sua_publication",
    "tags": [
      { "slug": "docker", "name": "Docker" },
      { "slug": "devops", "name": "DevOps" }
    ],
    "coverImageOptions": {
      "coverImageURL": "https://cdn.example.com/cover.png"
    },
    "originalArticleURL": "https://meublog.dev/postiz-docker"
  }
}

Mandar via curl é direto: corpo JSON com query e variables separados.

# Disparar via curl
curl -X POST https://gql.hashnode.com/ \
  -H "Authorization: $HASHNODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation PublishPost($input: PublishPostInput!) { publishPost(input: $input) { post { id slug url } } }",
    "variables": {
      "input": {
        "title": "Subindo Postiz com Docker Compose",
        "contentMarkdown": "# Introdução\n\nNeste post...",
        "publicationId": "SUA_PUBLICATION_ID",
        "tags": [{ "slug": "docker", "name": "Docker" }],
        "originalArticleURL": "https://meublog.dev/postiz-docker"
      }
    }
  }'

Conceitos-chave

Republicar o mesmo post em Dev.to + Hashnode + seu blog próprio multiplica audiência — mas sem cuidado isso vira duplicate content e o Google penaliza todos os três. A solução é a canonical_url: você declara qual versão é a "original" e as cópias dizem ao Google "indexe aquela ali".

# Dev.to — campo "canonical_url"
{
  "article": {
    "title": "Subindo Postiz com Docker Compose",
    "body_markdown": "...",
    "canonical_url": "https://meublog.dev/postiz-docker",
    "published": true
  }
}

# Hashnode — campo "originalArticleURL"
{
  "input": {
    "title": "Subindo Postiz com Docker Compose",
    "contentMarkdown": "...",
    "publicationId": "SUA_PUB_ID",
    "originalArticleURL": "https://meublog.dev/postiz-docker"
  }
}

Conceitos-chave