Referência da API

Busque as variáveis do variable Jar de qualquer lugar — apps iOS/Android, pipelines de CI — via REST. Somente leitura, com o mesmo token do servidor MCP.

Beta: a API e o MCP podem mudar antes do lançamento; os formatos agora têm versão (veja Saída de código de plataforma), e mudanças incompatíveis são anunciadas com 12 meses de convivência.

Emitir um token

1. variablejar.com/app → o menu ⋯ do cartão de um projeto → Propriedades → a seção Tokens de API (MCP)
2. Digite um nome para o token e clique em Emitir — o token (vjt_…) aparece uma única vez, logo depois da emissão. Guarde-o num lugar seguro.
3. Um token dá acesso só àquele projeto. Se ele vazar, revogue-o na hora, na mesma tela.

Os tokens expiram (180 dias por padrão, até 365). Você recebe uma notificação no sino 14 dias antes. Só o proprietário do espaço de trabalho pode emitir um token que inclua valores de texto (STRING) — saem todos os idiomas, inclusive traduções não publicadas. Também dá para limitar um token a coleções escolhidas.

Um token é tão seguro quanto o lugar onde você o guarda: quem o tiver recebe todos os valores dentro do seu escopo. Os dados que você exporta pela API ou pelo MCP saem do serviço e são tratados sob sua responsabilidade.

Endpoint

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

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

Os valores de texto (STRING) só vêm incluídos se o token foi emitido com valores de texto e você adicionar ?include=strings.

Resposta

Os valores são finais, com os aliases ({Collection/key}) resolvidos. Só as células que não puderam ser resolvidas aparecem em unresolved com um motivo (broken · cycle · inline), mantendo o valor original.

{
  "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" }
  ]
}

Sem include=strings, os tokens STRING continuam listados, mas com valuesByMode vazio e "omitted": "strings".

Saída de código de plataforma

Adicione ?format= para receber código de plataforma gerado em vez de JSON:

Os formatos têm versão. O nome sem versão (css) é um alias permanente de @1 — ele nunca passa sozinho para uma versão mais nova. Dentro de uma versão, só dois tipos de mudança são permitidos: corrigir uma saída que não era sintaxe válida e corrigir o escape por segurança; os dois aumentam o rev do formato (listado por /formats, abaixo) e invalidam os caches. Qualquer coisa que mude a representação de um valor ou um identificador é uma nova versão (css@2), e a versão anterior continua disponível por 12 meses (anunciado com os cabeçalhos Deprecation e Sunset).

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

A saída é determinística — tokens idênticos sempre geram bytes idênticos, então o cache com ETag/If-None-Match funciona do mesmo jeito que na resposta JSON. Os aliases são sempre resolvidos para valores finais; referências não resolvidas saem como comentários, nunca como valores inventados. Um format desconhecido retorna 400 { "error": "unknown_format" }.

Os identificadores vêm dos nomes de coleção e de variável e não dependem da ordem dos seus dados: reordenar coleções, variáveis ou modos no Figma nunca renomeia um token. Quando dois nomes resultam no mesmo identificador, o que vem primeiro na ordenação (pelo nome original) fica com o identificador simples e os outros recebem _2, _3 …; adicionar um novo nome em conflito pode renumerar os sufixos existentes, então evite nomes que só diferem em separadores ou em maiúsculas e minúsculas. A mesma variável recebe o mesmo identificador seja qual for o filtro usado (collection, include=strings ou um token limitado a algumas coleções): os nomes são definidos primeiro no projeto inteiro e a resposta é filtrada depois.

?collection=<name> limita a saída a uma coleção (400 unknown_collection se o nome não estiver no projeto). ?view=ai@1 retorna uma visão compacta e higienizada para agentes de IA (só nomes e valores, sem valores de texto por padrão); não dá para combinar com format, e qualquer outro valor de view além de index (abaixo) retorna 400 unknown_view.

?view=index junto com format retorna, em vez de código, o identificador que cada variável recebe naquele formato — para conferir nomes sem analisar o código gerado. Os identificadores são escritos como na saída (palavras-chave do Swift/Kotlin mantêm as crases). Variáveis de texto (STRING) ficam fora do índice, a menos que o token tenha sido emitido com valores de texto e você passe include=strings. view=index sem format retorna 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 lista os formatos e versões que este servidor oferece, com o rev atual, o nome de arquivo e o Content-Type de cada um. Usa o mesmo token, não conta para o uso nem para o limite de solicitações e aceita ETag/If-None-Match como o endpoint de variáveis (sem X-VJ-Stamp — a lista é estática). Uma versão substituída também traz "deprecated": { "since": "YYYY-MM-DD", "sunset": "YYYY-MM-DD" }; sunset só aparece quando há uma data marcada.

{
  "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 e ETag

As respostas incluem um cabeçalho ETag. Envie-o de volta como If-None-Match e você recebe 304 (sem corpo) quando nada mudou — economizando banda nas verificações periódicas de apps móveis e da CI. Use o valor de ETag recebido como está (ele pode incluir W/).

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

Toda resposta 200 ou 304 traz estes cabeçalhos:

Erros

As respostas de erro têm o corpo { "error": "<código>" }.

Servidor MCP (IDE / agentes de IA)

Em IDEs e agentes de programação com IA, o servidor MCP @variablejar/mcp é mais prático que o REST — o mesmo token serve para os dois. Você pode passar esta página para um agente de IA e pedir que ele configure a integração para você.

Adicione à sua configuração de MCP (fixe a versão):

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

O local do arquivo depende do cliente:

Ferramentas disponíveis:

O servidor mantém os resultados só na memória, verifica a API de novo uma vez por TTL (30–600 s) e reaproveita tudo enquanto o selo de atualização do projeto não mudar. Os resultados das ferramentas trazem os códigos de erro da API (error: unauthorized, error: plan_required, …); quando não é possível alcançar a API, o último resultado é entregue com uma nota sobre a idade dele. Os dados de tokens vêm envolvidos em marcadores de limite aleatórios, com um preâmbulo fixo dizendo que são dados, não instruções.

Variáveis de ambiente:

Atualizando a partir da 0.2.0: essa versão chama um endpoint desativado e agora recebe 410. Os nomes das ferramentas não mudaram e as entradas só ganharam acréscimos, mas as saídas mudaram — list_tokens é paginado, com uma primeira linha total=… e chaves curtas (c, k, t, v); get_token retorna as mesmas chaves curtas e lista os candidatos quando a chave existe em várias coleções; list_collections não retorna mais ids; e get_tokens retorna um bloco de preâmbulo mais um bloco de código dentro de marcadores de limite.

O servidor é somente leitura — o token não consegue gravar nem excluir nada.

Observações

• Não chame direto de um navegador (frontend web) — o token ficaria exposto no código do cliente. Use em servidores, apps ou CI, onde o token fica escondido.
• Ainda não há APIs de gravação nem consultas delta (só mudanças).
• Para contexto de LLM, a documentação completa está disponível em /llms.txt (índice) e /llms-full.txt (tudo num arquivo só), em inglês.