REST API
A API REST do UserJot dá ao seu código acesso aos mesmos dados do espaço de trabalho usados pelo painel: metadados do espaço de trabalho, quadros, solicitações (incluindo mesclagens, solicitações semelhantes, tags, inscrições e anexos), comentários, votos, entradas do changelog, membros (incluindo a exclusão de dados conforme o GDPR), empresas, conversas, recursos e coleções e artigos da central 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 a alimenta está em https://api.userjot.com/v1/openapi.json (também espelhado em https://userjot.com/docs/api/openapi.json), para que você possa gerar clientes tipados na sua linguagem.
URL base e autenticação
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENO UserJot aceita dois tipos de token Bearer nas rotas /v1/*:
Tokens de API: Crie um token em Configurações → MCP & API (somente administradores e proprietários). Os tokens usam o prefixo
uj_live_, pertencem a um único espaço de trabalho, não expiram até serem revogados e podem ser renomeados. Use Mantenha pressionado para revogar (pressione e segure) para revogar um token imediatamente; os tokens revogados permanecem na lista para fins de auditoria.Tokens de acesso OAuth 2.0: Compatível com PKCE (
S256), registro dinâmico de clientes (/oauth/register), documentos de metadados de ID de cliente (CIMD), revogação de tokens (/oauth/revoke) e metadados de descoberta emhttps://api.userjot.com/.well-known/oauth-authorization-serverehttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Os tokens de acesso têm validade de 1 hora, com tokens de atualização rotativos válidos por 30 dias (escoposworkspaceeoffline_access), e permanecem válidos somente enquanto o usuário que autorizou continuar sendo proprietário ou administrador desse espaço de trabalho.
Sua primeira solicitação
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Limites de requisições
As solicitações à API e ao MCP compartilham o mesmo limite de requisições por espaço de trabalho:
Plano | Por minuto | Por hora |
|---|---|---|
Free | 10 solicitações | 150 solicitações |
Starter | 60 solicitações | 1.500 solicitações |
Professional | 120 solicitações | 5.000 solicitações |
Também se aplicam limites adicionais específicos para cada operação:
Recursos: As importações de recursos, os uploads multipartes e as imagens Markdown importadas automaticamente compartilham um limite separado por espaço de trabalho de 20 solicitações por minuto e 300 por hora (além de 20 por minuto e 300 por hora para a conclusão do upload).
Conversas iniciadas (
POST /v1/conversations): Disponível somente nos planos pagos, com limite de 5 por dia no Starter e 15 por dia no Professional (retorna409 plan_feature_unavailableno Free).
Quando um limite é excedido, a API retorna 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
cursorelimit(até100; os valores padrão variam conforme o endpoint, como10em listas detalhadas, por exemplo/v1/requestse/v1/changelogs) e retornamnext_cursorpara avançar pelas páginas.Formato dos erros. As respostas de erro retornam
{ "error": { "code", "message", "details" } }e incluem um cabeçalho de respostaX-Request-Idem todas as respostas. Entre os códigos comuns estão422 validation_error(comdetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(emGET/PATCH /v1/members/{member_id}após a exclusão de dados conforme o GDPR,DELETE /v1/members/{member_id}),409 member_erased(em rotas que fazem referência a um membro cujos dados foram excluídos),409 help_slug_takene409 help_version_conflict.Idempotência. Envie um cabeçalho
Idempotency-Key(armazenado por 24 horas junto com uma impressão digital do corpo da solicitação) para repetir com segurança solicitações de criação em oito rotas:/v1/requests,/v1/changelogs,/v1/conversations,/v1/conversations/{conversation_id}/replies,/v1/conversations/{conversation_id}/notes,/v1/assets/import,/v1/help/articlese/v1/help/collections.
Recursos e imagens
Faça upload de imagens (PNG, JPEG, GIF ou WebP de até 10 MiB) de três maneiras:
Upload multipartes:
POST /v1/assets(createAsset, somente REST) faz upload de uma imagem em uma única solicitaçãomultipart/form-data.Importação por URL:
POST /v1/assets/importbaixa uma imagem HTTPS pública para o armazenamento do espaço de trabalho.Upload pré-assinado em três etapas:
POST /v1/assets/uploads(fornecendo osize_bytesexato; até 100 sessões de upload abertas por espaço de trabalho) →PUTbytes para a URL pré-assinada válida por 30 minutos →POST /v1/assets/uploads/{upload_id}/complete.
Faça referência aos recursos enviados em Markdown com asset:<id>. URLs públicas HTTPS de imagens incorporadas em Markdown enviado aos endpoints de changelog e de artigos da central de ajuda também são importadas automaticamente (até 10 imagens em linha por solicitação de changelog e 20 por solicitação de artigo da central de ajuda), e contam para o 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 equipe em tempo real, use Conectar Slack ou Conectar Discord, ou consulte as alterações periodicamente usando a API REST.
REST ou MCP
O servidor MCP é baseado nesta API e disponibiliza 98 das 100 operações REST como ferramentas MCP (POST /v1/assets upload multipartes e DELETE /v1/members/{member_id} exclusão de dados conforme o GDPR estão disponíveis somente via REST). Use a API REST no seu próprio back-end, em automações ou no código do seu aplicativo quando quiser ter controle total sobre as solicitações e respostas. Use MCP ao conectar um cliente de IA compatível com o Model Context Protocol.
Como lidar com tokens
Trate seu token de API como qualquer outro segredo:
Não inclua o token diretamente em arquivos de configuração versionados.
Prefira usar variáveis de ambiente ou um gerenciador de segredos.
Sempre que possível, use tokens separados para diferentes ambientes ou integrantes da equipe.
Revogue os tokens de que não precisa mais em Configurações → MCP & API, usando Mantenha pressionado para revogar.