Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.barekey.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
POST /v1/env/evaluate

Evaluate a single named variable and return its plaintext value. For ab_roll variables, the response includes which bucket was selected.

​
Request

curl -X POST https://api.barekey.dev/v1/env/evaluate \
  -H "Authorization: Bearer bk_at_..." \
  -H "Content-Type: application/json" \
  -H "x-barekey-request-key: req_abc123" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "production",
    "name": "DATABASE_URL"
  }'
Request body fields:
FieldTypeRequiredDescription
orgSlugstringYesOrg slug. Must match the org in the Authorization token.
projectSlugstringYesProject slug.
stageSlugstringYesStage name.
namestringYesVariable name.
declaredTypestringNoExpected type — validated against the stored declaredType. If provided and mismatching, returns INVALID_REQUEST.
seedstringNoSeed for deterministic ab_roll bucket assignment.
keystringNoNamespace key for deterministic evaluation. Used with seed.

​
Response

{
  "name": "DATABASE_URL",
  "kind": "secret",
  "value": "postgres://rds.example.com:5432/myapp",
  "declaredType": "string",
  "requestId": "req_01hx..."
}
For ab_roll variables: 
{
  "name": "CHECKOUT_FLOW",
  "kind": "ab_roll",
  "value": "redesigned",
  "declaredType": "string",
  "decision": "b",
  "requestId": "req_01hx..."
}
Response fields:
FieldTypeAlways presentDescription
namestringYesVariable name
kind"secret" | "ab_roll"YesVariable kind
valuestringYesPlaintext value
declaredTypestringNoThe stored declared type, if set
decision"a" | "b"ab_roll onlyWhich bucket was selected
requestIdstringYesRequest trace ID

​
Deterministic A/B evaluation

Pass seed and key to get a stable bucket assignment for a given user or context. Barekey computes: 
SHA-256("ab_roll:{name}:{seed}:{key}")
The hash is interpreted as a float between 0 and 1 and compared against the variable’s chance value. The same seed + key always returns the same bucket for the same variable. 
curl -X POST https://api.barekey.dev/v1/env/evaluate \
  -H "Authorization: Bearer bk_at_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "production",
    "name": "CHECKOUT_FLOW",
    "seed": "user_abc123",
    "key": "checkout-experiment-v1"
  }'

​
Error codes

CodeHTTPWhen
UNAUTHORIZED401Invalid or expired token
INVALID_JSON400Request body is not valid JSON
INVALID_REQUEST400Missing required field or type mismatch
INVALID_ORG_SCOPE403Token org doesn’t match orgSlug
VARIABLE_NOT_FOUND404Variable doesn’t exist in this stage
EVALUATION_FAILED500Decryption or resolution error
USAGE_LIMIT_EXCEEDED402Free plan evaluation limit reached
BILLING_UNAVAILABLE503Billing system temporarily unavailable

​
POST /v1/env/evaluate-batch

Evaluate multiple variables in a single request. More efficient than calling /v1/env/evaluate in a loop — one round trip, one billing event.

​
Request

curl -X POST https://api.barekey.dev/v1/env/evaluate-batch \
  -H "Authorization: Bearer bk_at_..." \
  -H "Content-Type: application/json" \
  -H "x-barekey-request-key: req_batch_xyz" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "production",
    "entries": [
      { "name": "DATABASE_URL" },
      { "name": "REDIS_URL" },
      { "name": "CHECKOUT_FLOW", "seed": "user_abc123", "key": "checkout-v1" }
    ]
  }'
Request body fields:
FieldTypeRequiredDescription
orgSlugstringYesOrg slug
projectSlugstringYesProject slug
stageSlugstringYesStage name
entriesarrayYesList of variable evaluation requests
Each entry in entries:
FieldTypeRequiredDescription
namestringYesVariable name
declaredTypestringNoExpected type for validation
seedstringNoSeed for deterministic ab_roll evaluation
keystringNoNamespace key (used with seed)

​
Response

{
  "results": [
    {
      "name": "DATABASE_URL",
      "kind": "secret",
      "value": "postgres://rds.example.com:5432/myapp",
      "declaredType": "string"
    },
    {
      "name": "REDIS_URL",
      "kind": "secret",
      "value": "redis://cache.example.com:6379",
      "declaredType": "string"
    },
    {
      "name": "CHECKOUT_FLOW",
      "kind": "ab_roll",
      "value": "redesigned",
      "declaredType": "string",
      "decision": "b"
    }
  ],
  "requestId": "req_01hx..."
}
Results are returned in the same order as the input entries array. If one variable is not found, the entire request returns VARIABLE_NOT_FOUND — there is no partial success.

​
POST /v1/env/pull

Fetch all variables for a stage and return them as a flat { [name]: value } map. Equivalent to barekey env pull in the CLI. This endpoint is designed for local development tooling and scripts that need all variables at once. For production application use, prefer /v1/env/evaluate or /v1/env/evaluate-batch which scope requests to specific variables.

​
Request

curl -X POST https://api.barekey.dev/v1/env/pull \
  -H "Authorization: Bearer bk_at_..." \
  -H "Content-Type: application/json" \
  -H "x-barekey-request-key: req_pull_xyz" \
  -d '{
    "orgSlug": "acme-42",
    "projectSlug": "backend-api-1234",
    "stageSlug": "development"
  }'
Request body fields:
FieldTypeRequiredDescription
orgSlugstringYesOrg slug
projectSlugstringYesProject slug
stageSlugstringYesStage name
seedstringNoSeed for deterministic ab_roll evaluation across all variables
keystringNoNamespace key (used with seed)

​
Response

{
  "variables": {
    "DATABASE_URL": "postgres://localhost:5432/myapp_dev",
    "FEATURE_ENABLED": "true",
    "CHECKOUT_FLOW": "original"
  },
  "requestId": "req_01hx..."
}
All values are plaintext strings, including boolean, int64, and json declared types — the pull endpoint does not coerce types. The CLI and SDK handle coercion on top of this response. ab_roll variables are evaluated using seed/key if provided, or randomly if not. There is no decision field in pull responses.

​
Error codes

The same codes as /v1/env/evaluate apply, plus:
CodeHTTPWhen
EVALUATION_FAILED500One or more variables failed to decrypt