ObjectStackMetadata & Package API
REST endpoints for object schemas, metadata types, UI views, and package management.
Manage object schemas, metadata types, UI views, and installed packages over REST. All paths are relative to the base URL (defaults to /api/v1) — see the API Overview for discovery and service availability.
Metadata
Retrieve and manage object schemas, metadata types, and UI views. Always available — provided by the kernel.
A type segment these routes cannot recognise, but which reaches for a metadata type the
platform declares, is refused 400 INVALID_REQUEST rather than served — see
unrecognised type spelling
in the error catalog for the envelope and the correction it names.
GET /meta
List all registered metadata types.
Response: { types: ["object", "view", "plugin", ...] }
GET /meta/:type
List all items of a metadata type.
| Parameter | Location | Description |
|---|---|---|
type | path | Metadata type name — the singular spelling (object, view, flow) |
Metadata type names are singular (Prime Directive #3) and this segment is the
type name itself, so the spelling to send is object — never objects. The
plurals elsewhere in this API name something else: a collection of records
(/data/:object) or a package-manifest key (objects: [...]). Neither carries
across to a /meta type segment.
Listing applies the ADR-0046 §6.7 audience gate to books and docs, RBAC filtering to privileged apps, and the usual response shaping.
Response: { type: "object", items: [{ name: "account", ... }, ...] }
GET /meta/:type/:name
Get a specific metadata item with optional ETag caching.
| Parameter | Location | Description |
|---|---|---|
type | path | Metadata type name |
name | path | Item name (snake_case) |
If-None-Match | header | ETag for conditional request |
Response: { type: "object", name: "account", item: { ... } }
304 if ETag matches (not modified).
PUT /meta/:type/:name
Create or update a metadata item.
Creates are gated per type: MetadataTypeRegistryEntry.allowRuntimeCreate decides
whether a brand-new name may be minted under that type at all, separately from
whether an item that already exists may be overlaid (allowOrgOverride). A type that
declines the create half still accepts updates to names that already exist, and its
refusal — 403 NOT_CREATABLE — names the route that does work. The flags are
documented on
MetadataTypeRegistryEntry;
which types currently decline which half is tracked in the
overlay whitelist
rather than enumerated on this page, so this caveat doesn't go stale the next time a
type is retired.
This verb also refuses a :type segment that is not a metadata type the platform
declares at all — not a recognised spelling, and not a misspelling of one either —
with 400 INVALID_REQUEST, before any namespace is minted for it. The refusal is
scoped to this verb: GET and DELETE on an item that already exists are
unaffected. See unrecognised type spelling
in the error catalog for the envelope — the same code and status cover both this
refusal and the misspelling one above; the message text tells them apart.
Body: { type: "object", name: "account", item: { ... } }
Response: { success: true }
GET /ui/view/:object/:type
Get an auto-generated UI view for an object.
| Parameter | Location | Description |
|---|---|---|
object | path | Object name (snake_case) |
type | path | list or form |
Response: Full ViewSchema definition with columns/fields derived from the object schema.
Package Management
Manage installed plugins/packages.
GET /packages
List installed packages.
POST /packages
Install a package from its manifest (SDK: client.packages.install). Re-installing an
already-installed id returns 409 Conflict unless overwrite: true.
Body: { manifest: { id: "plugin-auth", name: "Plugin Auth", version: "1.0.0", ... }, settings?: { ... }, enableOnInstall?: true, overwrite?: false }
Response: { package: { id: "plugin-auth", version: "1.0.0", ... }, message?: "..." }
POST /packages/publish
Publish a package (manifest + metadata) to the package marketplace registry. This is publisher tooling, not part of the app SDK surface.
Body: { manifest: { id: "plugin-auth", name: "Plugin Auth", version: "1.0.0", ... }, metadata: { objects: [...], views: [...], ... } }
Response: { success: true, message: "...", package: { id: "plugin-auth", version: "1.0.0" } }
GET /packages/:id
Get package details.
DELETE /packages/:id
Uninstall a package.
PATCH /packages/:id/enable
Enable a disabled package.
PATCH /packages/:id/disable
Disable a package without uninstalling.
See also
- API Overview — discovery, error handling, and protocol types
- Data API — CRUD, batch operations, and analytics