Admin API

The admin API is a Strawberry GraphQL endpoint at POST /admin/graphql (REQ-533). It requires a superuser or admin role (REQ-125, REQ-060) and is separate from the data GraphQL endpoint (REQ-533).

Authentication

Pass your credentials in the Authorization header using the standard Provisa auth provider (REQ-120):

Authorization: Bearer <token>

Admin access is governed by the admin capability assigned to a role (REQ-060, REQ-042).

Capabilities

Config Management

Download the current running config (REQ-164):

GET /admin/config

Returns the full config.yaml as a YAML file. Upload a new config (REQ-164):

PUT /admin/config

Provisa validates the YAML, reloads catalogs, and regenerates schemas (REQ-012, REQ-253). No restart required.

Runtime Settings

Read and write runtime platform settings without editing the config file (REQ-165):

GET  /admin/settings
PUT  /admin/settings

The settings surface covers large-result redirect, default sampling and row limit, response-cache TTL, naming convention, relationship FK auto-tracking, materialization-store DSN, federation-engine memory (jvm_heap_gb, query_max_memory, query_max_memory_per_node, query_max_total_memory, fault_tolerant_execution, fault_tolerant_task_memory, exchange_spool_dir), and the full OpenTelemetry tracing-pipeline tuning surface (REQ-1082). Remote-GraphQL traversal limits and warm-tier/read-cache settings are also exposed (REQ-1081, REQ-1083).

Security posture — security.mode (standard | high) — applied on restart (REQ-1079):

GET  /admin/security
PUT  /admin/security

AI model assignments, the embedding/vector-model registry, and the NL rate limit — applied on restart (REQ-1080):

GET  /admin/ai-models
PUT  /admin/ai-models

The admin encryption tab derives its provider list live from the encryption registry; unavailable providers appear but are not selectable (REQ-1091).

GET/HEAD /health and GET /setup/status are always unauthenticated — they bypass the Authorization: Bearer requirement even when an auth provider is configured (REQ-539).

Relationship Editor

List relationships (REQ-166):

query {
  relationships {
    id
    sourceTableId
    targetTableId
    sourceColumn
    targetColumn
    cardinality
    materialize
  }
}

Create a relationship (REQ-019):

mutation {
  upsertRelationship(input: {
    id: "orders-to-customers"
    sourceTableId: "orders"
    targetTableId: "customers"
    sourceColumn: "customer_id"
    targetColumn: "id"
    cardinality: "many_to_one"
  }) {
    success
  }
}

AI Relationship Discovery

Trigger Claude-powered FK analysis via REST (REQ-167, REQ-018):

curl -X POST http://localhost:8001/admin/discover/relationships \
  -H "Content-Type: application/json" \
  -d '{"scope": "domain", "domain_id": "sales"}'

Returns FK candidates ranked by confidence. Accept a candidate:

curl -X POST http://localhost:8001/admin/discover/candidates/{id}/accept \
  -H "Content-Type: application/json" \
  -d '{"name": "orders_to_customers"}'

Schema Introspection

Browse published tables across all sources (REQ-008):

query {
  tables {
    id
    sourceId
    columns {
      columnName
      unmaskedTo
      writableBy
    }
  }
}

View Management

Register a materialized view (REQ-133, REQ-135):

mutation {
  registerTable(input: {
    viewSql: "SELECT o.id, o.amount, c.name FROM orders o JOIN customers c ON o.customer_id = c.id"
    mvRefreshInterval: 300
    materialize: true
  }) {
    success
  }
}

Trigger a manual refresh (REQ-135):

mutation {
  refreshMv(mvId: "orders-with-customers") {
    success
  }
}

Graph Source Registration

Neo4j and SPARQL sources are registered via REST endpoints (not the GraphQL admin API) (REQ-295, REQ-297):

Neo4j:

# 1. Register the Neo4j source
curl -X POST http://localhost:8001/admin/sources/neo4j \
  -H "Content-Type: application/json" \
  -d '{"source_id": "graph", "host": "neo4j", "port": 7474, "database": "neo4j"}'

# 2. Preview a Cypher query (validates scalar projections)
curl -X POST http://localhost:8001/admin/sources/neo4j/graph/preview \
  -H "Content-Type: application/json" \
  -d '{"cypher": "MATCH (p:Person) RETURN p.name AS name, p.age AS age"}'

# 3. Register a table (runs preview+validate automatically)
curl -X POST http://localhost:8001/admin/sources/neo4j/graph/tables \
  -H "Content-Type: application/json" \
  -d '{"table_name": "people", "cypher": "MATCH (p:Person) RETURN p.name AS name, p.age AS age", "ttl": 300}'

SPARQL:

# 1. Register the SPARQL source
curl -X POST http://localhost:8001/admin/sources/sparql \
  -H "Content-Type: application/json" \
  -d '{"source_id": "kg", "endpoint_url": "http://fuseki:3030/ds/sparql"}'

# 2. Register a table (probes endpoint and infers columns)
curl -X POST http://localhost:8001/admin/sources/sparql/kg/tables \
  -H "Content-Type: application/json" \
  -d '{"table_name": "products", "sparql_query": "SELECT ?name ?category WHERE { ?p a :Product ; :name ?name ; :category ?category . }", "ttl": 600}'

Once registered, tables appear in the GraphQL schema and are queryable like any other source (REQ-016).

GraphiQL

The admin API ships with GraphiQL at GET /admin/graphql in the browser (REQ-622). Use it to explore the full admin schema interactively.