REST API

Shayan TaslimAtualizado

A API REST do UserJot dá ao seu código acesso aos mesmos dados do espaço de trabalho que o painel de controlo utiliza: metadados do espaço de trabalho, painéis, pedidos (incluindo fusões, pedidos semelhantes, etiquetas, subscrições e anexos), comentários, votos, entradas do registo de alterações, membros (incluindo o apagamento ao abrigo do RGPD), empresas, conversas, recursos e coleções e artigos do centro de ajuda.

A referência interativa completa, com todas as rotas, esquemas e exemplos, está disponível em userjot.com/docs/api e diretamente em https://api.userjot.com/v1/docs. O documento OpenAPI que lhe serve de base encontra-se em https://api.userjot.com/v1/openapi.json (também disponível em https://userjot.com/docs/api/openapi.json), para que possa gerar clientes com tipagem na sua linguagem.

URL base e autenticação

text
Base URL:      https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKEN

O UserJot aceita dois tipos de token Bearer nas rotas /v1/*:

  • Tokens de API: Crie um token em Definições → MCP & API (apenas administradores e proprietários). Os tokens começam pelo prefixo uj_live_, pertencem a um único espaço de trabalho, não expiram até serem revogados e podem ser renomeados. Utilize Mantenha premido para revogar para revogar imediatamente um token; os tokens revogados continuam listados para fins de auditoria.

  • Tokens de acesso OAuth 2.0: Suporta PKCE (S256), Registo Dinâmico de Clientes (/oauth/register), Documentos de Metadados de ID de Cliente (CIMD), revogação de tokens (/oauth/revoke) e metadados de descoberta em https://api.userjot.com/.well-known/oauth-authorization-server e https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Os tokens de acesso são válidos durante 1 hora, com tokens de atualização rotativos de 30 dias (âmbitos workspace e offline_access), e só permanecem válidos enquanto o utilizador que autorizou continuar a ser proprietário ou administrador desse espaço de trabalho.

Um primeiro pedido

Bash
curl https://api.userjot.com/v1/boards \
  -H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"

Limites de pedidos

Os pedidos da API e do MCP partilham o mesmo limite de pedidos do espaço de trabalho:

Plano

Por minuto

Por hora

Free

10 pedidos

150 pedidos

Starter

60 pedidos

1 500 pedidos

Professional

120 pedidos

5 000 pedidos

Aplicam-se também limites adicionais específicos a determinadas operações:

  • Recursos: As importações de recursos, os carregamentos multipartes e as imagens Markdown importadas automaticamente partilham um limite separado por espaço de trabalho de 20 pedidos por minuto e 300 por hora (além de 20 por minuto e 300 por hora para a conclusão do carregamento).

  • Conversas de saída (POST /v1/conversations): Disponíveis apenas nos planos pagos, com um limite de 5 por dia no Starter e de 15 por dia no Professional (devolve 409 plan_feature_unavailable no plano Free).

Quando um limite é excedido, a API devolve HTTP 429 com um cabeçalho Retry-After e error.details.retry_after_seconds.

Paginação, erros e idempotência

  • Paginação por cursor. Os endpoints de listagem aceitam cursor e limit (até 100; os valores predefinidos variam consoante o endpoint, por exemplo 10 em listas detalhadas como /v1/requests e /v1/changelogs) e devolvem next_cursor para avançar na paginação.

  • Estrutura de erro. As respostas de erro devolvem { "error": { "code", "message", "details" } } e incluem um cabeçalho de resposta X-Request-Id em todas as respostas. Os códigos mais comuns incluem 422 validation_error (com details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (em GET/PATCH /v1/members/{member_id} após o apagamento ao abrigo do RGPD de DELETE /v1/members/{member_id}), 409 member_erased (em rotas que fazem referência a um membro apagado), 409 help_slug_taken e 409 help_version_conflict.

  • Idempotência. Envie um cabeçalho Idempotency-Key (armazenado durante 24 horas com uma impressão digital do corpo do pedido) para repetir pedidos de criação em segurança em oito rotas: /v1/requests, /v1/changelogs, /v1/conversations, /v1/conversations/{conversation_id}/replies, /v1/conversations/{conversation_id}/notes, /v1/assets/import, /v1/help/articles e /v1/help/collections.

Recursos e imagens

Carregue imagens (PNG, JPEG, GIF ou WebP até 10 MiB) de três formas:

  • Carregamento multipartes: POST /v1/assets (createAsset, apenas REST) carrega uma imagem num único pedido multipart/form-data.

  • Importação por URL: POST /v1/assets/import transfere uma imagem HTTPS pública para o armazenamento do espaço de trabalho.

  • Carregamento pré-assinado em três etapas: POST /v1/assets/uploads (fornecendo size_bytes exatos; até 100 sessões de carregamento abertas por espaço de trabalho) → PUT bytes para o URL pré-assinado válido por 30 minutos → POST /v1/assets/uploads/{upload_id}/complete.

Faça referência aos recursos carregados em Markdown com asset:<id>. Os URLs públicos de imagens HTTPS incorporados em Markdown enviado para os endpoints do registo de alterações e dos artigos de ajuda também são importados automaticamente (até 10 imagens em linha por pedido do registo de alterações e 20 por pedido de artigo do centro de ajuda), sendo contabilizados no limite de recursos do espaço de trabalho.

Webhooks

Os webhooks de saída para clientes ainda não estão disponíveis. Para receber alertas da equipa em tempo real, utilize Connect Slack ou Connect Discord, ou consulte as alterações através da REST API.

REST ou MCP

O servidor MCP é desenvolvido com base nesta API e disponibiliza 98 das 100 operações REST como ferramentas MCP (POST /v1/assets carregamento multipartes e DELETE /v1/members/{member_id} apagamento ao abrigo do RGPD são exclusivos da REST). Utilize a API REST a partir do seu próprio backend, das suas automatizações ou do código da sua aplicação quando pretender controlo total sobre os pedidos e as respostas. Utilize MCP para ligar um cliente de IA compatível com o Model Context Protocol.

Gestão de tokens

Trate o seu token de API como qualquer outro segredo:

  • Não o inclua diretamente em ficheiros de configuração submetidos ao repositório.

  • Prefira variáveis de ambiente ou um gestor de segredos.

  • Sempre que possível, utilize tokens separados para ambientes ou membros da equipa diferentes.

  • Revogue os tokens de que já não precisa em Definições → MCP & API, utilizando Mantenha premido para revogar.

Isto respondeu à sua pergunta?