Get started

Organisation Stackfile

Source

Export your organisation's live register as a canonical vitna.stackfile.v1 JSON document, preview a deterministic reconciliation plan (dryRun: true), or apply declarative register updates over HTTP.

text
GET /api/v1/org/stackfile
POST /api/v1/org/stackfile
text
Authorization: Bearer vitna_key_...
bash
curl -H "authorization: Bearer vitna_push_..." https://vitna.ai/api/v1/org/stackfile

curl -X POST "https://vitna.ai/api/v1/org/stackfile?dryRun=1" \
  -H "authorization: Bearer vitna_key_..." \
  -H "content-type: application/json" \
  -d '{
    "stackfile": {
      "schema": "vitna.stackfile.v1",
      "org": "convexity",
      "privateSkus": [],
      "workloads": [
        {
          "slug": "support-triage",
          "name": "Support triage",
          "classId": "model",
          "status": "active",
          "priority": "economics",
          "unitLabel": "tickets",
          "incumbentSkuId": "openai/gpt-5.6-luna",
          "monthlyVolume": 50000,
          "unitProfile": {
            "inputTokensPerUnit": 1800,
            "outputTokensPerUnit": 400
          },
          "constraints": {
            "qualityFloor": 90,
            "allowsProviders": ["openai", "anthropic"]
          },
          "delivery": {
            "policyAlias": "support-triage"
          }
        }
      ]
    },
    "dryRun": true
  }'

Scopes and reconciliation rules

  • GET /api/v1/org/stackfile accepts either a platform (vitna_key_...) or push (vitna_push_...) bearer credential and returns the canonical Stackfile alongside its SHA-256 digest.
  • POST /api/v1/org/stackfile requires a platform key (router and push keys answer 403 forbidden_scope).
  • Pass "dryRun": true (or ?dryRun=1) to validate the document and compute the exact action plan (workload.create, workload.edit, workload.status, private.add, private.price, candidate.add, fallback.remove, fallback.add, rule.add, watch.arm) without mutating the database.
  • Every action executes through registerStore, enforcing metered workload allowances (402 plan_allowance_exceeded), archived-workload immutability (409 workload_archived), and org scope (403 org_mismatch). Workloads omitted from the payload are never deleted; they are reported in plan.unmanaged.workloads.

Export response (GET)

json
{
  "stackfile": {
    "schema": "vitna.stackfile.v1",
    "org": "convexity",
    "privateSkus": [],
    "workloads": [
      {
        "slug": "support-triage",
        "name": "Support triage",
        "classId": "model",
        "status": "active",
        "priority": "economics",
        "unitLabel": "tickets",
        "incumbentSkuId": "openai/gpt-5.6-luna",
        "monthlyVolume": 50000,
        "unitProfile": {
          "inputTokensPerUnit": 1800,
          "outputTokensPerUnit": 400
        },
        "constraints": {
          "qualityFloor": 90,
          "allowsProviders": ["openai", "anthropic"]
        },
        "delivery": {
          "policyAlias": "support-triage"
        },
        "notes": null,
        "candidates": [],
        "fallbacks": [],
        "rules": [],
        "watches": []
      }
    ]
  },
  "digest": "6f3e4b2c1a9d8e7f0123456789abcdef0123456789abcdef0123456789abcdef",
  "meta": {
    "generatedAt": "2026-09-14T12:00:00.000Z",
    "orgId": "convexity",
    "workloadCount": 1,
    "privateSkuCount": 0
  }
}