Grids

Ein Grid ist eine Tabelle: Felder als Spalten, Einträge als Zeilen. Die Pfade liegen unter /api/users/{userId}/spaces/{spaceId}/grids; sie sind hier gekürzt geschrieben.

Für Einträge gibt es eine eigene Seite. → Einträge

Ein Grid als JSON

Mit Accept: application/vnd.apptivegrid.hal;version=2:

{
  "_representation": "full",
  "id": "6512bb…",
  "name": "Aufgaben",
  "key": "aufgaben",
  "type": "persistent",
  "metaType": "grid",
  "displayValue": "Aufgaben",
  "icon": { … },
  "properties": { },
  "fields": [
    { "id": "6512cc…", "name": "Titel", "key": "titel", "description": null,
      "type": { "name": "string", … }, "schema": { … } }
  ],
  "_links": { "self": …, "entities": …, "addEntity": …, "schema": …, "virtualGrids": … }
}

fields gibt es nur in Version 2

Ohne version=2 im Accept-Header antwortet das Backend mit der älteren Darstellung ohne den Block fields. Die Felddefinitionen kommen dann über GET …/grids/{gridId}/schema.

Grids auflisten und anlegen

# Auflisten
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE/api/users/$USER_ID/spaces/$SPACE_ID/grids?type=persistent"

# Anlegen
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aufgaben", "key": "aufgaben", "createView": true}' \
  -D - -o /dev/null \
  "$BASE/api/users/$USER_ID/spaces/$SPACE_ID/grids"

Parameter bei GET /grids	Bedeutung
type	Auf eine Art einschränken: persistent (echte Grids) oder virtual (Ansichten)
pageIndex, pageSize	Seitensteuerung

Feld bei POST /grids
name	Höchstens 80 Zeichen, im Space eindeutig
key	Höchstens 25 Zeichen, im Space eindeutig
createView	true legt gleich eine erste Ansicht mit an
icon	Symbolobjekt

Antwort 201 Created, Pfad im Header Location.

Grid ändern und löschen

# Name oder Schlüssel ändern
curl -s -X PATCH -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Aufgaben 2026"}' \
  "$BASE$GRID"

# Löschen
curl -s -X DELETE -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID"

PATCH nimmt name, key, icon und properties.

Felder

Felder werden nicht über /fields angelegt, sondern über benannte Operationen am Grid. Die Pfade sind großgeschrieben — das ist so gewollt und keine Ungenauigkeit dieser Seite.

Aufgabe	Aufruf	Rumpf
Feld anlegen	POST …/grids/{gridId}/ColumnAdd	{ "name", "key", "description", "position", "type": { "name" } }
Feld umbenennen	POST …/grids/{gridId}/ColumnRename	{ "oldName", "newName" }
Typ ändern	POST …/grids/{gridId}/ColumnTypeChange	{ "fieldId", "type": { "name" } }
Schlüssel setzen	POST …/grids/{gridId}/ColumnKeyChange	{ "fieldId", "key" }
Feld löschen	POST …/grids/{gridId}/ColumnRemove	{ "fieldId" }
Feld lesen	GET …/grids/{gridId}/fields/{fieldId}	–
Feld ändern	PATCH …/grids/{gridId}/fields/{fieldId}	{ "name", "key", "description", "type" }

Alle Struktureingriffe verlangen die Rolle admin.

curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fällig am", "type": {"name": "date"}}' \
  "$BASE$GRID/ColumnAdd"

Feldtypen

Die Namen für type.name liefert GET /api/types — ohne Anmeldung abrufbar:

curl -s "$BASE/api/types"

Verfügbar sind unter anderem string, richText, integer, decimal, currency, boolean, date, date-time, enum, enumcollection, stringcollection, email, phoneNumber, uri, address, geolocation, attachments, signature, user, createdby, createdat, reference, references, lookup, formula, resource.

Neben name kann type je nach Typ weitere Eigenschaften tragen — bei enum etwa options. Die maßgebliche Beschreibung steht im Schema, das GET /api/types mitliefert.

Das Schema eines Grids

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID/schema"

Antwort ist ein JSON-Schema, das die erlaubten Einträge dieses Grids beschreibt: welche Schlüssel es gibt und welcher Wert je Feld zulässig ist. Es ist die verlässliche Quelle für Feld-IDs.

Ansichten (Virtual Grids)

Ein Virtual Grid ist ein gespeicherter Ausschnitt: Feldauswahl, Filter, Sortierung.

# Anlegen
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Offen",
        "fields": ["6512cc…", "6512dd…"],
        "filter": { "6512ee…": { "$eq": "offen" } },
        "sorting": { "6512cc…": { "$order": "ascending" } }
      }' \
  -D - -o /dev/null \
  "$BASE$GRID/virtualgrids"

# Auflisten
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID/virtualgrids"

fields und filter sind Pflicht; ein leeres filter schreibt man als {}.

Das angelegte Virtual Grid bekommt eine eigene Adresse in Gridform: /api/users/{userId}/spaces/{spaceId}/grids/{virtualGridId}. Es lässt sich damit wie ein Grid lesen, /entities eingeschlossen. Filter und Sortierung ändert man mit PUT auf diese Adresse (filter, fields, name sind dabei Pflicht) oder gezielt nur den Filter mit POST …/FilterChange und { "filter": … }.

→ Filtersprache

Ansichten (Stateful Views)

sviews beschreibt die Darstellung — Kanban, Kalender und so fort — und liegt unter einem Grid oder Virtual Grid.

Aufruf
GET …/grids/{gridId}/sviews	Auflisten; nested=true nimmt Ansichten unterliegender Virtual Grids mit
POST …/grids/{gridId}/sviews	Anlegen, Rumpf { "type", "properties", "slotProperties" }
GET/PATCH/DELETE …/sviews/{sview}	Lesen, ändern, löschen
GET …/sviews/{sview}/schema	Schema der Einträge dieser Ansicht
GET/POST …/sviews/{sview}/shares	Freigaben der Ansicht

Formulare

# Formulare eines Grids
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID/forms"

# Formular lesen
curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" "$BASE$GRID/forms/$FORM_ID"

# Formular absenden — legt einen Eintrag an
curl -s -X POST -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"6512cc…": "Erste Aufgabe"}' \
  "$BASE$GRID/forms/$FORM_ID"

Absenden nutzt immer das Feld-Layout

Anders als beim Anlegen über /entities erwartet das Absenden eines Formulars die Werte immer mit den Feld-IDs als Schlüssel, unabhängig von layout.

Absenden verlangt addEntity und ist damit auch für die Rolle creator offen — genau dafür sind öffentliche Formularlinks gedacht. → Authentifizierung

CSV-Export

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" -o export.csv "$BASE$GRID/csv"

Die Antwort ist eine Datei: Content-Type: application/octet-stream, Content-Disposition: attachment; filename="apptive-grid-export.csv". Auf einem Virtual Grid liefert derselbe Aufruf den gefilterten Ausschnitt.

Änderungen seit einem Zeitpunkt

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/updates?since=2026-03-14T09:12:00%2B01:00"

since ist der Zeitpunkt der letzten Abfrage. Nützlich, um eine Kopie fortzuschreiben, ohne jedes Mal alle Einträge zu holen.

Suchen im Grid

curl -s -u "$APPTIVE_KEY:$APPTIVE_SECRET" \
  "$BASE$GRID/query?matching=Rechnung&pageSize=20"

query durchsucht die Einträge nach einem Textwert. Die Antwort ist eine Sammlung von Einträgen, deren Werte auf die ersten vier Felder des Schemas beschränkt sind — die Trefferliste ist als Vorschau gedacht, nicht als vollständiger Datenabzug. Den ganzen Eintrag holt anschließend ein GET auf seine Adresse aus _links.

viewId schränkt die Suche auf einen Ausschnitt ein, layout bestimmt die Form der gelieferten Werte. Vorgabe für pageSize ist hier 50, nicht 300.