Data API (v2)
Един REST ресурс за всяка таблица, за програми и за createRestDataSource на SvGrid, който го чете и записва без адаптер.
Вход
Същите идентификационни данни като за останалата част от API:
- сесия на влязъл в профила си браузър
- API токен (Профил → API токени), изпратен по един от двата начина:
Authorization: Basic base64(email:token)API-KEY: <token>
Токенът работи само в работното пространство, за което е създаден, и само за базите, включени за него. Токените на AI конектора се отказват тук; те принадлежат на /mcp.
Маршрути
{code} е кодът на базата от адреса на базата. {table} е идентификаторът на таблицата, който е name в схемата.
| Заявка | Отговор |
|---|---|
GET /api/v2/bases/{code}/schema | 200 с базата и нейните таблици |
GET /api/v2/bases/{code}/tables/{table}/rows | 200 с { "rows": [...], "rowCount": 120, "offset": 0, "limit": 100 } |
GET .../rows/{id} | 200 с един запис |
POST .../rows със запис | 201 със записа, както е съхранен |
POST .../rows с { "records": [...] } (до 100) | 201 с { "records": [...] } |
PATCH .../rows/{id} с променените полета | 200 със записа, както е съхранен |
DELETE .../rows/{id} | 204; записът отива в кошчето на таблицата за 30 дни |
GET .../tables/{table}/trash | 200 с { "records": [{ "trashId", "deletedAt", "deletedBy", "deletedVia", "record" }] } |
POST .../tables/{table}/trash/{trashId}/restore | 200 със записа, върнат под собствения му идентификатор; изисква право за добавяне на записи |
GET .../tables/{table}/trash?limit=500 или ?rows=12,13 | Списъкът на кошчето както по-горе, до limit записа (най-много 1 000), или само тези записи; с "total", колко записа има в кошчето |
POST .../tables/{table}/trash/restore с { "ids": [12, 13] } | 200 с { "restored": ["12"] }: записи, върнати по своите идентификатори, всеки от последния си запис в кошчето, под собствения си идентификатор. Който не може да се върне, се пропуска. Изисква право за добавяне на записи. |
POST .../tables/{table}/trash/purge с { "ids": [12] } | 200 с { "purged": ["12"] }: изтриване завинаги. Записите в кошчето на тези записи се премахват, така че не могат да се възстановят. Изисква право за изтриване на записи. |
GET .../rows/{id}/history | 200 с { "changes": [{ "at", "by", "via", "columnId", "value", "from" }] }: последните 200 промени на записа от дневника на промените, най-старите първи. at е в милисекунди, by е идентификатор на член, via е приложението, през което е дошла промяната („Claude“). Добавен запис е един ред с "added": true. Стойностите са в същата форма като при четене. |
GET /api/v2/bases/{code}/assistant | 200 с адреса на конектора, дали този човек може да променя записи от AI чата, и примерни подкани, написани от полетата на всяка таблица |
GET /api/v2/bases/{code}/schema?format=base | 200 с таблиците във формата на SvGrid Base (BaseTable: полета, изгледи), всяка с permissions, които екранът трябва да предложи, плюс people (id, име, снимка) и me |
POST /api/v2/bases/{code}/editor с { "editor": "base" } | 200. Всяка база се отваря в екрана с таблица; "classic" се отказва (422, "code": "retired"). Само за собственици. |
POST .../tables/{table}/fields с { "field": "priority", "fieldType": "text" } | 201; колоната за ново поле (букви, цифри и _). Формула, справка, обобщение или брой не се нуждаят от такава: "column": false. Име, което таблицата вече има, отговаря с 409 и "code": "column-exists". С "default" всеки запис, който вече е в таблицата, получава тази стойност (ново поле още не съдържа нищо), а "filled" казва колко. Поле автономер, време на създаване или създадено от номерира или отбелязва съществуващите записи. Само за собственици. |
GET /api/v2/forms/{table code} | 200 с публикувания формуляр на таблицата: полетата на неговия изглед формуляр като колони на SvGrid Base, кои са задължителни, неговите условия, предварително попълнени полета и долен колонтитул, и как изглежда. Само title и needsPassword, докато посетителят не въведе паролата. 404 за таблица, която не споделя формуляр. |
POST /api/v2/forms/{table code} с { "values": {...}, "recaptcha": "..." } | 201 с { "id" }. Проверява се отново: само полетата на формуляра, задължителните му (поле с условие тук никога не е задължително), паролата и reCAPTCHA. Полетата, които формулярът не изисква, получават стойността си по подразбиране, номер и време. |
POST /api/v2/forms/{table code}/password с { "password" }, POST .../files (multipart file) | 200, щом паролата е вярна (пази се в сесията на посетителя); 201 с файл за формуляр, който изисква такъв |
GET /api/v2/workspaces/{code}/people или /api/v2/bases/{code}/people | 200 с това кой е вътре (роля owner, contributor или readonly и дали достъпът му е включен), за база също и хората на работното пространство отделно, отворените покани, кой моли за достъп и лимита на плана. Само за собственици. |
POST .../people/invites с { "email", "role", "message" } или { "link": true, "role" }, DELETE .../people/invites/{id} | 201 или 200 със списъка; изпраща се покана по имейл. Адрес, който вече е поканен или вече е вътре, отговаря с 409. |
PATCH .../people/{id} с { "role" } и/или { "active" }, DELETE .../people/{id} | 200 със списъка, или { "owner": false }, когато промяната е прекратила вашата собствена собственост. Последният активен собственик на работно пространство не може да се оттегли, да бъде изключен или премахнат (409, "code": "last-owner"). |
POST /api/v2/bases/{code}/people/requests с { "message" }; POST .../people/requests/{id}/accept с { "role" } | 201, щом е поискано (всеки влязъл в профила си, който не е вътре, веднъж); собственик го допуска с роля. |
GET /api/v2/bases/{code}/permissions, PUT с { "records": {...}, "tables": [...] } или { "reset": true } | 200 с това кой може да добавя, променя и изтрива записи (contributors, owners, specific_users с people или nobody), кой вижда всяка таблица (everyone, readonly, contributors, owners), правилото за редове на всяка таблица и хората на базата с техните роли. Всяка стойност се проверява: кой може да добавя никога не е по-широк от това кой може да променя, а назованите хора принадлежат на базата. Само за собственици. |
GET .../tables/{table}/form, PATCH с което и да е от published, forEveryone, recaptcha, password, clearPassword, view, welcome, thanks, background | 200 с настройките на формуляра на таблицата: кой може да попълва формуляра, неговата парола (само дали има такава), кой изглед формуляр е споделен, екраните за добре дошли и за благодарност, лого, корица, фон и връзките за споделяне. Това, което формулярът пита, е неговият изглед формуляр. Само за собственици. |
POST .../tables/{table}/form/images/{logo, cover or background} (multipart file, заглавка X-Artavolo-Upload: 1), DELETE същото | 200 с настройките; снимка JPEG, PNG, GIF или WebP до 5 MB, иначе 415 или 413. Само за собственици. |
GET /api/v2/bases/{code}/trash-items | 200 с { "items": [...] }: полетата, изгледите и таблиците, изтрити в екрана с таблици през последните 30 дни, като елементи от кошчето на SvGrid Base. Чете се от всеки член. |
POST .../trash-items с { "items": [...] }, POST .../trash-items/remove с { "ids": [...] } | запазете елементите или ги премахнете (възстановени или изтрити завинаги). Само за собственици; за всеки друг премахването не прави нищо. Записите не се пазят тук: кошчето на всяка таблица ги съдържа. |
PUT /api/v2/bases/{code}/design с { "tables": [{ "id", "name", "primaryField", "columns", "views", "removed": ["field"] }] } | 200 с { "saved": [ids], "skipped": [ids] }. Полетата (колоните на SvGrid Base) и изгледите на новия екран с таблици, и името на таблицата. Полетата на записите се записват и в настройките на класическия екран; поле ги напуска само когато е назовано в removed, а неговата колона и стойности остават. Формулите, справките, обобщенията, броячите и изгледите се пазят само за новия екран. Таблици не се добавят и не се изтриват тук. Само за собственици. |
Записите трябва да се изпращат с Content-Type: application/json.
Записи
Записът е плосък. Той има:
id- полетата на таблицата, по техния ключ (например
dataFieldDefault1) - четири полета, които задава сървърът:
created_at,updated_at,created_byиupdated_by(идентификатори на членове)
{ "id": 12, "dataFieldDefault1": "Acme", "dataFieldAmount": 12000, "dataFieldStage": "proposal",
"dataFieldTags": ["eu", "q4"], "dataFieldWon": false, "dataFieldClose": "2026-11-20",
"created_at": "2026-11-04T10:12:00", "updated_at": null, "created_by": 7, "updated_by": null }
| Тип на полето в схемата | Стойност |
|---|---|
text | низ; нови редове като \
|
number | число или null |
boolean | true или false |
date | YYYY-MM-DD |
datetime | YYYY-MM-DDTHH:MM:SS, по часа на сървъра |
enum | value на опцията; при запис може да се подаде label вместо него |
json с multiple: true | списък със стойности на опции |
json | файлове и контролни списъци, като JSON |
json с kind: "link" | идентификаторите на свързаните записи, [12, 40], или []; table е името на свързаната таблица, а multiple показва дали полето съдържа няколко записа, или един. Записът приема списък (или един идентификатор); филтърът eq:12 означава „включва 12“ |
Връзката се пази по идентификатор на запис, така че изтриването на запис в свързаната таблица никога не премества връзките на никого към друг запис; връзките към изтрития запис се изчистват.
GET .../schema?format=base връща същите таблици във формата на самия SvGrid Base: { id, name, primaryField, columns: [{ id, field, header, fieldType, fieldProps }], views }, готови за <SvBase tables>, плюс notes. Бележките назовават всичко, което не се пренася точно, например форматиран текст, съхранен като HTML, или тип изглед, който SvGrid Base няма. php utilities/base-schema.php --all отпечатва същите бележки за всяка база в инсталацията.
kind показва полето така, както го съхранява Artavolo, например richText (чете се и се записва като Markdown, с format: "markdown": удебелен, *курсив*, code, връзки и списъци с „- “; клетката пази HTML, който рисува старият екран, а HTML, изпратен от по-стар клиент, се запазва), collaborator (идентификатор на член), formula или ai. Полетата, отбелязани с readonly, не могат да се записват: формули и AI полета (все още изчислявани в браузъра), файлове (използвайте процеса за качване) и полета за време на създаване.
Всяка таблица в схемата носи и access: canCreate, canEdit и canDelete за извикващия.
Четене
| Параметър | Значение |
|---|---|
offset, limit | странициране; limit е 100 по подразбиране и най-много 10 000 |
sort=-dataFieldAmount,dataFieldDefault1 | полета, разделени със запетая; - сортира низходящо |
search=acme | което и да е текстово поле го съдържа |
<field>=<op>:<value> | eq, contains, startsWith, gt, lt, between:a,b, in:a,b,c, isNull |
fields=dataFieldDefault1,dataFieldAmount | връща само тези полета (и id) |
filter=<FieldFilter JSON> | филтърът на запазен изглед, както го изпраща SvGrid Base ({"kind":"fieldFilter","conjunction":"and","conditions":[...]}, едно ниво групи). Или целият се прилага в SQL и отговорът съдържа "appliedExpression": true, или не се прилага нищо от него и отговорът го пропуска: условие върху формула, справка, обобщение или брой, свързан запис, търсен по име, форматиран текст, файлове, контролен списък или време от денонощието не може да бъде SQL и екранът тогава го изчислява сам |
tz=Europe/Berlin | часовата зона на зрителя, за „днес“ и другите относителни дни в условие за дата (по подразбиране: на сървъра) |
groupBy=dataFieldStage | един ред на ключ вместо записи: { "dataFieldStage": "won", "childCount": 4000, "leafCount": 4000 }, подредени по ключ (или както sort подрежда това поле); rowCount брои групите. Записите под даден ключ: dataFieldStage=eq:won (за празен ключ: isNull). Още не се групира по връзка, множествен избор, форматиран текст или JSON (400) |
aggregate=sum:dataFieldAmount,count:dataFieldDue | суми за всяка група, под името на всяко поле: sum, avg, min, max (числови полета) и count (попълнени клетки) |
grandTotal=1 | заедно с aggregate: общите стойности за всички записи, които заявката обхваща, в "grandTotal" |
Редовете идват по ред на идентификатора на записа, освен ако не е зададено сортиране. В инсталация, която криптира стойностите на клетките, филтрирането, търсенето и сортирането се отказват с 400; страницирането продължава да работи. С format=base схемата дава recordCount на всяка таблица; екранът на таблицата чете таблица с над 10 000 записа на части.
И API на Airtable
Скриптове и инструменти, написани за REST API на Airtable, могат да ползват API-то, съвместимо с Airtable, на /v0/...: същите пътища, идентификатори и формати, върху това API. Таблица може да се експортира и във форматите CSV и JSON на Airtable (.../tables/{id}/export?format=airtable-csv|airtable-json).
Изчислявани полета
Формулите, справките, обобщенията и броячите, създадени в екрана на таблицата, се изчисляват и на сървъра, на PHP (libs/BaseCompute.class.php и libs/Formula.class.php, порт на енджина на SvGrid Base, който tests/formula_test.php проверява стойност по стойност спрямо него), така че четенето връща стойностите, които хората виждат. Не е нужно нищо да работи освен PHP. Те идват с всеки запис под ключа на своето поле и са изброени в схемата като само за четене ("computed": true, kind показва кое е).
- Свързаните записи попадат в справка или обобщение само такива, каквито извикващият има право да вижда (правила за редове).
- Не могат да се записват и записите още не могат да се филтрират или сортират по тях: това връща
400с едно изречение, а никога резултат, който пренебрегва условието. computed=0ги изключва (екранът на таблицата иска така; той ги изчислява сам).- „Днес“ и датите без час са по часовата зона на сървъра или по тази на зрителя с
tz=. - Ако изчисляването им се провали, записите пак идват, но без тях, а отговорът съдържа
"computed": false.
Откази
Всеки отказ е статус и едно изречение: { "error": "..." }. 422 за пакет изброява и всеки проблем под problems.
| Статус | Кога |
|---|---|
401 | не сте влезли |
403 | влезли сте, но правилата на базата не позволяват това, или обхватът на токена не стига до тази база |
404 | няма такава база, таблица или запис, или такава, която извикващият не може да вижда |
415 | запис, който не е JSON |
422 | поле, което не съществува, поле само за четене или стойност от грешен вид; изречението назовава полетата или опциите, които биха свършили работа |
Какво още прави един запис
Това са същите неща, които се случват, когато някой редактира в браузъра:
- Следва правилата на базата за това кой може да създава, редактира и изтрива, и видимостта на таблицата.
- Записва се в дневника на промените, със стойностите преди и след.
- Стартира автоматизациите на таблицата.
- Изпраща уебхуковете на базата.
- Обновява таблицата за всеки, който я има отворена, когато са включени актуализациите на живо.