Knowledge Table REST API

Overview

This document describes the HTTP API exposed by KnowledgeTableApiController for reading and writing Knowledge tables in a workspace. All routes use POST and JSON bodies unless noted.

The Knowledge Table REST API allows you to read and write data in Knowledge tables within your Swiftask workspace. Instead of manually managing tables through the UI, you can programmatically query, insert, update, and manage table schemas using simple HTTP requests.

This API is ideal for integrating Swiftask Knowledge tables with external applications, automating data workflows, or building custom tools that need to interact with your workspace data.

Prerequisites

1. Swiftask account with access to the target workspace.

2. Workspace membership with permission to use the Knowledge tables you call (the API enforces the same access rules as the product).

3. At least one Knowledge table created in the workspace (you need each table’s slug). Tables are managed from the Knowledge section of the app.

4. Authentication, choose one:

   • API key (recommended for integrations and scripts)
     Create and manage keys at /:workspaceId/profil/space-developper (Settings → Account Settings→ API).
     Each API key is bound to a workspace. Store the secret securely; it is shown only once when created.

   • Session JWT (browser or apps already logged in): same Authorization: Bearer <jwt> pattern when the token is not recognized as an API key; then you must specify the workspace (see below).

Base URL

Production GraphQL / REST host: https://api.swiftask.fr.

Prefix all paths below with this origin.

Local development often uses http://localhost:4000 instead.

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

Authentication headers

API key specifics

• Send: Authorization: Bearer <your-api-key>

• Do not rely on workspaceId in the JSON body to switch workspaces when using an API key: the workspace is always the one attached to the key.

• Expired keys receive 401 with message API key expired.

Session JWT specifics

• If the bearer token is not a valid API key, the backend uses the authenticated user from session middleware.

• You must supply the workspace via workspaceId in the JSON body (where the endpoint supports it) or x-workspace-id: <numeric-id>.

• Missing workspace → 400 Missing workspaceId (body or x-workspace-id header).

Query data with SELECT

The /api/knowledge-table/query endpoint allows you to read data from a Knowledge table using a SQL-like SELECT syntax.

Endpoint: POST /api/knowledge-table/query

Request body:

Successful response (200 OK):

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

Error response (validation or execution error):

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

Query grammar:

• SELECT * FROM <table_slug> : Select all columns

• SELECT col1, col2 FROM <table_slug> : Select specific columns

• WHERE ... (optional) : Filter rows

• ORDER BY col [ASC|DESC], ... (optional) : Sort results

• LIMIT <n> (optional) : Default 100 if omitted

• OFFSET <n> (optional) : Skip rows

Identifiers (table_slug, column names) are matched case-insensitively against stored slugs.

Supported WHERE operators:

• Comparison: =, !=, <, >, <=, >=

• LIKE, NOT LIKE (string pattern matching)

• IN (...), NOT IN (...) : list size limited (max 100 values)

• IS NULL, IS NOT NULL

• Boolean grouping: AND, OR, NOT, parentheses

Important: Only SELECT is supported. INSERT, UPDATE, DELETE are not accepted by this endpoint. Use the write endpoints below or the app.

Limits

• Default row batch: 100 rows per query if LIMIT is omitted.

• Hard maximum per query: 1000 rows (also capped by maxLimit if provided: effective max is min(maxLimit, 1000)).

Example

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"
}

Get table schema

The /api/knowledge-table/schema endpoint returns column definitions for a table.

Endpoint: POST /api/knowledge-table/schema

Request body:

Successful response (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 if the table slug does not exist in the workspace.

Insert multiple rows

The /api/knowledge-table/rows/batch-insert endpoint creates multiple rows at once.

Endpoint: POST /api/knowledge-table/rows/batch-insert

Request body:

Each element of rows:

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

• Use value for scalar / JSON / select values as accepted by the column type.

• For REFERENCE columns, use referencedRowId (number or null) instead of or alongside value as applicable.

Successful response (200 OK):

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

Update cells on a row

The /api/knowledge-table/cells/upsert endpoint updates or creates cell values for an existing row.

Endpoint: POST /api/knowledge-table/cells/upsert

Request body:

Each cell: { "columnSlug": "...", "value": ..., "referencedRowId": ... }

Successful response (200 OK):

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

Create a column

The /api/knowledge-table/columns/create endpoint adds a new column to a table.

Endpoint: POST /api/knowledge-table/columns/create

Request body:

Allowed dataType values:

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

(case-insensitive in the API; stored uppercase).

Successful response (200 OK):

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

Delete a column

The /api/knowledge-table/columns/delete endpoint soft-deletes a column from a table.

Endpoint: POST /api/knowledge-table/columns/delete

Request body:

HTTP status summary

Node.js example

Uses the built-in fetch (Node.js 18+). Set SWIFTASK_API_KEY to the key from /: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);
})();

Practical Use Cases

Customer support ticket system

Build a support agent that queries your Knowledge table for open tickets, updates their status, and logs resolution notes—all without leaving your 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());

Lead management pipeline

Automatically add leads to your Knowledge table, track their status through your sales pipeline, and sync with external CRMs.

// 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());

Data synchronization

Keep your Swiftask Knowledge tables in sync with external databases or APIs by querying regularly and updating rows.

// 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());

Dynamic form generation

Use the schema endpoint to dynamically generate forms based on your table structure, with proper field types and 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);

Tips & Best Practices

Use meaningful table slugs. Slugs should be lowercase, descriptive, and use underscores (e.g., customer_orders, support_tickets). Avoid generic names like table1 or data.

Batch operations when possible. Instead of inserting rows one at a time, use batch-insert to reduce API calls and improve performance.

Cache schema information. The table schema rarely changes. Cache it in your application to avoid repeated schema requests.

Validate data before sending. Check that values match the expected column types (e.g., dates are valid, numbers are numeric) before submitting to the API.

Handle rate limiting gracefully. Implement exponential backoff and retry logic for transient failures.

Keep API keys secure. Never commit API keys to version control. Use environment variables and secrets management tools.

Use SELECT with LIMIT. Always include a LIMIT clause when querying large tables to avoid timeouts. Default is 100 rows, maximum is 1000.

Additional Resources

• Knowledge Base – Learn how to create and manage Knowledge tables in the UI

• API Introduction – Get your API key and workspace ID

• Swiftask Documentation – Full feature documentation and guides