---
title: "Hasura-compatible metadata API"
method: POST
path: "/v1/metadata"
tags: ["metadata"]
---

# Hasura-compatible metadata API

`POST /v1/metadata`

Dispatches on `args.type` to per-op handlers. Operations not yet migrated off the Hasura proxy return `{code: "not-supported"}`. Admin-only: requests without a valid `X-Hasura-Admin-Secret` header are rejected with 401 (no JWT fallback).

## Request body

- MetadataRequest
  - `type` string, required — Operation discriminator (e.g. `export_metadata`, `pg_track_table`)
  - `args` unknown
  - `version` integer — Metadata API version (1 or 2; defaults to 1)
  - `resource_version` integer — Optimistic-concurrency token from the most recent `export_metadata`
  - `source` string — Source name when the op targets a specific data source

## Response `200`

Per-operation result. The body shape varies by `type`: most ops return `{message: "success"}`, `export_metadata` returns `{resource_version, metadata}`, etc. Modelled as a freeform object until per-op schemas are migrated into this spec.

- object

## Other responses

- `400` — Op-level validation failure (`MetadataError`: `{code, error, path, internal?}`). Spec-level failures — invalid JSON, type mismatches, missing required fields — are rejected earlier by the shared OpenAPI validator and return `ValidationError` (`{error, reason}`) instead. Both are 400 with `Content-Type: application/json`; client code that branches on the body must tolerate either shape (the presence of `code` distinguishes them).
- `401` — Missing or invalid admin secret. Emitted by the shared security middleware before the per-op handler runs, so the body shape is `AuthError` (`{error, reason, securityScheme}`), not `MetadataError`.

---

[API](https://skmtc.dev/nhost/apis/nhost-constellation-api.md) · [All operations](https://skmtc.dev/nhost/apis/nhost-constellation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhost/nhost-constellation-api/revisions/d676467fb711/schema)