> Source: https://vitna.ai/docs/api/v1/engine/org-stackfile
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/org-stackfile.md
> Corpus index: https://vitna.ai/llms.txt

# 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/stackfile
```

```
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](../../../routing/stackfile.md) 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
  }
}
```
