REST API

Shayan TaslimAggiornato

L’API REST di UserJot offre al tuo codice accesso agli stessi dati dell’area di lavoro usati dalla dashboard: metadati dell’area di lavoro, bacheche, richieste (incluse fusioni, richieste simili, tag, iscrizioni e allegati), commenti, voti, voci del changelog, membri (inclusa la cancellazione ai sensi del GDPR), aziende, conversazioni, asset e raccolte e articoli del Centro assistenza.

Il riferimento interattivo completo, con ogni endpoint, schema ed esempio, è disponibile all’indirizzo userjot.com/docs/api e direttamente su https://api.userjot.com/v1/docs. Il documento OpenAPI alla base del riferimento è disponibile su https://api.userjot.com/v1/openapi.json (e in una copia su https://userjot.com/docs/api/openapi.json), così puoi generare client tipizzati nella tua lingua.

URL di base e autenticazione

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

UserJot accetta due tipi di token Bearer sulle route /v1/*:

  • Token API: crea un token in Impostazioni → MCP & API (solo amministratori e proprietari). I token hanno il prefisso uj_live_, appartengono a una sola area di lavoro, non scadono finché non vengono revocati e possono essere rinominati. Usa Tieni premuto per revocare (tieni premuto) per revocare immediatamente un token; i token revocati restano nell’elenco a fini di verifica.

  • Token di accesso OAuth 2.0: supportano PKCE (S256), la registrazione dinamica dei client (/oauth/register), i documenti dei metadati dell’ID client (CIMD), la revoca dei token (/oauth/revoke) e i metadati di discovery su https://api.userjot.com/.well-known/oauth-authorization-server e https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. I token di accesso durano 1 ora e sono accompagnati da token di aggiornamento rotanti validi 30 giorni (ambiti workspace e offline_access); restano validi solo finché l’utente che ha autorizzato l’accesso mantiene il ruolo di proprietario o amministratore di quell’area di lavoro.

Una prima richiesta

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

Limiti di frequenza

Le richieste API e MCP condividono un unico limite di frequenza per spazio di lavoro:

Piano

Al minuto

All’ora

Free

10 richieste

150 richieste

Starter

60 richieste

1.500 richieste

Professional

120 richieste

5.000 richieste

Si applicano budget aggiuntivi specifici per operazione:

  • Asset: le importazioni di asset, i caricamenti multipart e le immagini Markdown importate automaticamente condividono un budget separato per area di lavoro di 20 richieste al minuto e 300 all’ora (oltre a 20 al minuto e 300 all’ora per il completamento dei caricamenti).

  • Conversazioni in uscita (POST /v1/conversations): disponibili solo nei piani a pagamento, con un limite di 5 al giorno nel piano Starter e di 15 al giorno nel piano Professional (nel piano Free restituiscono 409 plan_feature_unavailable).

Quando viene superato un limite, l’API restituisce HTTP 429 con un’intestazione Retry-After e error.details.retry_after_seconds.

Paginazione, errori e idempotenza

  • Paginazione tramite cursore. Gli endpoint per gli elenchi accettano cursor e limit (fino a 100; i valori predefiniti variano a seconda dell’endpoint, ad esempio 10 per gli elenchi ricchi di dati come /v1/requests e /v1/changelogs) e restituiscono next_cursor per passare alla pagina successiva.

  • Struttura delle risposte di errore. Le risposte di errore restituiscono { "error": { "code", "message", "details" } } e includono un’intestazione di risposta X-Request-Id in ogni risposta. Tra i codici più comuni figurano 422 validation_error (con details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (su GET/PATCH /v1/members/{member_id} dopo la cancellazione ai sensi del GDPR DELETE /v1/members/{member_id}), 409 member_erased (sugli endpoint che fanno riferimento a un membro cancellato), 409 help_slug_taken e 409 help_version_conflict.

  • Idempotenza. Invia un’intestazione Idempotency-Key (memorizzata per 24 ore insieme all’impronta del corpo della richiesta) per riprovare in sicurezza le richieste di creazione su otto endpoint: /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.

Risorse e immagini

Carica immagini (PNG, JPEG, GIF o WebP fino a 10 MiB) in tre modi:

  • Caricamento multipart: POST /v1/assets (createAsset, solo REST) carica un’immagine con una singola richiesta multipart/form-data.

  • Importazione da URL: POST /v1/assets/import scarica un’immagine HTTPS pubblica nello spazio di archiviazione dell’area di lavoro.

  • Caricamento in tre passaggi con URL presigned: POST /v1/assets/uploads (fornendo il valore esatto di size_bytes; fino a 100 sessioni di caricamento aperte per area di lavoro) → PUT byte all’URL presigned valido 30 minuti → POST /v1/assets/uploads/{upload_id}/complete.

Fai riferimento agli asset caricati in Markdown con asset:<id>. Anche gli URL HTTPS pubblici di immagini incorporati nel Markdown inviato agli endpoint del changelog e degli articoli del Centro assistenza vengono importati automaticamente (fino a 10 immagini in linea per richiesta del changelog e 20 per richiesta di un articolo del Centro assistenza) e conteggiati nel budget degli asset dell’area di lavoro.

Webhook

I webhook in uscita per i clienti non sono ancora disponibili. Per ricevere avvisi in tempo reale per il team, usa Connect Slack o Connect Discord, oppure controlla periodicamente le modifiche tramite l’API REST.

REST o MCP

Il server MCP si basa su questa API ed espone 98 delle 100 operazioni REST come strumenti MCP (POST /v1/assets per il caricamento multipart e DELETE /v1/members/{member_id} per la cancellazione ai sensi del GDPR sono disponibili solo tramite REST). Usa l’API REST dal tuo backend, dalle tue automazioni o dal codice della tua applicazione quando vuoi il pieno controllo su richieste e risposte. Usa MCP per connetterti a un client AI che supporta il Model Context Protocol.

Gestione dei token

Tratta il tuo token API come qualsiasi altro segreto:

  • Non inserirlo direttamente nei file di configurazione inclusi nei commit.

  • Preferisci le variabili di ambiente o un gestore di segreti.

  • Quando possibile, usa token diversi per ambienti o collaboratori diversi.

  • Revoca i token che non ti servono più da Impostazioni → MCP & API usando Tieni premuto per revocare.

Ha risposto alla tua domanda?