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

Créer ou remplacer une fiche par identifiant externe

upsert_card_by_external_id

Crée ou remplace une fiche d’après l’external_id de l’intégrateur. Envoyez du texte en application/json (CardTextUpsert) ou un fichier en multipart/form-data (CardFileUpsertForm, avec les mêmes vérifications de fichier que POST /v1/cards). Si l’organisation n’a aucune fiche avec cet external_id, la fiche est créée dans la collection et le dossier indiqués dans le corps (201). Sinon, le contenu est remplacé par une nouvelle version et indexé de nouveau comme une nouvelle version de fichier, et les données de la fiche (titre, étiquettes, responsable, catégorie, metadata) prennent les valeurs transmises (200). Un contenu inchangé ne crée pas de nouvelle version (status: skipped, reason: unchanged) : répéter la requête est donc sans risque, même sans Idempotency-Key. Lorsque metadata est transmis, il remplace l’objet entier. L’accès est vérifié comme pour un téléversement lorsque la fiche est créée, et comme pour une modification de fiche lorsqu’elle est remplacée. Le contenu d’une fiche que l’appelant ne voit qu’en partie n’est pas remplacé (403 cards.content_whole_access). Les fiches des sources ne sont pas écrasées de cette manière : si l’external_id appartient à un document d’une source personnalisée, ou si la fiche trouvée est gérée par une source, la requête renvoie 409 cards.managed_by_source. La modification du contenu retire la validation de la fiche, comme toute nouvelle version (motif update).

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

external_idstringobligatoire
external_id de la fiche : une chaîne de 1 à 512 caractères, unique dans l’organisation.
length ≥ 1, length ≤ 512

Paramètres d’en-tête

X-View-Asstring
Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

kb_view_asstring
Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringobligatoire
Texte de la fiche au format content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
Collection par nom, à la création de la fiche. Par défaut, la collection par défaut de l’installation.
collection_idinteger | null
Collection par ID, à la création de la fiche. Si collection est aussi transmis, collection_id l’emporte.
folder_idstring | null
Dossier de la collection pour la nouvelle fiche, avec les mêmes vérifications que folder_id d’un téléversement de fichier.
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 répond immédiatement et indexe la fiche dans la file d’attente ; false répond après l’indexation.
Par défaut : false

multipart/form-data

Objet : CardFileUpsertForm

filestring (application/octet-stream)obligatoire
titlestring | null
Titre de la fiche. S’il n’est pas transmis, une nouvelle fiche reçoit le nom du fichier et une fiche existante conserve son titre.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
Étiquettes séparées par des virgules.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
metadata : un objet JSON comme valeur du champ de formulaire. Les règles sont celles de MetadataPatch.
asyncboolean
Par défaut : false

Réponses

200La fiche existait déjà. Son contenu a été remplacé (`queued`, `ready`, `error`) ou n’a pas changé (`skipped`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : UploadResult

statusstringobligatoire
Valeurs autorisées: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged ou an identical file is already indexed.
tablesinteger
timingsobject
Champs
- total_snumber
errorstring

201La fiche a été créée (`queued` pour une requête asynchrone, `ready` ou `error` pour une requête synchrone).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : UploadResult

statusstringobligatoire
Valeurs autorisées: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged ou an identical file is already indexed.
tablesinteger
timingsobject
Champs
- total_snumber
errorstring

400La requête est invalide : la valeur d’un paramètre ou l’état de l’objet ne permet pas l’action (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

402L’organisation a atteint une limite de son offre (fiches, stockage ou utilisateurs). `error.details` contient `kind`, `limit` et `used`.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

409L’état de l’objet ne permet pas l’action, par exemple un doublon, une indexation en cours ou un job déjà traité.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

413Le corps de la requête dépasse la taille autorisée.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

415Le format du fichier n’est pas pris en charge.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

Retry-After
Nombre de secondes à attendre avant de réessayer la requête.
RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

503Un service dont dépend cette requête est temporairement indisponible. Réessayez plus tard.

En-têtes de la réponse

RateLimit-Policy
Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.
RateLimit
Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).
X-RateLimit-Remaining
Requêtes restantes au titre de la limite la plus stricte.
X-RateLimit-Reset
Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← cards · Référence de l’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"

Essayer

Clé API

La clé reste dans la mémoire de cet onglet et n’est envoyée qu’à https://api.sursa.com.

Les requêtes agissent sur les données réelles de votre organisation.

X-View-As header

external_id path *

Corps de la requête (JSON)