Social Media Auto Publisher

O que é essa API

É a mesma API REST que move o painel do PostAutomation - cadastro de nichos, upload e agendamento de vídeos, métricas e a conexão com o YouTube. Cada requisição autenticada usa o mesmo token que sua sessão já tem quando você está logado no painel.

URL base

Não existe prefixo de versão nem de rota - cada endpoint é chamado direto na raiz.

Produção

https://postautomation-production-5857.up.railway.app

Local

http://localhost:3000

Autenticação

Faça login em POST /auth/login com email e senha da sua conta pra receber um accessToken. Envie esse token em toda chamada protegida no header abaixo. Quando ele expirar, troque por um novo em POST /auth/refresh usando o refreshToken recebido junto - sem precisar logar de novo.

Authorization: Bearer <SEU_ACCESS_TOKEN>

Não existe um mecanismo separado de chave de API hoje - a autenticação é sempre o token da sua própria conta.

Códigos de erro comuns

Todo erro vem no formato padrão do NestJS: { statusCode, message }. Os códigos abaixo aparecem em praticamente qualquer endpoint protegido; cada endpoint também lista, na própria seção, os status específicos dele nas abas de resposta.

Status	Descrição
`400` Bad Request	O corpo da requisição não passou na validação - campo obrigatório ausente ou em formato errado.
`401` Unauthorized	Token ausente, inválido ou expirado. Renove em POST /auth/refresh ou faça login de novo.
`404` Not Found	Nenhum registro encontrado com o id informado.
`409` Conflict	Já existe um registro com esse valor único (ex: email já cadastrado).
`500` Internal Server Error	Erro inesperado no servidor - se persistir, entre em contato com o suporte.

Autenticação

POST/auth/loginPúblico

Login

Autentica com email e senha e devolve o par de tokens usado em todas as outras chamadas da API.

Corpo da requisição (application/json)

`email`obrigatório string	Email cadastrado do usuário.
`password`obrigatório string	Senha da conta.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"<EMAIL>","password":"<PASSWORD>"}'

Resposta

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST/auth/refreshPúblico

Renovar sessão

Troca um refreshToken válido por um novo par de tokens, sem precisar logar de novo.

Corpo da requisição (application/json)

refreshTokenobrigatório

string

Refresh token obtido no login.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<REFRESHTOKEN>"}'

Resposta

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

GET/auth/youtube/connectRequer autenticação

Iniciar conexão do YouTube

Gera a URL de autorização do Google para o usuário logado conectar um canal do YouTube. O cliente deve redirecionar o navegador pra essa URL - depois da autorização o Google chama nosso callback e a conexão fica pronta, sem o cliente precisar fazer mais nada.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/auth/youtube/connect" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=..."
}

Usuários

Cadastro, dados da conta e status da conexão com o YouTube.

POST/usersPúblico

Criar conta

Cadastra um novo usuário. É o único endpoint de usuários que não exige autenticação.

Corpo da requisição (application/json)

`email`obrigatório string	Precisa ser um email válido.
`name` string	Até 10 caracteres.
`password` string	Entre 3 e 20 caracteres.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/users" \
  -H "Content-Type: application/json" \
  -d '{"email":"<EMAIL>","name":"<NAME>","password":"<PASSWORD>"}'

Resposta

{
  "id": "b3f1a2c4-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "email": "criador@exemplo.com",
  "name": "Ana",
  "role": "USER",
  "createdAt": "2026-09-01T12:00:00.000Z"
}

GET/usersRequer autenticação

Listar usuários

Lista todos os usuários cadastrados.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/users" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  {
    "id": "b3f1a2c4-1234-4a5b-8c9d-0e1f2a3b4c5d",
    "email": "criador@exemplo.com",
    "name": "Ana",
    "role": "USER"
  }
]

GET/users/emailsRequer autenticação

Listar emails

Lista só os emails de todos os usuários cadastrados.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/users/emails" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  "criador@exemplo.com",
  "outro@exemplo.com"
]

GET/users/email/:emailRequer autenticação

Buscar usuário por email

Retorna os dados de um usuário a partir do email.

Parâmetros na URL

emailobrigatório

string

Email do usuário.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/users/email/<EMAIL>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "id": "b3f1a2c4-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "email": "criador@exemplo.com",
  "name": "Ana"
}

GET/users/:idRequer autenticação

Buscar usuário por id

Retorna os dados de um usuário específico.

Parâmetros na URL

idobrigatório

string (uuid)

Id do usuário.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/users/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "id": "b3f1a2c4-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "email": "criador@exemplo.com",
  "name": "Ana",
  "role": "USER"
}

PATCH/users/:idRequer autenticação

Atualizar usuário

Atualiza parcialmente os dados de um usuário (mesmos campos do cadastro, todos opcionais).

Parâmetros na URL

idobrigatório

string (uuid)

Id do usuário.

Corpo da requisição (application/json)

`email` string	Novo email.
`name` string	Até 10 caracteres.
`password` string	Entre 3 e 20 caracteres.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X PATCH "https://postautomation-production-5857.up.railway.app/users/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"email":"<EMAIL>","name":"<NAME>","password":"<PASSWORD>"}'

Resposta

{
  "id": "b3f1a2c4-1234-4a5b-8c9d-0e1f2a3b4c5d",
  "email": "novo@exemplo.com",
  "name": "Ana"
}

DELETE/users/:idRequer autenticação

Excluir usuário

Remove permanentemente uma conta de usuário.

Parâmetros na URL

idobrigatório

string (uuid)

Id do usuário.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X DELETE "https://postautomation-production-5857.up.railway.app/users/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "message": "Usuário removido com sucesso."
}

GET/users/:id/youtube-connectionRequer autenticação

Status da conexão com o YouTube

Informa se o usuário tem um canal do YouTube conectado no momento.

Parâmetros na URL

idobrigatório

string (uuid)

Id do usuário.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/users/<ID>/youtube-connection" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "connected": true,
  "account": {
    "id": "a1b2c3d4-...",
    "platform": "YOUTUBE",
    "tokenExpiry": "2026-09-17T22:00:00.000Z"
  }
}

DELETE/users/:id/youtube-connectionRequer autenticação

Desconectar YouTube

Remove a conexão do canal do YouTube do usuário. Isso apaga a credencial guardada no nosso banco - não revoga o acesso automaticamente do lado do Google (o usuário pode revogar manualmente na própria conta Google se quiser).

Parâmetros na URL

idobrigatório

string (uuid)

Id do usuário.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X DELETE "https://postautomation-production-5857.up.railway.app/users/<ID>/youtube-connection" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "message": "Conexão com o YouTube removida com sucesso."
}

Nichos

Organização dos posts por nicho de conteúdo.

POST/nichesRequer autenticação

Criar nicho

Cria um nicho usado pra organizar os posts.

Corpo da requisição (application/json)

`name`obrigatório string	Entre 2 e 60 caracteres.
`description` string	Até 255 caracteres.
`active` boolean	Padrão: true.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/niches" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"<NAME>","description":"<DESCRIPTION>","active":"<ACTIVE>"}'

Resposta

{
  "id": "c1a2b3c4-...",
  "name": "Curiosidades",
  "description": null,
  "active": true
}

GET/nichesRequer autenticação

Listar nichos

Lista todos os nichos cadastrados.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/niches" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  {
    "id": "c1a2b3c4-...",
    "name": "Curiosidades",
    "active": true
  }
]

GET/niches/:idRequer autenticação

Buscar nicho

Retorna um nicho específico.

Parâmetros na URL

idobrigatório

string (uuid)

Id do nicho.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/niches/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "id": "c1a2b3c4-...",
  "name": "Curiosidades",
  "active": true
}

PATCH/niches/:idRequer autenticação

Atualizar nicho

Atualiza parcialmente um nicho (mesmos campos da criação, todos opcionais).

Parâmetros na URL

idobrigatório

string (uuid)

Id do nicho.

Corpo da requisição (application/json)

`name` string	Entre 2 e 60 caracteres.
`description` string	Até 255 caracteres.
`active` boolean

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X PATCH "https://postautomation-production-5857.up.railway.app/niches/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"<NAME>","description":"<DESCRIPTION>","active":"<ACTIVE>"}'

Resposta

{
  "id": "c1a2b3c4-...",
  "name": "Curiosidades e fatos",
  "active": true
}

DELETE/niches/:idRequer autenticação

Excluir nicho

Remove um nicho.

Parâmetros na URL

idobrigatório

string (uuid)

Id do nicho.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X DELETE "https://postautomation-production-5857.up.railway.app/niches/<ID>" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "message": "Nicho removido com sucesso."
}

Posts e agendamento

Upload, edição de rascunho, agendamento, publicação e métricas.

GET/postsRequer autenticação

Listar posts

Lista todos os posts do usuário autenticado (qualquer status).

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  {
    "id": "d1e2f3a4-...",
    "platform": "YOUTUBE",
    "title": "Como automatizar sua publicação",
    "status": "POSTED",
    "scheduledAt": "2026-09-10T13:00:00.000Z",
    "postedAt": "2026-09-10T13:00:04.000Z"
  }
]

GET/posts/overviewRequer autenticação

Resumo de posts

Retorna um resumo agregado dos posts do usuário (usado pela tela inicial do painel) - opcionalmente filtrado por data.

Query params

date

string (ISO 8601)

Filtra o resumo por um dia específico.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/overview" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "scheduled": 3,
  "posted": 12,
  "drafts": 2,
  "failed": 0
}

GET/posts/:id/analyticsRequer autenticação

Métricas de um post

Retorna o histórico de métricas coletadas (visualizações, curtidas, comentários) de um post publicado.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/<ID>/analytics" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  {
    "id": "e1f2...",
    "views": 1240,
    "likes": 87,
    "comments": 12,
    "collectedAt": "2026-09-17T09:00:00.000Z"
  }
]

GET/posts/draftsRequer autenticação

Listar rascunhos

Lista os posts que ainda estão em rascunho (status DRAFT).

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/drafts" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

[
  {
    "id": "f1a2...",
    "title": "Sem título",
    "status": "DRAFT",
    "format": "SHORT"
  }
]

GET/posts/:id/draftRequer autenticação

Buscar rascunho

Retorna um rascunho específico.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/<ID>/draft" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "id": "f1a2...",
  "title": "Sem título",
  "status": "DRAFT",
  "format": "SHORT",
  "trimStart": 0,
  "trimEnd": 12.5
}

GET/posts/:id/draft/videoRequer autenticação

Baixar vídeo do rascunho

Retorna o arquivo de vídeo do rascunho (stream binário, não JSON). Usado pelo player do editor de vídeo.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/<ID>/draft/video" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

<binário - video/mp4>

GET/posts/:id/draft/thumbnailRequer autenticação

Baixar thumbnail do rascunho

Retorna a imagem de thumbnail do rascunho (stream binário, não JSON).

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X GET "https://postautomation-production-5857.up.railway.app/posts/<ID>/draft/thumbnail" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

<binário - image/jpeg>

POST/posts/draftRequer autenticação

Criar rascunho

Envia um vídeo e cria um novo post em rascunho (status DRAFT).

Corpo da requisição (multipart/form-data)

`video`obrigatório file	Arquivo de vídeo.
`title` string	Até 255 caracteres.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/posts/draft" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -F "video=@caminho/do/arquivo" \
  -F "title=<TITLE>"

Resposta

{
  "id": "f1a2...",
  "title": "Sem título",
  "status": "DRAFT"
}

PATCH/posts/:id/editRequer autenticação

Editar rascunho

Atualiza título, descrição, formato ou o corte (trim) de um rascunho.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Corpo da requisição (application/json)

`title` string
`description` string	Até 500 caracteres.
`format` "SHORT" \| "STANDARD"
`trimStart` number	Segundos, >= 0.
`trimEnd` number	Segundos, >= 0.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X PATCH "https://postautomation-production-5857.up.railway.app/posts/<ID>/edit" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"title":"<TITLE>","description":"<DESCRIPTION>","format":"<FORMAT>","trimStart":"<TRIMSTART>","trimEnd":"<TRIMEND>"}'

Resposta

{
  "id": "f1a2...",
  "format": "SHORT",
  "trimStart": 0,
  "trimEnd": 12.5
}

POST/posts/:id/thumbnailRequer autenticação

Enviar thumbnail

Envia/substitui a imagem de thumbnail de um rascunho.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Corpo da requisição (multipart/form-data)

thumbnailobrigatório

file

Arquivo de imagem.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/posts/<ID>/thumbnail" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -F "thumbnail=@caminho/do/arquivo"

Resposta

{
  "id": "f1a2...",
  "thumbnailUrl": "https://.../thumb.jpg"
}

PATCH/posts/:id/finalizeRequer autenticação

Finalizar rascunho

Sai do estado de rascunho e agenda a publicação (status DRAFT -> PENDING). A partir daqui o nicho passa a ser obrigatório.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Corpo da requisição (application/json)

`nicheId`obrigatório string (uuid)	Nicho do post.
`scheduledAt`obrigatório string (ISO 8601)	Data/hora da publicação.
`title` string
`description` string

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X PATCH "https://postautomation-production-5857.up.railway.app/posts/<ID>/finalize" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"nicheId":"<NICHEID>","scheduledAt":"<SCHEDULEDAT>","title":"<TITLE>","description":"<DESCRIPTION>"}'

Resposta

{
  "id": "f1a2...",
  "status": "PENDING",
  "scheduledAt": "2026-09-20T13:00:00.000Z"
}

DELETE/posts/:id/draftRequer autenticação

Excluir rascunho

Remove um rascunho e o arquivo de vídeo/thumbnail associado do armazenamento.

Parâmetros na URL

idobrigatório

string (uuid)

Id do post.

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X DELETE "https://postautomation-production-5857.up.railway.app/posts/<ID>/draft" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>"

Resposta

{
  "message": "Rascunho removido com sucesso."
}

POST/posts/import-youtube-urlRequer autenticação

Importar vídeo por URL do YouTube

Cria um post agendado a partir de uma URL pública de um vídeo já existente no YouTube.

Corpo da requisição (application/json)

`userId`obrigatório string (uuid)
`nicheId`obrigatório string (uuid)
`youtubeUrl`obrigatório string (url)	Até 500 caracteres.
`scheduledAt`obrigatório string (ISO 8601)

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/posts/import-youtube-url" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"userId":"<USERID>","nicheId":"<NICHEID>","youtubeUrl":"<YOUTUBEURL>","scheduledAt":"<SCHEDULEDAT>"}'

Resposta

{
  "id": "f1a2...",
  "platform": "YOUTUBE",
  "status": "PENDING"
}

POST/posts/upload-videoRequer autenticação

Enviar vídeo já agendado

Envia um vídeo e já cria o post com nicho e data de publicação definidos (sem passar pelo fluxo de rascunho).

Corpo da requisição (multipart/form-data)

`video`obrigatório file
`userId`obrigatório string (uuid)
`nicheId`obrigatório string (uuid)
`title`obrigatório string	Até 255 caracteres.
`description` string
`scheduledAt`obrigatório string (ISO 8601)

Server URLhttps://postautomation-production-5857.up.railway.app

curl -X POST "https://postautomation-production-5857.up.railway.app/posts/upload-video" \
  -H "Authorization: Bearer <SEU_ACCESS_TOKEN>" \
  -F "video=@caminho/do/arquivo" \
  -F "userId=<USERID>" \
  -F "nicheId=<NICHEID>" \
  -F "title=<TITLE>" \
  -F "description=<DESCRIPTION>" \
  -F "scheduledAt=<SCHEDULEDAT>"

Resposta

{
  "id": "f1a2...",
  "platform": "YOUTUBE",
  "status": "PENDING"
}