Напускате Airtable? Пренесете базите си в Artavolo, проверени запис по запис. Вижте как

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}/schema200 с базата и нейните таблици
GET /api/v2/bases/{code}/tables/{table}/rows200 с { "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}/trash200 с { "records": [{ "trashId", "deletedAt", "deletedBy", "deletedVia", "record" }] }
POST .../tables/{table}/trash/{trashId}/restore200 със записа, върнат под собствения му идентификатор; изисква право за добавяне на записи
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}/history200 с { "changes": [{ "at", "by", "via", "columnId", "value", "from" }] }: последните 200 промени на записа от дневника на промените, най-старите първи. at е в милисекунди, by е идентификатор на член, via е приложението, през което е дошла промяната („Claude“). Добавен запис е един ред с "added": true. Стойностите са в същата форма като при четене.
GET /api/v2/bases/{code}/assistant200 с адреса на конектора, дали този човек може да променя записи от AI чата, и примерни подкани, написани от полетата на всяка таблица
GET /api/v2/bases/{code}/schema?format=base200 с таблиците във формата на 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}/people200 с това кой е вътре (роля 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, background200 с настройките на формуляра на таблицата: кой може да попълва формуляра, неговата парола (само дали има такава), кой изглед формуляр е споделен, екраните за добре дошли и за благодарност, лого, корица, фон и връзките за споделяне. Това, което формулярът пита, е неговият изглед формуляр. Само за собственици.
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-items200 с { "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
booleantrue или false
dateYYYY-MM-DD
datetimeYYYY-MM-DDTHH:MM:SS, по часа на сървъра
enumvalue на опцията; при запис може да се подаде 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поле, което не съществува, поле само за четене или стойност от грешен вид; изречението назовава полетата или опциите, които биха свършили работа

Какво още прави един запис

Това са същите неща, които се случват, когато някой редактира в браузъра:

  • Следва правилата на базата за това кой може да създава, редактира и изтрива, и видимостта на таблицата.
  • Записва се в дневника на промените, със стойностите преди и след.
  • Стартира автоматизациите на таблицата.
  • Изпраща уебхуковете на базата.
  • Обновява таблицата за всеки, който я има отворена, когато са включени актуализациите на живо.
Въпрос, на който тези страници не отговарят? Пишете ни и ще ви отговорим по имейл, обикновено в рамките на един работен ден. Свържете се с нас