Management API

The management API lets a front end or a script discover Business Central tables and fields, and create, update and delete custom endpoints. It was introduced in BI Endpoints 26.4.

https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/datawareness/management/v1.0/companies({companyId})/

Access

• Authentication is the same as for the data endpoints: a client credentials token with scope https://api.businesscentral.dynamics.com/.default. See Authentication.
• Permissions: no extra permission set. The app registration uses the DTW BI ENDPOINTS set it already holds for the data endpoints.
• Subscription: Premium. On Free every request fails with The management API requires a Premium subscription.
• Switch: enabled by default. An administrator can turn it off on BI Endpoints Setup with Disable Management API; every request then fails with The management API is disabled in this environment.
• Company scope: definitions are environment-wide. One created through one company's URL is immediately served in every company.

Entity sets

Entity set	Methods	Key	Purpose
tables	GET	tableId	Tables a custom endpoint may read from
tableFields	GET	tableId, fieldNo	Mappable fields of a table. A tableId filter, or tables({id})/tableFields, is required.
customEndpoints	GET, POST, PATCH, DELETE	endpointName	Custom endpoint definitions
customEndpointColumns	GET, POST, PATCH, DELETE	endpointName, colNo	Column mappings of a custom endpoint

Navigation: tables({id})/tableFields and customEndpoints('{name}')/customEndpointColumns, also with $expand.

Conventions

Content type	Content-Type: application/json on POST and PATCH
Concurrency	If-Match is required on PATCH and DELETE: *, or the @odata.etag from the last read (a mismatch returns 412)
Query options	$filter, $select, $orderby, $top, $skip, $count=true, $expand
Keys	customEndpoints('myEndpoint'), customEndpointColumns(endpointName='myEndpoint',colNo=5), tables(18)
Status codes	GET 200 · POST 201 · PATCH 200 · DELETE 204 · validation 400 · unknown key 404 · etag mismatch 412
Errors	{ "error": { "code": "Application_DialogException", "message": "…" } }, the message followed by a CorrelationId: suffix

Typical flow

1. Pick a table. GET tables?$filter=startswith(tableName,'Sales')&$select=tableId,tableName,tableCaption,standardEndpoints&$top=50. When standardEndpoints is not empty, a standard endpoint already exposes the table.

2. List its fields. GET tables(18)/tableFields?$select=fieldNo,fieldName,dataType,isPrimaryKey,defaultLabel. Primary key fields are mapped automatically and cannot be removed; defaultLabel is the column label they will get.

3. Create the endpoint, inactive:

   POST customEndpoints
   Content-Type: application/json
   
   {
     "endpointName": "legalMatters",
     "tableId": 167,
     "type": "Master Data",
     "description": "Matters (Job table) for the legal dashboard",
     "active": false
   }

   The response includes businessKeyFields, mappedColumnCount and dataUrl, the ready-to-use data URL.

4. Map the fields, one POST per field, in the order you want the columns. Omit colNo to take the next free slot:

   POST customEndpoints('legalMatters')/customEndpointColumns
   Content-Type: application/json
   
   { "fieldName": "Description" }

5. Review: GET customEndpoints('legalMatters')?$expand=customEndpointColumns.

6. Publish: PATCH customEndpoints('legalMatters') with If-Match: * and { "active": true }.

7. Read the data through customData; see Custom endpoints.

To change the source table or the name, delete the endpoint and create it again. PATCH customEndpointColumns(endpointName='legalMatters',colNo=2) with { "fieldNo": 20 } re-points a column; DELETE clears it.

Rules worth knowing

• Names are camelCase ([a-z][A-Za-z0-9]*) and cannot be a standard endpoint name or one of customData, biEndpoints, properties, relationships, referencedBy, applicationInfo, deletedEntries.
• Tables must be normal tables — not system tables, not the BI Endpoints app's own, not obsolete.
• Fields must be normal fields — no FlowFields or FlowFilters, no BLOB, Media or MediaSet. The five system fields (SystemId, SystemCreatedAt, SystemCreatedBy, SystemModifiedAt, SystemModifiedBy) can be mapped.
• 50 columns per endpoint, col1 to col50. A field can be mapped once.
• Relationships are derived: a mapped column whose field relates to a table served by another endpoint appears in relationships automatically.

The Postman collection in the Support Material has a Management API v1 folder with examples for Tables, Custom Endpoints and Custom Endpoint Columns. See Explore the endpoints.