Meta API

Reference for the meta.svc HTTP surface. For concepts see the Meta block docs.

The API is mounted at the server root. /health and /ready are plain endpoints; everything else goes through the middleware chain: auth → conditional requests → compression (gzip/zstd).

Auth is a cascade — any one of: API key (X-Api-Key), certificate-derived JWT, or tenant JWT. Tenant headers X-Customer, X-Product, X-Env, X-Tenant populate context; X-Customer selects the customer whose repositories are visible. Per-repo JS access rules (access.read / access.write) and license entitlements apply after authentication.

Conditional requests: every file read returns a SHA-256 ETag; send If-None-Match to get 304s.

All read routes accept ?version=<name>&versionType=branch|tag.

Product routes — `/product/{id}/…`

Files (the preferred surface)

Method	Path	Purpose
GET	`files`	Directory listing (`?path=&depth=`)
GET	`file/{path…}`	Raw bytes + ETag
POST	`batch`	`{"paths":[…]}` → `{"files":[{path,content,hash,size,error}]}`
POST	`resolve`	`{"path","have":{hash:path},"depth"}` → server-side transitive `import:` resolution; returns only what the client is missing
GET	`manifest`	Merkle tree of the repo → `{root_hash, entries:[{path,hash,size,mod_time,is_dir}]}` — cheap “did anything change?” sync

Git

Method	Path	Purpose
GET	`git/refs`, `git/version`	Refs / current HEAD
POST	`git/status`, `git/diff`, `git/fetch`, `git/pull`, `git/reset`, `git/stage`, `git/commit`, `git/push`	Porcelain over the working tree (local repos, used by the authoring UI)
PATCH	`git/patch`	Apply a patch
PATCH	`git/commitfile`	Write + stage + commit in one call — body `{"path","file"}`

Service reads

Method	Path	Purpose
GET	`service/{service}/config`	The critical endpoint — merged envelope for one block (see below)
GET	`service/{service}/datastore`	Merged datastore definition (params: `format`, `array`, `filepath`, `injectproduct`, `injectservices`, `onlyinjected`)
GET	`service/{service}/type/{type}[/file[/{path…}]]`	Type-mapped reads (being retired — prefer `file/`)

Remote filesystem

Read-only stat/read surface used by clients that mount meta as a filesystem:

GET fs/stat/{path…} → {name,size,mode,mod_time,is_dir} · fs/readfile/{path…} · fs/readdir/{path…} · fs/exists/{path…} (never 404s).

Components

GET categories, categories/all, category/{category…}, component/{name}[/full], component/{name}/files/{path…}, components[/path/{path…}].

Writes (authoring; repo must not be `readonly`)

Method	Path	Purpose
PUT / DELETE	`files`	mkdir / rmdir
POST	`file/{path…}`	Upload (multipart field `files`)
POST	`zip/{path…}`	Upload a zip, expanded in place
POST / PUT	`type/{type}/file/{path…}`	Typed create / update
PUT	`type/{type}/rename`	Rename

Streams (SSE)

Stream	Purpose
`watch`	File-level change stream (snapshot-diff based)
`events`	Git HEAD push: `snapshot`, `repo-updated {repo,ref,hash,prevHash,ts}`, `ping` every 30s

The service-config envelope

GET /product/{id}/service/{service}/config is called by every block on every poll. Response:

{
  "load": true,
  "service": { "…": "the block's folder config" },
  "product": { "…": "product-level config" },
  "data":    { "…": "datastore definitions" },
  "version":     { "service": "…", "product": "…" },
  "lastupdated": { "service": "…", "product": "…" }
}

load is true only when the timestamps differ from the caller’s servicelastupdated / productlastupdated query params — a cheap no-op poll otherwise.

Standalone service routes — `/service/{name}/…`

Serves each block’s binary-embedded base definitions (GET /service/{name}/type/datastore, lastupdated). The server config’s services: block can override embeds for hotfixes.

Instance routes

Method	Path	Purpose
GET	`/repositories`	Registered repositories
GET	`/tenant-repositories`	Per-tenant on-demand repositories
GET	`/embedded-info`	What products are compiled into this binary
POST	`/license-activate`	`{"token"}` → entitlement map
GET	`/license-status`	Current entitlements
POST	`/license-deactivate`	Drop a license

Marketplace routes — `/market/{id}/…`

POST git/fetch · GET git/zip · GET fileorfolderzip/{path…} · GET file/{path…} · PATCH paths (batch read) · GET components/{path…} · POST index · DELETE indexdocuments · DELETE index.

Errors

Code	Meaning
`META_READONLY`	Write against a read-only repo
`META_NOT_LOCAL`	Git porcelain against a non-local repo
`META_MISSING_CUSTOMER`	No `X-Customer` header and no JWT customer claim
”given version is not allowed”	`?version=` outside the repo’s `allowedversions`
403	Entitlement/access-rule denial