REST APIs
NocoDB REST API Overview
Once you've created the schemas, you can manipulate the data or invoke actions using the REST APIs. We provide several types of APIs for different usages. Refer to the following links for more details:
You will need an API key and endpoint to use the API. The endpoint URL for hosted instances of NocoDB is in the format https://app.nocodb.com/api/v2/tables/TABLEID/records and https://app.nocodb.com/api/v2/meta/bases/BASEID/info.
- You can find a TABLEID by going to any table in NocoDB > Details > API Snippets.
- You can find your BASEID by clicking the menu icon next to any database, rest APIs > and seeing the BASEID in the url.
Additional information on the REST APIs is provided below.
- When querying using v3 apis, see v3 Where Clause for a slight difference between the two version's where clause.
Query params
| Name | Alias | Use case | Default value | Example value |
|---|---|---|---|---|
| where | w | Complicated where conditions | (colName,eq,colValue)~or(colName2,gt,colValue2) Usage: Comparison operators Usage: Logical operators | |
| limit | l | Number of rows to get (SQL limit value) | 10 | 20 |
| offset | o | Offset for pagination (SQL offset value) | 0 | 20 |
| sort | s | Sort by column name, Use - as a prefix for descending sort | column_name | |
| fields | f | Required column names in result | * | column_name1,column_name2 |
| shuffle | r | Shuffle the result for pagination | 0 | 1 (Only allow 0 or 1. Other values would see it as 0) |
Comparison Operators
| Operation | Meaning | Example |
|---|---|---|
| eq | equal | (colName,eq,colValue) |
| neq | not equal | (colName,neq,colValue) |
| not | not equal (alias of neq) | (colName,not,colValue) |
| gt | greater than | (colName,gt,colValue) |
| ge | greater or equal | (colName,ge,colValue) |
| lt | less than | (colName,lt,colValue) |
| le | less or equal | (colName,le,colValue) |
| is | is | (colName,is,true/false/null) |
| isnot | is not | (colName,isnot,true/false/null) |
| in | in | (colName,in,val1,val2,val3,val4) |
| btw | between | (colName,btw,val1,val2) |
| nbtw | not between | (colName,nbtw,val1,val2) |
| like | like | (colName,like,%name) |
| nlike | not like | (colName,nlike,%name) |
| isWithin | is Within (Available in Date and DateTime only) | (colName,isWithin,sub_op) |
| allof | includes all of | (colName,allof,val1,val2,...) |
| anyof | includes any of | (colName,anyof,val1,val2,...) |
| nallof | does not include all of (includes none or some, but not all of) | (colName,nallof,val1,val2,...) |
| nanyof | does not include any of (includes none of) | (colName,nanyof,val1,val2,...) |
Comparison Sub-Operators
The following sub-operators are available in the Date and DateTime columns.
| Operation | Meaning | Example |
|---|---|---|
| today | today | (colName,eq,today) |
| tomorrow | tomorrow | (colName,eq,tomorrow) |
| yesterday | yesterday | (colName,eq,yesterday) |
| oneWeekAgo | one week ago | (colName,eq,oneWeekAgo) |
| oneWeekFromNow | one week from now | (colName,eq,oneWeekFromNow) |
| oneMonthAgo | one month ago | (colName,eq,oneMonthAgo) |
| oneMonthFromNow | one month from now | (colName,eq,oneMonthFromNow) |
| daysAgo | number of days ago | (colName,eq,daysAgo,10) |
| daysFromNow | number of days from now | (colName,eq,daysFromNow,10) |
| exactDate | exact date | (colName,eq,exactDate,2022-02-02) |
For isWithin in Date and DateTime columns, the different set of sub-operators are used.
| Operation | Meaning | Example |
|---|---|---|
| pastWeek | the past week | (colName,isWithin,pastWeek) |
| pastMonth | the past month | (colName,isWithin,pastMonth) |
| pastYear | the past year | (colName,isWithin,pastYear) |
| nextWeek | the next week | (colName,isWithin,nextWeek) |
| nextMonth | the next month | (colName,isWithin,nextMonth) |
| nextYear | the next year | (colName,isWithin,nextYear) |
| nextNumberOfDays | the next number of days | (colName,isWithin,nextNumberOfDays,10) |
| pastNumberOfDays | the past number of days | (colName,isWithin,pastNumberOfDays,10) |
Logical Operators
| Operation | Example |
|---|---|
| ~or | (checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,2000)) |
| ~and | (checkNumber,eq,JM555205)~and((amount,gt,200)~and(amount,lt,2000)) |
| ~not | ~not(checkNumber,eq,JM555205) |
v3 Where Query Parameter
When calling v3 data api, the where clause has a slight difference with the previous versions. It allows values to be wrapped with quotes (double quotes, single quotes, or backticks) to safely use special characters that might otherwise break older version where clauses. This is particularly useful for strings containing commas, parentheses, or other delimiters.
Example: Searching for a phrase with special characters:
("My Field", like, "Let's come home, and go straight to bed")
Another Example: Searching for a value that includes a comma:
("Product Name", eq, "Laptop, 15-inch")
Example: Using single quotes for a value:
(City, eq, 'New York')
Usage on v2 API
The v3 where clause can also be utilized when using the v2 API by prepending the where clause with an @ sign. This allows you to leverage the advanced capabilities of the v3 where clause even in v2 API calls.
Example: Using a v3 where clause to check for non-blank titles in a v2 API call:
@("Title", not, blank)
Another Example: Combining multiple conditions with special characters in a v2 API call:
@("Description", like, "High-performance, water-resistant")