API-Referenz

Rufen Sie variable Jar Variablen von überall ab – aus iOS-/Android-Apps oder CI-Pipelines – per REST. Schreibgeschützt, mit demselben Token wie der MCP-Server.

Beta: API und MCP können sich vor dem Start ändern; Formate sind jetzt versioniert (siehe Plattform-Code-Ausgabe), und inkompatible Änderungen werden mit 12 Monaten Übergangszeit angekündigt.

Ein Token ausstellen

1. variablejar.com/app → ⋯-Menü → Eigenschaften einer Projektkarte → Abschnitt API-Tokens (MCP)
2. Geben Sie einen Token-Namen ein und drücken Sie Ausstellen – das Token (vjt_…) wird nur einmal direkt nach der Ausstellung angezeigt. Bewahren Sie es sicher auf.
3. Ein Token gewährt nur Zugriff auf genau dieses Projekt. Gelangt es nach außen, widerrufen Sie es sofort auf demselben Bildschirm.

Tokens laufen ab (standardmäßig nach 180 Tagen, höchstens nach 365). 14 Tage vorher erhalten Sie eine Benachrichtigung über die Glocke. Nur der Eigentümer des Workspace kann ein Token ausstellen, das Textwerte (STRING) enthält – alle Sprachen, auch unveröffentlichte Übersetzungen. Sie können ein Token außerdem auf ausgewählte Sammlungen beschränken.

Ein Token ist nur so sicher wie der Ort, an dem Sie es aufbewahren: Wer es besitzt, erhält alle Werte innerhalb seines Umfangs. Über die API oder MCP exportierte Daten verlassen den Dienst und werden in Ihrer Verantwortung verarbeitet.

Endpunkt

GET https://variablejar.com/api/v1/variables
Authorization: Bearer vjt_...

curl -H "Authorization: Bearer vjt_..." \
  "https://variablejar.com/api/v1/variables"

Textwerte (STRING) sind nur enthalten, wenn das Token mit Textwerten ausgestellt wurde und Sie ?include=strings anhängen.

Antwort

Die Werte sind Endwerte, Aliase ({Collection/key}) sind aufgelöst. Nur Zellen, die nicht aufgelöst werden konnten, erscheinen mit einem Grund (broken · cycle · inline) in unresolved und behalten ihren ursprünglichen Wert.

{
  "apiVersion": "v1",
  "project": { "name": "My Variables" },
  "collections": [
    { "name": "Color", "modes": ["light", "dark"] },
    { "name": "Text", "modes": ["en", "ko"] }
  ],
  "tokens": [
    {
      "key": "color/primary",
      "collection": "Color",
      "type": "COLOR",
      "valuesByMode": { "light": "#3B82F6", "dark": "#60A5FA" }
    },
    { "key": "hello", "collection": "Text", "type": "STRING", "valuesByMode": {}, "omitted": "strings" }
  ]
}

Ohne include=strings werden STRING-Tokens trotzdem aufgeführt, aber mit leerem valuesByMode und "omitted": "strings".

Plattform-Code-Ausgabe

Hängen Sie ?format= an, um statt JSON generierten Plattform-Code zu erhalten:

Formate sind versioniert. Der Name ohne Version (css) ist ein dauerhafter Alias für @1 – er wechselt nie von selbst auf eine neuere Version. Innerhalb einer Version sind nur zwei Arten von Änderungen erlaubt: Korrekturen an Ausgaben, die keine gültige Syntax waren, und Korrekturen am Escaping aus Sicherheitsgründen; beide erhöhen die rev des Formats (aufgeführt unter /formats, siehe unten) und machen Caches ungültig. Alles, was die Darstellung eines Werts oder einen Bezeichner ändert, ist eine neue Version (css@2), und die vorherige Version bleibt 12 Monate lang verfügbar (angekündigt über die Header Deprecation und Sunset).

curl -H "Authorization: Bearer vjt_..." \
  "https://variablejar.com/api/v1/variables?format=css" \
  > variables.css

Die Ausgabe ist deterministisch – identische Tokens ergeben immer identische Bytes, sodass Caching mit ETag/If-None-Match genauso funktioniert wie bei der JSON-Antwort. Aliase werden immer zu Endwerten aufgelöst; nicht auflösbare Referenzen werden als Kommentare ausgegeben, nie als erfundene Werte. Ein unbekanntes format liefert 400 { "error": "unknown_format" }.

Bezeichner werden aus Sammlungs- und Variablennamen abgeleitet und hängen nicht von der Reihenfolge Ihrer Daten ab: Wenn Sie in Figma Sammlungen, Variablen oder Modi umsortieren, wird nie ein Token umbenannt. Ergeben zwei Namen denselben Bezeichner, behält derjenige, der nach seinem ursprünglichen Namen zuerst einsortiert wird, den einfachen Bezeichner, und die anderen erhalten _2, _3 …; ein neu hinzugefügter kollidierender Name kann vorhandene Suffixe neu nummerieren – vermeiden Sie daher Namen, die sich nur in Trennzeichen oder Groß-/Kleinschreibung unterscheiden. Dieselbe Variable erhält denselben Bezeichner, egal welchen Filter Sie verwenden (collection, include=strings oder ein auf einige Sammlungen beschränktes Token): Die Namen werden zuerst über das gesamte Projekt festgelegt, erst danach wird die Antwort gefiltert.

?collection=<name> beschränkt die Ausgabe auf eine Sammlung (400 unknown_collection, wenn der Name nicht im Projekt vorkommt). ?view=ai@1 liefert eine kompakte, bereinigte Ansicht für KI-Agenten (nur Namen und Werte, Textwerte standardmäßig ausgelassen); sie lässt sich nicht mit format kombinieren, und jeder andere view-Wert außer index (siehe unten) liefert 400 unknown_view.

?view=index zusammen mit format liefert statt Code den Bezeichner, den jede Variable in diesem Format erhält – zum Prüfen von Namen, ohne den generierten Code zu parsen. Die Bezeichner sind so geschrieben wie in der Ausgabe (Swift/Kotlin-Schlüsselwörter behalten ihre Backticks). Text-Variablen (STRING) fehlen im Index, außer das Token wurde mit Textwerten ausgestellt und Sie übergeben include=strings. view=index ohne format liefert 400 unknown_view.

curl -H "Authorization: Bearer vjt_..." \
  "https://variablejar.com/api/v1/variables?format=css@1&view=index"

{
  "format": "css@1",
  "rev": "1-1",
  "identifiers": [
    { "collection": "Color", "key": "btn/bg", "identifier": "--color-btn-bg" }
  ]
}

GET /api/v1/formats listet die Formate und Versionen, die dieser Server anbietet, jeweils mit aktueller rev, Dateiname und Content-Type. Der Endpunkt nutzt dasselbe Token, zählt weder zur Nutzung noch zum Anfragelimit und unterstützt ETag/If-None-Match wie der Variablen-Endpunkt (kein X-VJ-Stamp – die Liste ist statisch). Eine abgelöste Version trägt zusätzlich "deprecated": { "since": "YYYY-MM-DD", "sunset": "YYYY-MM-DD" }; sunset ist nur vorhanden, wenn ein Datum feststeht.

{
  "contract": "1",
  "formats": [
    { "id": "css", "version": 1, "spec": "css@1", "rev": "1-1", "alias": "css", "filename": "variables.css", "mime": "text/css; charset=utf-8" },
    { "id": "swift", "version": 1, "spec": "swift@1", "rev": "1-1", "alias": "swift", "filename": "Tokens.swift", "mime": "text/plain; charset=utf-8" },
    { "id": "compose", "version": 1, "spec": "compose@1", "rev": "1-1", "alias": "compose", "filename": "Tokens.kt", "mime": "text/plain; charset=utf-8" }
  ],
  "views": [{ "view": "ai@1", "rev": "1" }]
}

Polling und ETag

Antworten enthalten einen ETag-Header. Senden Sie ihn als If-None-Match zurück, und Sie erhalten 304 (ohne Body), wenn sich nichts geändert hat – das spart Bandbreite bei regelmäßigen Prüfungen aus mobilen Apps und CI. Verwenden Sie den erhaltenen ETag-Wert unverändert (er kann W/ enthalten).

curl -i -H "Authorization: Bearer vjt_..." \
  -H 'If-None-Match: "…"' \
  "https://variablejar.com/api/v1/variables"
# HTTP/2 304

Jede 200- und 304-Antwort trägt diese Header:

Fehler

Fehlerantworten haben den Body { "error": "<code>" }.

MCP-Server (IDE / KI-Agenten)

Aus IDEs und KI-Coding-Agenten ist der MCP-Server @variablejar/mcp bequemer als REST – dasselbe Token funktioniert für beides. Sie können diese Seite einem KI-Agenten geben und ihn bitten, die Integration für Sie einzurichten.

Fügen Sie Folgendes zu Ihrer MCP-Konfiguration hinzu (mit fester Version):

{
  "mcpServers": {
    "variablejar": {
      "command": "npx",
      "args": ["-y", "@variablejar/mcp@0.3.1"],
      "env": { "VARIABLEJAR_TOKEN": "vjt_your_token_here" }
    }
  }
}

Wo die Datei liegt, hängt vom Client ab:

Verfügbare Tools:

Der Server hält Ergebnisse nur im Arbeitsspeicher, prüft die API einmal pro TTL (30–600 s) erneut und verwendet alles wieder, solange der Aktualitätsstempel des Projekts unverändert ist. Tool-Ergebnisse enthalten die Fehlercodes der API (error: unauthorized, error: plan_required, …); ist die API nicht erreichbar, wird das letzte Ergebnis mit einem Hinweis auf sein Alter geliefert. Token-Daten sind in zufällige Begrenzungsmarker eingeschlossen, mit einer festen Vorbemerkung, dass es sich um Daten und nicht um Anweisungen handelt.

Umgebungsvariablen:

Umstieg von 0.2.0: Diese Version ruft einen stillgelegten Endpunkt auf und erhält jetzt 410. Die Tool-Namen sind unverändert und Eingaben kamen nur hinzu, aber die Ausgaben haben sich geändert – list_tokens ist seitenweise, mit einer ersten Zeile total=… und kurzen Schlüsseln (c, k, t, v), get_token liefert dieselben kurzen Schlüssel und listet die Kandidaten auf, wenn der Schlüssel in mehreren Sammlungen vorkommt, list_collections liefert keine IDs mehr, und get_tokens liefert einen Vorbemerkungsblock plus einen Codeblock innerhalb von Begrenzungsmarkern.

Der Server ist schreibgeschützt – das Token kann nichts schreiben oder löschen.

Hinweise

• Nicht direkt aus einem Browser (Web-Frontend) aufrufen – das Token wäre im Client-Code sichtbar. Verwenden Sie es aus Servern, Apps oder CI, wo das Token verborgen bleibt.
• Schreib-APIs und Delta-Abfragen (nur Änderungen) gibt es noch nicht.
• Als LLM-Kontext steht die gesamte Dokumentation als /llms.txt (Index) und /llms-full.txt (alles in einer Datei) auf Englisch bereit.