List API

This document describes how to use the API to retrieve a list of records from a table.

API Description

Retrieve a list of records from a table, supporting pagination, sorting, and filtering.

Request Method

GET /api/v1/bases/{base_id}/tables/{table_name}/records

Path Parameters

Parameter	Type	Description
base_id	string	Database ID
table_name	string	Table name

Query Parameters

Parameter	Type	Description	Default
page	number	Page number	1
limit	number	Records per page	15
filters	string	Filter conditions, format description	-
viewId	string	ID of the view content to return	-

Request Headers

x-bm-token: your_api_token

Example Requests

Basic Query

GET /api/bases/base123/tables/table456/records

Paginated Query

GET /api/bases/base123/tables/table456/records?page=2&limit=10

Filtered Query

GET /api/bases/base123/tables/table456/records?filters=W1sid2hlcmUiLCBbImFnZSIsICI+IiwgMThdXV0=

Response Format

Successful Response

{
  "current_page": 1,
  "data": [
    // records
  ],
  "per_page": 15,
  "total": 10,
  "last_page": 1,
  "count": 10
}

Error Response

{
  "message": "Invalid filter format"
}

Filter Conditions

Filter conditions are a base64 encoded string of condition arrays. Each condition contains two elements: an operator and an operand.

Operators

Operator	Description
where	Add filter condition
orderBy	Add sorting condition
select	Add field selection
with	Add related fields
withCount	Add related aggregation

Operands

Operand	Description	Example
"="	Equal to	["where", ["age", "=", 18]]
"!="	Not equal to	["where", ["age", "!=", 18]]
">"	Greater than	["where", ["age", ">", 18]]
">="	Greater than or equal to	["where", ["age", ">=", 18]]
"<"	Less than	["where", ["age", "<", 18]]
"<="	Less than or equal to	["where", ["age", "<=", 18]]
"in"	In list	["where", ["status", "in", ["active", "pending"]]]
"notin"	Not in list	["where", ["status", "notin", ["deleted"]]]
"like"	Contains	["where", ["name", "like", "test"]]
"notlike"	Does not contain	["where", ["name", "notlike", "test"]]
"isNull"	Is null	["where", ["description", "=", null]]
"isNotNull"	Is not null	["where", ["description", "!=", null]]

base64 Encoding

// SELECT * FROM users
// WHERE age > 18;

const encoded = btoa(JSON.stringify([
  ["where", ["age", ">", 18]]
]));

Conditions

// SELECT * FROM users
// WHERE age > 18 AND status = 'active';

const encoded = btoa(JSON.stringify([
  ["where", ["age", ">", 18]],
  ["where", ["status", "=", "active"]]
]));

Sorting

// SELECT * FROM users
// ORDER BY age DESC;

const encoded = btoa(JSON.stringify([
  ["orderBy", ["age", "desc"]]
]));

Field Selection

// SELECT name, age FROM users;

const encoded = btoa(JSON.stringify([
  ["select", ["name", "age"]]
]));

Relationships

const encoded = btoa(JSON.stringify([
  ["with", ["posts:id,title"]],
  ["with", ["comments"]],
]));

Related Aggregation

const encoded = btoa(JSON.stringify([
  ["withCount", ["posts"]]
]));

Compound Conditions

Multiple conditions can be combined:

const encoded = btoa(JSON.stringify([
  ["select", ["id", "title", "description"]],
  ["with", ["author:id,name"]],
  ["withCount", ["comments", [
    ["where", ["status", "=", "active"]]
  ]]],
  ["where", ["vote", ">", 10]],
  ["orderBy", ["votes", "desc"]]
]));

fetch(`/api/v1/bases/base123/tables/posts/records?filters=${encoded}`)

// response
{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "title": "Post 1",
      "description": "Description 1",
      "comments_count": 5,
      "author": {
        "id": 1,
        "name": "Alice"
      }
    }
    // ...
  ],
  "per_page": 15,
  "total": 10,
  "last_page": 1,
  "count": 10
}

Notes

1. The maximum number of records per page is 100
2. Complex filter conditions may affect query performance
3. Related field data needs to be retrieved using specific query parameters