API references
The AME API (Active Metadata Engine API) is the single control plane for the PDQ platform. Every component — INGEST, DLS, DWA, QPI, the DataOps Console and the Config UI — reads and writes its configuration, state and audit information through this one REST interface.
This page describes the API at capability level: what you can do with it and where each capability lives. The complete, always-current endpoint reference — parameters, schemas and example payloads — is generated from the running service.
Every installation publishes its own live contract:
- Swagger UI —
https://<your-ame-host>/docs - ReDoc —
https://<your-ame-host>/redoc - OpenAPI schema —
https://<your-ame-host>/openapi.json
If the service is mounted behind a path prefix, that prefix is included in the published contract.
Versioning
Endpoints are versioned in the path: /api/v3/..., /api/v3.1/..., /api/v3.2/..., /api/v4/....
- Use v3 and higher. The v3 surface is complete — including the scheduler — so an integration no longer needs to mix versions.
- A higher minor version supersedes a lower one within the same capability. Where both
/api/v3and/api/v3.2exist for source files,v3.2is the current contract. - v4 is a forward-looking contract surface for data products, currently covering model objects, source files and target-object-oriented mappings.
- Nothing is removed on upgrade. Older versions remain registered for backwards compatibility, but new work should target the newest version of each capability.
- Some capability areas are marked Deprecated in the OpenAPI tags even though v3 paths exist — see Legacy areas.
Authentication and authorisation
The API uses the OAuth2 password flow and issues bearer tokens.
POST /tokenwithusernameandpasswordas form fields.- Send the returned token as
Authorization: Bearer <token>on every subsequent request.
Three account properties govern what a token may do:
| Property | Effect |
|---|---|
| Disabled | All requests are rejected. |
| Read-only | GET is permitted; POST, PUT, DELETE and PATCH are rejected. |
| Admin | Required for administrative operations. |
Passwords are stored using bcrypt_sha256. Existing legacy hashes remain valid and are upgraded when the password is next changed.
Capabilities
Administration and platform settings
Global configuration of the data platform installation and the metadata vocabulary used across it.
- Read and update global data platform settings — zone names, model and schema names, client type, storage integration, and naming conventions such as table-name casing and object key suffix.
- Maintain field categorisations — the field group and field domain hierarchy used to classify data. Categorisations are versioned on save rather than overwritten.
- Maintain documentation notes — free-form key/value notes attached to modules and surfaced through the documentation.
- Utility helpers for provisioning: generate a hash, generate a salt, encrypt a string.
Base paths: /api/v3/settings, /api/v3/fieldcategorizations, /api/v3/documentation/notes
Ingest
Everything INGEST needs in order to know what to extract, plus the run control and monitoring around it.
- Connections — manage source system connections and data store connections, with credentials handled through the platform's encryption.
- Export definitions — create, read, update, delete and move ingest definitions between source systems; update extraction filters; set a start date for an extraction.
- Workload control — claim a workload for a worker, start a workload, mark it completed, request the next workload for a source system, and re-run a workload.
- Monitoring — list export run history over a time window, and list runs still in progress. Both are available per source system and across all systems, so a monitor does not need to fan out one call per system.
Base path: /api/v3/ingest/... — definition lifecycle at /api/v3.1/ingest/...
Source handler — source systems, source files and mappings
The data contract layer: what a source delivers, and how it maps onto the model.
- Source systems — list, read and update source system definitions.
- Source files — the definition of one delivered dataset. Create, replace, append to, read and delete a source file data contract. Structure is versioned, so a specific historical structure version can be retrieved.
- Field mappings — map source fields to target attributes, and organise mappings into mapping groups.
- Relationship mappings — define relationships between mapped objects, keyed on mapping number.
- Target-object-oriented mappings (v4) — read and write the same mappings organised by target object rather than by source field.
Base paths: /api/v3/systems, /api/v3.2/sourcefiles/..., /api/v4/sourcefiles/...
Data models
The business model that DWA automates against.
- Objects — read, create, replace and delete model objects. A complete object, including its attributes, can be posted in a single call.
- Attributes and relations — read, create and delete individually.
- Subject areas — define subject areas, and attach or detach objects from them.
- Loading patterns — read and set the loading pattern for an object.
- Data product contract (v4) — read a model object expressed as a data product contract.
Base paths: /api/v3.1/model/..., /api/v4/model/...
Source scheduler
Orchestration of flows — a flow being the scheduled processing of one source file through its load steps.
- Schedules — read and maintain the master schedule and the working schedule, per source file or by time window; read a flow's state, type and next step; set state.
- Run control — start a flow, re-run a known run from a chosen step and everything downstream, or restart the current run so that only unfinished steps execute.
- Bulk operations — set state in bulk, and skip steps by marking them completed without executing them, which unblocks a stalled chain.
- Processor steps — read and set state for extra-processor steps in the chain.
Base paths: /api/v3/schedule/..., /api/v3/master/schedule/...
Extra processors
Custom processing steps that run as part of a flow.
- Define, read and delete extra processors, and look them up by name or type.
- Inspect incomplete extra-processor runs and the execution task log.
Base path: /api/v3/extraprocessor
Audit and data contracts
The audit trail produced by DLS as data moves through the zones, and the promotion of an observed profile into an agreed contract.
- Batches and logs — read and write audit batches and the audit log for a load.
- Profiles per zone — read the audit of a source file per processing zone, and promote a specific profile to be the data contract for that source file.
- Definition sync — sync a complete observed file structure from audit into the source file definition.
- Publisher audit — audit and statistics for published source files and published tables, queryable by date range.
- Triggers — trigger a restart or a skip for one or more files (with a skip reason), create triggers from a list for a zone, and register an undefined blob file for reprocessing.
- Loading statistics — read and write per-load statistics.
Base paths: /api/v3/audit/..., /api/v3/sourcefiles/{sourcefile}/audits, /api/v3/statistics
Quality Performance Indicator (QPI)
The data quality framework, built as an asynchronous operator/worker subsystem. The API never executes probe SQL itself: it mints a run key, queues the work, and records the outcome.
- Definitions — create, read, disable and delete QPI definitions, and validate a probe command before saving it.
- Execution — trigger a run and receive a single run key covering the whole batch; log run start and finish; poll for completion; read results and execution statistics.
- Status — list incomplete runs and read the execution log.
- Dependencies — find which QPIs depend on a given flow, and trigger exactly those when the flow completes.
- Settings — read and update QPI subsystem settings.
Base path: /api/v3/qpi/...
System health
Operational status of the platform, intended for dashboards and alerting.
- Summary — an overall health score across a time window.
- Runtime log and metrics — the runtime job trace with derived severity levels.
- Job log, metrics and status — job execution history and current status.
All endpoints accept a time window and a row limit.
Base path: /api/v3/systemhealth/...
OpenLineage
Lineage published in the OpenLineage format, so the platform can be consumed by external catalogue and lineage tools.
- Read a dataset with its schema and lineage facets for a given load step, optionally scoped to a source file or file key, at summary or detail level.
Base path: /api/v3/openlineage/dataset
Legacy areas
These areas are still exposed at v3 but are marked Deprecated in the OpenAPI tags. They remain available for existing integrations; prefer the capabilities above for new work.
| Area | Capability |
|---|---|
| Deviations | Bad-data type conversions and samples, bad-loading detection, and dangling-record detection with fix and reload helpers. |
| Monitors | Source export failures and export log, and restart of a source export. |
| Data lineage | Trace a value backwards through the transformation layers, from the model or from the source. |
| Importer | The v2 predecessor to Ingest. Superseded by /api/v3/ingest/.... |
Conventions
- Format — JSON request and response bodies. Responses carry a status and a message alongside the payload.
- Status codes — standard HTTP semantics.
401for an invalid or expired token,403for a disabled account, a read-only account attempting a write, or a missing admin privilege,404for a missing record, and504when a repository query exceeds the configured statement timeout. - Errors — database errors are translated into readable descriptions before they reach the response; verbose tracebacks are not returned.
- Descriptions — description fields are capped at 255 characters across the model and source file schemas.