# API v3 Implementation Summary
## Overview
The MCP server has been updated to use **NocoDB API v3 as the primary API**, with automatic fallback to v2 for compatibility. This aligns with the [NocoDB 0.264.0 release](https://github.com/nocodb/nocodb/releases/tag/0.264.0) which introduced API v3.
## API v3 Features (from 0.264.0 Release)
According to the [official release notes](https://github.com/nocodb/nocodb/releases/tag/0.264.0), API v3 provides:
### Key Improvements
1. **Embedded Relation Field Data**
- Listing records returns paginated linked records inline
- Reduces need for multiple API calls
- More efficient data retrieval
2. **Unified Record Linking in CRUD**
- Create or update record links directly in the main API call
- No more separate link/unlink operations
- Simplified workflow management
3. **Standardized Responses & Errors**
- More predictable response envelopes
- Consistent status codes
- Better error handling across operations
### Benefits
- 🚀 **Reduced API Traffic** - Fewer HTTP calls thanks to embedded relations
- 🔄 **Simplified Workflows** - Handle records and relationships in single requests
- 📘 **Better Documentation** - Standardized API structure
## Endpoint Structure
### API v3 Endpoints (Primary)
**Meta APIs:**
- `GET /api/v3/meta/bases` - List all bases
- `GET /api/v3/meta/bases/{base_id}/tables` - List tables in base
- `POST /api/v3/meta/bases/{base_id}/tables` - Create table
**Data APIs:**
- `GET /api/v3/data/{base_id}/{table_id}/records` - List records
- `POST /api/v3/data/{base_id}/{table_id}/records` - Create record(s)
- `GET /api/v3/data/{base_id}/{table_id}/records/{recordId}` - Read single record
- `PATCH /api/v3/data/{base_id}/{table_id}/records?recordId={recordId}` - Update record
- `DELETE /api/v3/data/{base_id}/{table_id}/records?recordId={recordId}` - Delete record
- `GET /api/v3/data/{base_id}/{table_id}/count` - Count records
### Key Differences: v3 vs v2
| Feature | API v3 | API v2 |
|---------|--------|--------|
| Record endpoints | Require `base_id` | Don't require `base_id` |
| Update/Delete | Query param `?recordId=` | Path param `/records/{id}` |
| Relations | Embedded in responses | Separate calls needed |
| Linking | Unified in CRUD | Separate link/unlink calls |
| Response format | Standardized | Varies |
## Implementation Details
### Auto-Detection Strategy
The code implements a smart fallback system:
1. **Try API v3 first** - All endpoints attempt v3
2. **Fallback to v2** - If v3 fails (404, 400, etc.), automatically tries v2
3. **Report version** - Response includes `api_version` field showing which version was used
### Code Pattern
```python
# Try API v3 first, fallback to v2
for api_version in ["v3", "v2"]:
try:
if api_version == "v3":
url = f"{context.nocodb_url}/api/v3/data/{base_id}/{table_id}/records"
else:
url = f"{context.nocodb_url}/api/v2/tables/{table_id}/records"
async with session.get(url, headers=headers) as response:
if response.status == 200:
# Success - return with api_version
return json.dumps({..., "api_version": api_version, ...})
except Exception:
if api_version == "v2":
# Last attempt failed
return error_response
continue # Try next version
```
## Record Payload Format
### API v3 Bulk Operations
For bulk create/update operations, API v3 uses the `fields` object format:
```json
[
{
"fields": {
"column_name": "value",
"related_field": 123
}
},
{
"fields": {
"column_name": "value2"
}
}
]
```
### Single Record Operations
Single record operations can use direct format:
```json
{
"column_name": "value"
}
```
Or `fields` object format (both work).
## Compatibility
### NocoDB Version Requirements
- **API v3**: Requires NocoDB 0.264.0+ (introduced in 0.264.0)
- **Latest Stable**: 0.265.1 (October 2025) - Bug fixes, no API changes
- **Native MCP Server**: Available in 0.265.0+ (optional, our custom server still works)
- **API v2**: Works with NocoDB 0.200.0+
- **Auto-detection**: Server works with both v2 and v3
### n8n Integration
- **n8n v0.200.0+**: Supports NocoDB API v2
- **n8n with v3**: May need update for full v3 support
- **Recommendation**: Test n8n workflows with your NocoDB v3 instance
## Testing Checklist
With your instance at `nocodb.v1su4.com`:
- [ ] Test connection detects v3
- [ ] List bases works with v3
- [ ] List tables works with v3
- [ ] Get records returns embedded relations (v3 feature)
- [ ] Create record works with v3
- [ ] Update record works with v3 query param format
- [ ] Delete record works with v3 query param format
- [ ] Search records works with v3
- [ ] Table creation works with v3
- [ ] Analytics tool works with v3
## Your Instance Details
- **URL**: `https://nocodb.v1su4.com`
- **Base ID**: `pce7ccvwd1z09bx` (KEDB-SOLO)
- **API Versions Available**: v2 and v3 (confirmed from Swagger UI)
- **Storage**: MinIO S3 at `https://minio-api.v1su4.com` (needs configuration)
## Next Steps
1. ✅ **Code Updated** - All endpoints use v3 primary with v2 fallback
2. ⏳ **Deploy & Test** - Deploy updated code and test all tools
3. ⏳ **Configure MinIO** - Set up S3 storage (see MINIO_S3_CONFIGURATION.md)
4. ⏳ **Verify n8n** - Test n8n workflows with API v3
## References
- [NocoDB 0.264.0 Release Notes](https://github.com/nocodb/nocodb/releases/tag/0.264.0) - API v3 Introduction
- [NocoDB 0.265.0 Release Notes](https://github.com/nocodb/nocodb/releases) - Native MCP Server
- [NocoDB 0.265.1 Release Notes](https://github.com/nocodb/nocodb/releases/tag/0.265.1) - Latest (Bug Fixes)
- [NocoDB API v3 Documentation](https://nocodb.com/apis/v3/)
- [NocoDB GitHub Repository](https://github.com/nocodb/nocodb)
