DocumentationAPI v1
Organisation Stackfile
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.
GET /api/v1/org/stackfile
POST /api/v1/org/stackfileAuthorization: Bearer vitna_key_...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/stackfileaccepts either aplatform(vitna_key_...) orpush(vitna_push_...) bearer credential and returns the canonical Stackfile alongside its SHA-256digest.POST /api/v1/org/stackfilerequires aplatformkey (routerandpushkeys answer403 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 inplan.unmanaged.workloads.
Export response (GET)
{
"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
}
}