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 projects 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 project 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 project.
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 Project 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.
Request IDs
Outside the Community Edition, every NocoDB API error response carries an x-request-id header. In the v3 APIs, the error body also has a requestId field with the same value. Send this id with a bug report. It names the exact call that failed.
To use an id of your own, set an x-request-id header on the request. NocoDB keeps your value when it is 100 characters or less and has only letters, digits, _, ., :, and -. For any other value, NocoDB uses an id of its own.
Record ids in a DELETE query parameter
Some HTTP clients and proxies remove the body of a DELETE request. The two v3 data endpoints that delete a list of records also read the record ids from a records query parameter. Repeat the parameter for each id.
To delete records:
DELETE /api/v3/data/{baseId}/{tableId}/records?records=12&records=13To unlink linked records from one record:
DELETE /api/v3/data/{baseId}/{tableId}/links/{linkFieldId}/{recordId}?records=4&records=5If a request has record ids in the body and in the query parameter, NocoDB uses both sets.
Paging the base list
GET /api/v3/meta/workspaces/{workspaceId}/bases returns every base in the workspace. To get one page instead, send limit with the number of bases you want, and offset with the number to skip. NocoDB ignores offset when you send no limit.
Each response has a pageInfo object beside list. totalRows counts every base that you can see in the workspace. pageSize is the page size that NocoDB applied. It is smaller than your limit when the deployment caps it, so page with pageSize and not with the limit that you sent. A self-hosted deployment sets this cap with NC_DB_QUERY_LIMIT_MAX.
An offset at or above totalRows returns an error, not an empty page.
Paging records
The v3 record and link endpoints return next and prev URLs beside records. Follow next until it is null.
A page after the last record is not an error. The response has an empty records list and a null next. Its prev points at the last page that has records, or at page 1 when the result set is empty. The base list above is different: there, an offset past the end returns an error.
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 take two numbers on Number, Decimal, Currency, Percent, Rating, and Duration fields: (price,btw,10,100). They do not work on Date, DateTime, and Checkbox fields. On a Date or DateTime field, write the range with two bounds: (dueDate,gte,exactDate,2026-01-01)~and(dueDate,lte,exactDate,2026-03-31).
The v3 filter endpoints check each condition when you save it. A condition that names a field the table does not have, or an operator the field type does not support, is refused with ERR_FILTER_VERIFICATION_FAILED. The stored filters do not change.
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