PUT/v1/cards-by-external-id/{external_id}

Creare o sostituire una scheda tramite ID esterno

upsert_card_by_external_id

Crea o sostituisce una scheda in base all’external_id dell’integratore. Invia il testo come application/json (CardTextUpsert) o un file come multipart/form-data (CardFileUpsertForm, con gli stessi controlli dei file di POST /v1/cards). Se l’organizzazione non ha una scheda con questo external_id, la scheda viene creata nella raccolta e nella cartella indicate nel corpo (201). Altrimenti il contenuto viene sostituito con una nuova versione e indicizzato di nuovo come una nuova versione di un file, e i dettagli della scheda (titolo, tag, responsabile, categoria, metadata) assumono i valori passati (200). Un contenuto invariato non crea una nuova versione (status: skipped, reason: unchanged), quindi ripetere la richiesta è sicuro anche senza Idempotency-Key. Se viene passato, metadata sostituisce l’intero oggetto. L’accesso viene controllato come per un caricamento quando la scheda viene creata e come per un aggiornamento della scheda quando viene sostituita. Il contenuto di una scheda visibile solo in parte a chi effettua la chiamata non viene sostituito (403 cards.content_whole_access). Le schede delle fonti non vengono sovrascritte in questo modo: se l’external_id appartiene a un documento di una fonte personalizzata o la scheda trovata è gestita da una fonte, la richiesta restituisce 409 cards.managed_by_source. La modifica del contenuto rimuove la verifica della scheda, come qualsiasi nuova versione (motivo update).

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di percorso

external_idstringobbligatorio
external_id della scheda: una stringa di 1–512 caratteri, univoca nell’organizzazione.
length ≥ 1, length ≤ 512

Parametri di intestazione

X-View-Asstring
Solo per le chiavi API con il ruolo admin. Esegue la richiesta come il profilo dati <profile>[:viewer|verifier|editor], ad esempio employee:viewer. La chiave di installazione non può usare questa intestazione (403).

Parametri cookie

kb_view_asstring
Cookie della modalità “View as” per una sessione. POST /auth/view-as lo imposta e DELETE /auth/view-as lo cancella.

Corpo della richiesta

application/json

Oggetto: CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringobbligatorio
Testo della scheda nel formato content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
Raccolta per nome, alla creazione della scheda. Per impostazione predefinita, la raccolta predefinita dell’installazione.
collection_idinteger | null
Raccolta per ID, alla creazione della scheda. Quando viene passato anche collection, prevale collection_id.
folder_idstring | null
Cartella della raccolta per la nuova scheda, con gli stessi controlli del folder_id di un caricamento di file.
length ≤ 64
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
metadataMetadataPatch
asyncboolean
true: la risposta arriva subito e la scheda viene indicizzata in coda; false: la risposta arriva dopo l’indicizzazione.
Predefinito: false

multipart/form-data

Oggetto: CardFileUpsertForm

filestring (application/octet-stream)obbligatorio
titlestring | null
Titolo della scheda. Se non viene passato, una nuova scheda riceve il nome del file e una scheda esistente mantiene il suo titolo.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
Tag separati da virgole.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
metadata: un oggetto JSON come valore del campo del modulo. Le regole sono quelle di MetadataPatch.
asyncboolean
Predefinito: false

Risposte

200La scheda esisteva già. Il suo contenuto è stato sostituito (`queued`, `ready`, `error`) oppure non è cambiato (`skipped`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: UploadResult

statusstringobbligatorio
Valori ammessi: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged o an identical file is already indexed.
tablesinteger
timingsobject
Campi
- total_snumber
errorstring

201La scheda è stata creata (`queued` per una richiesta asincrona, `ready` o `error` per una sincrona).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: UploadResult

statusstringobbligatorio
Valori ammessi: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged o an identical file is already indexed.
tablesinteger
timingsobject
Campi
- total_snumber
errorstring

400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

402L’organizzazione ha raggiunto un limite del piano (schede, spazio di archiviazione o utenti). `error.details` contiene `kind`, `limit` e `used`.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

404L’oggetto non esiste o non è disponibile per te. L’API non conferma l’esistenza di un oggetto con accesso limitato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

409Lo stato dell’oggetto non consente l’azione, ad esempio un duplicato, un’indicizzazione in corso o un job già elaborato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

413Il corpo della richiesta supera la dimensione consentita.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

415Il formato del file non è supportato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

Retry-After
Numero di secondi da attendere prima di ripetere la richiesta.
RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

503Un servizio da cui dipende questa richiesta non è temporaneamente disponibile. Riprova più tardi.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← cards · Riferimento API

curl -X PUT 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body":"# Refund policy\n\nRefunds are processed within 14 days.","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

Chiave API

La chiave resta nella memoria di questa scheda del browser e viene inviata solo a https://api.sursa.com.

Le richieste vengono eseguite sui dati reali della tua organizzazione.

X-View-As header

external_id path *

Corpo della richiesta (JSON)