API REST des tables de connaissances

Aperçu

Ce document décrit l'API HTTP exposée par KnowledgeTableApiController pour lire et écrire des tables de connaissances dans un espace de travail. Toutes les routes utilisent POST et des corps JSON sauf indication contraire.

L'API REST des tables de connaissances vous permet de lire et écrire des données dans les tables de connaissances de votre espace de travail Swiftask. Au lieu de gérer manuellement les tables via l'interface utilisateur, vous pouvez interroger, insérer, mettre à jour et gérer les schémas de table de manière programmatique en utilisant de simples requêtes HTTP.

Cette API est idéale pour intégrer les tables de connaissances Swiftask avec des applications externes, automatiser les flux de travail de données, ou créer des outils personnalisés qui ont besoin d'interagir avec les données de votre espace de travail.

Conditions préalables

1. Compte Swiftask avec accès à l'espace de travail cible.

2. Appartenance à l'espace de travail avec permission d'utiliser les tables de connaissances que vous appelez (l'API applique les mêmes règles d'accès que le produit).

3. Au moins une table de connaissances créée dans l'espace de travail (vous avez besoin du slug de chaque table). Les tables sont gérées à partir de la section Connaissances de l'application.

4. Authentification, choisissez l'une des options :

   • Clé API (recommandée pour les intégrations et scripts) : Créez et gérez les clés à /:workspaceId/profil/space-developper (Paramètres → Paramètres du compte → API). Chaque clé API est liée à un espace de travail. Stockez le secret de manière sécurisée ; il n'est affiché qu'une seule fois lors de sa création.

   • JWT de session (navigateur ou applications déjà connectées) : Utilisez le même modèle Authorization: Bearer si le jeton n'est pas reconnu comme clé API ; vous devez alors spécifier l'espace de travail (voir ci-dessous).

URL de base

Hôte GraphQL / REST de production :https://api.swiftask.fr .

Préfixez tous les chemins ci-dessous avec cette origine.

Le développement local utilise souvent http://localhost:4000 à la place.

Exemple : POST https://api.swiftask.fr/api/knowledge-table/query

En-têtes d'authentification

Spécificités des clés API

• Envoyez : Authorization: Bearer <votre-api-key>

• Ne comptez pas sur workspaceId dans le corps JSON pour changer d'espaces de travail lors de l'utilisation d'une clé API : l'espace de travail est toujours celui attaché à la clé.

• Les clés expirées reçoivent 401 avec le message API key expired.

Spécificités du JWT de session

• Si le jeton porteur n'est pas une clé API valide, le backend utilise l'utilisateur authentifié à partir du middleware de session.

• Vous devez fournir l'espace de travail via workspaceId dans le corps JSON (où le point de terminaison le supporte) ou x-workspace-id: <numeric-id> .

• Espace de travail manquant → 400 Missing workspaceId (body or x-workspace-id header).

Interroger les données avec SELECT

Le point de terminaison /api/knowledge-table/query vous permet de lire les données d'une table de connaissances en utilisant une syntaxe SELECT de type SQL.

Point de terminaison : POST /api/knowledge-table/query

Corps de la requête:

Réponse réussie (200 OK):

{
  "success": true,
  "data": {
    "columns": [{ "slug": "string", "dataType": "string" }],
    "rows": [{ "...": "cell values keyed by column slug" }]
  }
}

Réponse d’erreur (erreur de validation ou d’exécution):

{
  "success": false,
  "error": { "...": "structured error from the query engine" }
}

Grammaire de requête :

Grammaire de requete:

• SELECT * FROM <table_slug> : Sélectionner toutes les colonnes

• SELECT col1, col2 FROM <table_slug> : Sélectionner des colonnes spécifiques

• WHERE ... (optionnel) : Filtrer les lignes

• ORDER BY col [ASC|DESC], ... (optionnel) : Trier les résultats

• LIMIT <n> (optionnel) : Par défaut 100 s'il est omis

• OFFSET <n> (optionnel) : Ignorer les lignes

Les identificateurs (table_slug, noms de colonnes) sont mis en correspondance sans tenir compte de la casse par rapport aux slugs stockés.

Opérateurs WHERE supportés :

• Comparaison : =, !=, <, >, <=, >=

• LIKE, NOT LIKE : correspondance de motif de chaîne

• IN (...), NOT IN (...) : taille de liste limitée (max 100 valeurs)

• IS NULL, IS NOT NULL

• Regroupement booléen : AND, OR, NOT, parenthèses

Important : Seul SELECT est supporté. INSERT, UPDATE, DELETE ne sont pas acceptés par ce point de terminaison. Utilisez les points de terminaison d'écriture ci-dessous ou l'application.

Limites

• Lot de lignes par défaut : 100 lignes par requête si LIMIT est omis.

• Maximum absolu par requête : 1000 lignes (également limité par maxLimit s'il est fourni : le maximum effectif est min(maxLimit, 1000) ).

Exemple

POST /api/knowledge-table/query
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "query": "SELECT name, status FROM my_table WHERE status = 'open' ORDER BY name ASC LIMIT 50"
}

Obtenir le schéma de la table

Le point de terminaison /api/knowledge-table/schema retourne les définitions de colonnes pour une table.

Point de terminaison : POST /api/knowledge-table/schema

Corps de la requête :

Réponse réussie (200 OK):

{
  "success": true,
  "data": {
    "tableId": 1,
    "name": "Display name",
    "slug": "my_table",
    "columns": [
      {
        "id": 10,
        "name": "Title",
        "slug": "title",
        "order": 0,
        "dataType": "TEXT",
        "isRequired": false,
        "referencesColumnId": null,
        "referencedTableId": null,
        "selectOptions": null
      }
    ]
  }
}

404 si le slug de la table n'existe pas dans l'espace de travail.

Insérer plusieurs lignes

Le point de terminaison /api/knowledge-table/rows/batch-insert crée plusieurs lignes à la fois.

Point de terminaison : POST /api/knowledge-table/rows/batch-insert

Corps de la requête :

Corps de la requête :

Chaque élément de rows :

{
  "cells": [
    { "columnSlug": "title", "value": "Hello" },
    { "columnSlug": "parent", "referencedRowId": 42 }
  ]
}

• Utilisez value pour les valeurs scalaires / JSON / sélectionnées acceptées par le type de colonne.

• Pour les colonnes REFERENCE, utilisez referencedRowId (nombre ou null) au lieu de ou en même temps que value selon le cas.

Réponse réussie (200 OK) :

Réponse réussie (200 OK):

{
  "success": true,
  "data": { "rowIds": [101, 102] }
}

Mettre à jour les cellules d'une ligne

Le point de terminaison /api/knowledge-table/cells/upsert met à jour ou crée des valeurs de cellules pour une ligne existante.

Point de terminaison : POST /api/knowledge-table/cells/upsert

Corps de la requête:

Chaque cellule : { "columnSlug": "...", "value": ..., "referencedRowId": ... }

Réponse réussie (200 OK):

{
  "success": true,
  "data": { "rowId": 101 }
}

Créer une colonne

Le point de terminaison /api/knowledge-table/columns/create ajoute une nouvelle colonne à une table.

Point de terminaison : POST /api/knowledge-table/columns/create

Corps de la requête:

Valeurs dataType autorisées:

TEXT, NUMBER, BOOLEAN, DATE, DATETIME, JSON, REFERENCE, SELECT_OPTIONS

(insensible à la casse dans l'API ; stocké en majuscules).

Réponse réussie (200 OK):

{  "success": true,  "data": { "columnId": 12 }}

Supprimer une colonne

Le point de terminaison /api/knowledge-table/columns/delete supprime temporairement une colonne d'une table.

Point de terminaison : POST /api/knowledge-table/columns/delete

Corps de la requête:

Résumé des codes de statut HTTP

Exemple Node.js

Utilise le fetch intégré (Node.js 18+). Définissez SWIFTASK_API_KEY sur la clé de /:workspaceId/profil/space-developper.

const API_BASE = 'https://api.swiftask.fr';
const API_KEY = process.env.SWIFTASK_API_KEY; // never commit real keys

async function knowledgeTableQuery(query, maxLimit) {
  const body = { query };
  if (maxLimit != null) body.maxLimit = maxLimit;

  const res = await fetch(`${API_BASE}/api/knowledge-table/query`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  const data = await res.json();
  if (!res.ok) {
    throw new Error(data.error || JSON.stringify(data));
  }
  if (!data.success) {
    throw new Error(JSON.stringify(data.error));
  }
  return data.data; // { columns, rows }
}

async function knowledgeTableSchema(tableSlug) {
  const res = await fetch(`${API_BASE}/api/knowledge-table/schema`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tableSlug }),
  });

  const data = await res.json();
  if (!res.ok) throw new Error(data.error || JSON.stringify(data));
  return data.data;
}

// Usage
(async () => {
  const schema = await knowledgeTableSchema('my_table');
  console.log(schema.columns.map((c) => c.slug));

  const { rows } = await knowledgeTableQuery(
    "SELECT * FROM my_table WHERE status = 'open' LIMIT 10",
  );
  console.log(rows);
})();

Cas d'usage pratiques

Système de tickets d’assistance client

Construisez un agent d'assistance qui interroge votre table de connaissances pour les tickets ouverts, met à jour leur statut et enregistre les notes de résolution — tout sans quitter votre application.

// Get all open tickets
const { rows } = await fetch('https://api.swiftask.fr/api/knowledge-table/query', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: "SELECT id, subject, status FROM support_tickets WHERE status = 'open' ORDER BY created_at ASC"
  })
}).then(r => r.json()).then(d => d.data);

// Update a ticket status
await fetch('https://api.swiftask.fr/api/knowledge-table/cells/upsert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tableSlug: 'support_tickets',
    rowId: rows[0].id,
    cells: [
      { columnSlug: 'status', value: 'resolved' },
      { columnSlug: 'resolution_notes', value: 'Issue fixed in latest release' }
    ]
  })
}).then(r => r.json());

Pipeline de gestion des leads

Pipeline de gestion des leads

Ajoutez automatiquement des leads à votre table de connaissances, suivez leur statut à travers votre pipeline de vente et synchronisez avec les CRM externes.

// Add new leads in batch 
await fetch('https://api.swiftask.fr/api/knowledge-table/rows/batch-insert', {
 method: 'POST',
 headers: {
   'Authorization': 'Bearer YOUR_API_KEY',
   'Content-Type': 'application/json'
 },
 body: JSON.stringify({
   tableSlug: 'leads',
   rows: [
     {
       cells: [
         { columnSlug: 'name', value: 'Acme Corp' },
         { columnSlug: 'email', value: 'contact@acme.com' },
         { columnSlug: 'status', value: 'new' }
      ]
    }
  ]
 })
}).then(r => r.json());

Synchronisation des données

Gardez vos tables de connaissances Swiftask en synchronisation avec les bases de données externes ou les API en interrogeant régulièrement et en mettant à jour les lignes.

// Add new leads in batch
await fetch('https://api.swiftask.fr/api/knowledge-table/rows/batch-insert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tableSlug: 'leads',
    rows: [
      {
        cells: [
          { columnSlug: 'name', value: 'Acme Corp' },
          { columnSlug: 'email', value: 'contact@acme.com' },
          { columnSlug: 'status', value: 'new' }
        ]
      }
    ]
  })}).then(r => r.json());

Génération de formulaires dynamiques

Utilisez le point de terminaison du schéma pour générer dynamiquement des formulaires basés sur la structure de votre table, avec les types de champs appropriés et la validation.

// Query and export data
const schema = await fetch('https://api.swiftask.fr/api/knowledge-table/schema', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ tableSlug: 'inventory' })
}).then(r => r.json()).then(d => d.data);

const data = await fetch('https://api.swiftask.fr/api/knowledge-table/query', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'SELECT * FROM inventory WHERE quantity < 10'
  })
}).then(r => r.json()).then(d => d.data);

// Send to external system
await syncToExternalDatabase(schema, data);

Conseils et meilleures pratiques

Utilisez des slugs de table significatifs. Les slugs doivent être en minuscules, descriptifs et utiliser des traits de soulignement (p. ex., customerorders, supporttickets). Évitez les noms génériques comme table1 ou data.

Regroupez les opérations lorsque possible. Au lieu d'insérer des lignes une à la fois, utilisez batch-insert pour réduire les appels API et améliorer les performances.

Mettez en cache les informations de schéma. Le schéma de table change rarement. Mettez-le en cache dans votre application pour éviter les demandes de schéma répétées.

Validez les données avant de les envoyer. Vérifiez que les valeurs correspondent aux types de colonnes attendus (p. ex., les dates sont valides, les nombres sont numériques) avant de soumettre à l'API.

Gérez l'limitation de débit gracieusement. Implémentez une logique de backoff exponentiel et de nouvelle tentative pour les défaillances transitoires.

Gardez les clés API sécurisées. Ne validez jamais les clés API dans le contrôle de version. Utilisez les variables d'environnement et les outils de gestion des secrets.

Utilisez SELECT avec LIMIT. Incluez toujours une clause LIMIT lors de l'interrogation de grandes tables pour éviter les délais d'expiration. La valeur par défaut est 100 lignes, le maximum est 1000.

Ressources supplémentaires

• Base de connaissances – Apprenez à créer et gérer les tables de connaissances dans l'interface utilisateur

• Introduction à l'API – Obtenez votre clé API et votre ID d'espace de travail

• Documentation Swiftask – Documentation et guides de fonctionnalités complets