Primi passi

Questa guida ti porta da zero alla prima richiesta autenticata: crea un token, imposta la base URL e chiama l'API.

Prerequisiti

• Accesso a un workspace idoneo alla Public API.
• Permesso di creare token in quel workspace.
• Familiarità di base con le risorse Copera — board, table, righe, channel, documenti.

Passo 1 — Crea un Personal Access Token

Un Personal Access Token (PAT, prefisso cp_pat_) autentica l'API come te e sblocca l'intera superficie API. È il modo più semplice per iniziare.

Apri Workspace Settings

Vai su Workspace Settings → Integrations.

Apri la tab Personal Tokens

Seleziona Personal Tokens, poi Create new token.

Dagli un nome, scope e scadenza

Dai un nome al token, seleziona gli scope di cui ha bisogno e imposta una data di scadenza (fino a 1 anno).

Copia il token subito

Il token viene mostrato una sola volta. Copialo immediatamente e conservalo in un secret manager o in una variabile d'ambiente.

avviso

Tratta i token come password. Non committarli mai nel source control. Se un token viene esposto, eliminalo e creane uno nuovo.

Per il dettaglio completo di tipi di token e scope, vedi Autenticazione.

Passo 2 — Imposta la base URL

Tutti gli endpoint vivono sotto:

https://api.copera.ai/public/v1

Ogni richiesta deve includere il token nell'header Authorization con lo schema Bearer:

Authorization: Bearer cp_pat_your_token_here

Passo 3 — Fai la prima richiesta

Questo elenca le board a cui il token può accedere.

curl

curl https://api.copera.ai/public/v1/board/list-boards \
  -H "Authorization: Bearer cp_pat_your_token_here"

JavaScript

const res = await fetch(
  "https://api.copera.ai/public/v1/board/list-boards",
  {
    headers: {
      Authorization: "Bearer cp_pat_your_token_here",
    },
  },
);

if (!res.ok) {
  const error = await res.json();
  throw new Error(`${res.status}: ${error.message}`);
}

const boards = await res.json();
console.log(boards);

Una response 200 restituisce JSON. Un 401 significa che il token manca, è malformato o è scaduto — vedi Autenticazione. Altri fallimenti seguono lo schema di errore condiviso.

Passo 4 — Invia un messaggio (opzionale)

Se il token ha lo scope access_channels, puoi pubblicare su un channel:

curl -X POST \
  https://api.copera.ai/public/v1/chat/channel/{channelId}/send-message \
  -H "Authorization: Bearer cp_pat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hello from my integration!" }'

suggerimento

Abilita il Developer Mode per copiare gli ID delle risorse (channel, board, table, column) direttamente dall'interfaccia Copera — senza ispezionare il network.

Prossimi passi

• Autenticazione — tipi di token, scope e sicurezza.
• Paginazione — come gli endpoint list scorrono i risultati.
• Gestione errori — codici di stato e recovery.
• Rate limit — limiti per-endpoint e backoff.
• API Reference — ogni endpoint e schema.