Pular para o conteúdo principal

API

Referência da API​

O Semaphore UI fornece dois formatos de documentação da API, para que você possa escolher o que melhor se adapta ao seu fluxo de trabalho:

  • Swagger/OpenAPI — ideal se você prefere uma experiência interativa no navegador.
  • Coleção oficial do Postman — explore e teste todos os endpoints no Postman.
  • Documentação Swagger da API integrada — documentação interativa da API baseada no Swagger UI. Você pode acessá-la na sua instância.

Todas as opções incluem documentação completa dos endpoints disponíveis, parâmetros e exemplos de respostas.

Primeiros passos com a API​

Para começar a usar a API do Semaphore, você precisa gerar um token de API. Esse token deve ser incluído no cabeçalho da requisição como:

Authorization: Bearer YOUR_API_TOKEN

Criando um token de API​

Há duas maneiras de criar um token de API:

  • Pela interface web
  • Usando uma requisição HTTP

Pela interface web (desde a versão 2.14)​

Você pode criar e gerenciar seus tokens de API pela interface web do Semaphore:

Tokens de API

Usando uma requisição HTTP​

Você também pode se autenticar e gerar um token de sessão usando uma requisição HTTP direta.

Faça login no Semaphore (a senha deve ser escapada, por exemplo slashy\\pass em vez de slashy\pass):

curl -v -c /tmp/semaphore-cookie -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"auth": "YOUR_LOGIN", "password": "YOUR_PASSWORD"}' \
http://localhost:3000/api/auth/login

Gere um novo token e obtenha o novo token:

curl -v -b /tmp/semaphore-cookie -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
http://localhost:3000/api/user/tokens

O comando deve retornar algo semelhante a:

{
    "id": "YOUR_ACCESS_TOKEN",
    "created": "2025-05-21T02:35:12Z",
    "expired": false,
    "user_id": 3
}

Usando o token para fazer requisições à API​

Depois de obter seu token de API, inclua-o no cabeçalho Authorization para autenticar suas requisições.

Iniciar uma tarefa​

Use este token para iniciar uma tarefa ou qualquer outra operação:

curl -v -XPOST \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{"template_id": 1}' \
http://localhost:3000/api/project/1/tasks

Expirando um token de API​

Se você não precisar mais do token, expire-o para manter sua conta segura.

Para revogar (expirar) manualmente um token de API, envie uma requisição DELETE para o endpoint do token:

curl -v -XDELETE \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
http://localhost:3000/api/user/tokens/YOUR_ACCESS_TOKEN