Nextcloud Tables API

Integration with Nextcloud Tables for CRUD operations, table schema management, row pagination, and server-side authentication proxying.

Last updated: 2025-02-18

Nextcloud Tables API

Certexi integrates with Nextcloud Tables for structured data management. All API calls are proxied server-side to avoid CORS issues and protect credentials.

Authentication

All requests require Nextcloud authentication headers:

Authorization: Bearer <token> | Basic <credentials>
X-NextCloud-Instance: https://cloud.example.com
X-NextCloud-Username: username

The API supports OAuth Bearer tokens with automatic App Password fallback.

Table Operations

GET/api/tables

List all tables

Returns all tables accessible to the authenticated user with metadata.

{
  "success": true,
  "data": {
    "tables": [
      {
        "id": 1,
        "title": "Shipments",
        "emoji": "📦",
        "rowsCount": 150,
        "columnsCount": 8,
        "lastEditAt": "2024-01-15T10:30:00Z",
        "ownerDisplayName": "John Doe"
      }
    ],
    "count": 1
  }
}
GET/api/tables/:tableId

Get table details with schema

Returns full table information including column schema, statistics, and sample rows.

The schema includes column types, validation rules, and display configuration:

{
  "schema": [
    {
      "id": 1,
      "title": "Shipment ID",
      "type": "text",
      "mandatory": true,
      "textAllowedPattern": "^[A-Z]{2}[0-9]{6}$",
      "textMaxLength": 8
    },
    {
      "id": 2,
      "title": "Weight",
      "type": "number",
      "numberMin": 0,
      "numberMax": 1000,
      "numberDecimals": 2,
      "numberSuffix": "kg"
    }
  ]
}
POST/api/tables

Create a new table

{
  "title": "New Shipments Table",
  "emoji": "📦",
  "template": "custom",
  "description": "Table for tracking shipment data"
}

Title is required (max 200 characters). Returns the created table with its ID.

PUT/api/tables/:tableId

Update table metadata

Update title, emoji, or description. Only provided fields are changed.

DELETE/api/tables/:tableId

Delete a table

🚨

Destructive Operation

Deleting a table permanently removes all rows and column definitions. This action cannot be undone.

Row Operations

GET/api/tables/:tableId/rows

Get paginated rows

Supports pagination with limit (1–1000, default 50) and offset parameters.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "data": { "1": "SH123456", "2": 25.5 },
        "createdBy": "user123",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
POST/api/tables/:tableId/rows

Create a row

Data is provided as column ID to value mapping:

{
  "data": {
    "1": "SH789012",
    "2": 45.2,
    "3": "Los Angeles"
  }
}
PUT/api/tables/:tableId/rows/:rowId

Update a row

Only provided column values are updated. Omitted columns remain unchanged.

DELETE/api/tables/:tableId/rows/:rowId

Delete a row

Permanently removes the row from the table.

TypeScript Client

Certexi provides a typed API client for frontend integration:

import {
  tablesApiClient,
  configureTablesApiClient,
} from '@/lib/nextcloud/tables-api-client';

configureTablesApiClient({
  Authorization: 'Bearer your_token',
  'X-NextCloud-Instance': 'https://cloud.example.com',
  'X-NextCloud-Username': 'username',
});

const { tables } = await tablesApiClient.getTables();
const { items: rows } = await tablesApiClient.getRows(tableId, { limit: 100 });
const newRow = await tablesApiClient.createRow(tableId, {
  data: { '1': 'Value' },
});

Error Codes

CodeDescription
INVALID_TABLE_IDTable ID is not a valid integer
INVALID_ROW_IDRow ID is not a valid integer
MISSING_TITLETable title is required for creation
TITLE_TOO_LONGTitle exceeds 200 characters
INVALID_ROW_DATARow data is missing or malformed
EMPTY_ROW_DATARow data object has no entries
NEXTCLOUD_API_ERRORError from upstream Nextcloud API
CONNECTION_ERRORCannot connect to Nextcloud instance

Security

  • All Nextcloud API calls are proxied server-side
  • Credentials are never exposed to the browser
  • Input validation on all request parameters
  • Rate limiting protects against API abuse
  • Error responses are sanitized to prevent information leakage

Related

Nextcloud Tables API | Certexi Docs