REST APIs
NocoDB gives a full set of REST APIs. Use them to work with your data, metadata, and workspace resources from code. With these APIs, you can:
- integrate NocoDB with external applications
- automate workflows
- build custom tools
- manage your bases at scale
You can query records, update fields, manage tables, or get metadata. The NocoDB APIs are clear and consistent, for simple and for advanced use cases. This page gives the available API types, tells how to build endpoints, and shows where to find the IDs for your requests.
Use this reference as your starting point to build reliable integrations with the NocoDB APIs.
The where clause of the v3 APIs is slightly different from the where clause of the earlier version. Refer to v3 Where Clause.
Finding Your API IDs
Before you make API calls, find and copy the IDs that your endpoints need. This section tells you where to find each ID.
Workspace ID
Workspace ID is a unique alphanumeric identifier for your workspace in NocoDB. It starts with w (for workspace). It shows in the URL bar when you open a base in the workspace.
You can also find it in the workspace switcher, at the top of the workspace sidebar. Click the ID to copy it to your clipboard.
The Workspace ID also shows in Settings > General > Appearance.
Base ID
Metadata APIs and administrative operations need the Base ID. It is a unique identifier for one database (or base) in your workspace.
The Base ID is an alphanumeric identifier that starts with p (for project). It shows in the URL when you open a table or the base settings. You can also find it in the base context menu in the left sidebar. To open this menu, click the chevron next to the base name. Click the ID to copy it to your clipboard.
Table ID
Table ID is the identifier that you use most. All data API calls need it. It is a unique identifier for one table in your base.
The Table ID is an alphanumeric string that starts with m (for model). When you open a table, it shows in the URL, immediately after the Base ID. You can also find it in the table context menu in the left sidebar. To open this menu, click the three dots next to the table name. Click the ID to copy it to your clipboard.
View ID
Use the View ID for API operations on a view, for example to get records from one view. It is a unique identifier for one view in a table.
The View ID is an alphanumeric string that starts with v (for view). It shows in the URL when a view is open. You can also find it in the view context menu in the left sidebar. To open this menu, click the three dots next to the view name. Click the ID to copy it to your clipboard.
You can also get the View ID from the view toolbar > more actions (3 dots) menu.
Field ID
Use the Field ID for API operations on a field, for example to update field properties. It is a unique identifier for one column in a table.
The Field ID is an alphanumeric string that starts with c (for column). It shows in the URL when you view or edit the settings of a field. You can also find it in the field context menu in the field header bar. To open this menu, click the chevron next to the field name. Click the ID to copy it to your clipboard.
You can also get the Field ID from Tools > Manage fields.
Record ID
Use the Record ID for API operations on a record, for example to get or update one record. It is a unique identifier for one row in a table.
By default, the Record ID is a number that starts at 1. The ID field shows the Record ID. To show the ID field, do these steps:
- In the toolbar, open the Fields menu.
- Enable Show System Fields.
You can also find it in the URL when you open a record (expanded record view).
You can also use the Record ID in formulas. In the formula editor, select ID from the list of available fields, or use the RECORD_ID() function.
User ID
Use the User ID for API operations on a user, for example to get user details. It is a unique identifier for one user in your workspace or organization.
The User ID is an alphanumeric string that starts with u (for user). To find it, open the Workspace Members page or the Base Members page. Then click the three dots menu next to the name of the user. Click the ID to copy it to your clipboard.
Data Source ID
For external data sources that are connected to NocoDB (for example Postgres or MySQL), data API operations also need the Data Source ID.
The Data Source ID is a unique alphanumeric string for the connected data source. To find it, click the three dots next to the data source name in the left sidebar. The context menu opens. Click the ID to copy it to your clipboard.
You can also find it on the Data Source settings page.
Rate Limits
NocoDB APIs have rate limits. The limits keep usage fair and performance good for all users. The default rate limit is 5 requests per second per user. These limits are the same on all plans.
If you go above these limits, the API returns a 429 status code (Too Many Requests). Wait 30 seconds before you send more requests.
To keep good service performance, NocoDB can change these limits or add more rate tiers for pricing plans.
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. For a descending sort, use - as a prefix | column_name | |
| fields | f | Required column names in result | * | column_name1,column_name2 |
| shuffle | r | Shuffle the result for pagination | 0 | 1 (Only 0 or 1. NocoDB reads other values 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,...) |
btw and nbtw do not work on Number, Decimal, Currency, Percent, Rating, Duration, Date, DateTime, and Checkbox fields. Instead, write the range with two bounds: (price,gte,10)~and(price,lte,100). This works on all field types that can have a range.
Comparison Sub-Operators
These sub-operators are available in 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) |
in matches one of several exact dates. Write the exactDate sub-operator, then a comma-separated list: (colName,in,exactDate,2022-02-02,2022-03-04).
For isWithin in Date and DateTime columns, use these different sub-operators.
| 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
In the v3 data API, the where clause is slightly different from the earlier versions. You can put values in quotes: double quotes, single quotes, or backticks. Then you can safely use special characters that can break the where clauses of earlier versions. This helps most with strings that contain commas, parentheses, or other delimiters.
Example: Search for a phrase with special characters:
("My Field", like, "Let's come home, and go straight to bed")
Another Example: Search for a value that has a comma:
("Product Name", eq, "Laptop, 15-inch")
Example: Use single quotes for a value:
(City, eq, 'New York')
Usage on v2 API
You can also use the v3 where clause with the v2 API. Put an @ sign before the where clause. Then you can use the advanced functions of the v3 where clause in v2 API calls.
Example: Use a v3 where clause to find titles that are not blank, in a v2 API call:
@("Title", not, blank)
Another Example: Combine multiple conditions with special characters in a v2 API call:
@("Description", like, "High-performance, water-resistant")
Availability
- Collaboration Meta APIs are available on NocoDB Cloud (Business plan and above) and on licensed self-hosted deployments (Business plan and above).
- View and Script Meta APIs are available on NocoDB Cloud (Enterprise plan) and on licensed self-hosted deployments (Business plan and above).
Last updated on