Skip to content

REST API

Automate MDM with a stable JSON API, from entity lifecycle to row-level CRUD, approvals, and Enterprise integrations.

Overview

EntiHub exposes a REST surface under /api/v1.

  • OpenAPI 3 document: /swagger/v1/swagger.json
  • Swagger UI: /swagger for Global Admin users

Authentication

Supported modes:

  • Bearer token from Azure AD / Microsoft Entra ID
  • Cookie auth for browser sessions
  • Service principals for unattended automation
  • API key via X-API-Key

Examples:

curl -sS -H "Authorization: Bearer $TOKEN" https://mdm.contoso.com/api/v1/entities
curl -sS -H "X-API-Key: $ENTIHUB_API_KEY" https://mdm.contoso.com/api/v1/entities

Rate limiting

All /api/* endpoints are protected by per-client fixed-window rate limiting.

  • Default: 200 requests per 60 seconds
  • Configure with Mdm__RateLimit__PermitLimit and Mdm__RateLimit__WindowSeconds
  • Disable with Mdm__RateLimit__Enabled=false

When exceeded, the API returns:

{
  "code": "MDM_RATE_LIMIT",
  "message": "Too many requests. Please retry later."
}

Error format

Failed requests return RFC 7807 Problem Details:

{
  "type": "https://mdm.contoso.com/problems/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Column 'code' is required.",
  "code": "ENTITY_VALIDATION_REQUIRED_FIELD",
  "traceId": "00-abc123..."
}

Entity definition endpoints

GET    /api/v1/entities
GET    /api/v1/entities/summary
GET    /api/v1/entities/{name}
GET    /api/v1/entities/{name}/yaml
POST   /api/v1/entities/parse-yaml
POST   /api/v1/entities/validate
POST   /api/v1/entity-create
POST   /api/v1/entities/{name}
PUT    /api/v1/entities/{name}
DELETE /api/v1/entities/{name}

Deploy endpoints

POST /api/v1/entities/{name}/deploy
GET  /api/v1/entities/{name}/deploy/preview
POST /api/v1/entities/{name}/redeploy
POST /api/v1/entities/{name}/deploy/remove
POST /api/v1/entities/{name}/deploy/drop-archive-tables
GET  /api/v1/entities/{name}/deploy/history

Data endpoints

GET    /api/v1/entities/{name}/data
GET    /api/v1/entities/{name}/data/{id}
POST   /api/v1/entities/{name}/data
PUT    /api/v1/entities/{name}/data/{id}
DELETE /api/v1/entities/{name}/data/{id}?soft=true
POST   /api/v1/entities/{name}/data/{id}/restore
GET    /api/v1/entities/{name}/data/export?format=csv
GET    /api/v1/entities/{name}/data/time-travel-bounds
POST   /api/v1/entities/{name}/data/bulk
POST   /api/v1/entities/{name}/data/bulk-csv
POST   /api/v1/entities/{name}/data/bulk-action/preview
POST   /api/v1/entities/{name}/data/bulk-action/execute
GET    /api/v1/entities/{name}/saved-filters
POST   /api/v1/entities/{name}/saved-filters
POST   /api/v1/entities/{name}/similar
GET    /api/v1/entities/{name}/data/ref-options
GET    /api/v1/entities/{name}/data/column-suggestions

Approval endpoints

GET  /api/v1/entities/{name}/pending
GET  /api/v1/entities/{name}/pending/batches
POST /api/v1/entities/{name}/approve/{id}
POST /api/v1/entities/{name}/approve-batch
POST /api/v1/entities/{name}/reject/{id}
POST /api/v1/entities/{name}/reject-batch
GET  /api/v1/entities/{name}/versions/{id}
POST /api/v1/entities/{name}/versions/{id}/restore

Enterprise endpoints

GET    /api/v1/audit
GET    /api/v1/changes
GET    /api/v1/webhooks
POST   /api/v1/packages/export
POST   /api/v1/packages/deploy
GET    /api/v1/search/entities?q=text
GET    /api/v1/search/data?q=text&entity=Customer

Permissions & roles

GET    /api/v1/roles
GET    /api/v1/permissions
POST   /api/v1/permissions
GET    /api/v1/permissions/yaml
POST   /api/v1/permissions/yaml
GET    /api/v1/common-entities
POST   /api/v1/common-entities/{id}/install