The day you want to leave, your data leaves with you, complete. And what the API does not do is in writing.
With a new supplier, the reasonable fear is twofold: that the API promises what it does not have, and that your data will not come out complete when you need it. Here you get incremental sync to keep another system up to date, a full export to take everything with you, and a reference you can read without a key before you sign anything.
Integrations fail because of what was promised and was not there, not because of what was missing and was flagged up front. That is why this page starts with getting your data out and ends with the limits.
You take all your information with you, without asking anyone for it.
Twenty-two resources: assets with their photographs and documents, work orders with their full record — tasks, staff, materials, status history, attachments and signatures — incidents and readings.
It is not an instant download, because a serious data dump does not fit in a single web request. You request it, check its progress and download it when it is ready, through a signed URL that expires.
Request
You state which resources, from what date, whether deleted records are included and whether files are packaged. Generation starts immediately.
Track
Status, progress and row count, until it finishes.
Download
Signed URL, valid for one hour. The package stays available for seven days and is then purged automatically.
Requesting a resource the key has no permission for returns an error, not a dump that has been quietly cut short. An incomplete package that the integrator believes is complete is worse than a failure.
A ZIP that explains itself.
The data comes as NDJSON — one JSON object per line, one file per resource — rather than a single giant JSON. That way you can process the dump as a stream, without loading a file that may be close to a gigabyte into memory.
A manifest describes the package: format version, generation date — which is the starting point for the next sync — filters applied, and for each resource its file, its row count, whether it supports incremental reads and whether it reports deletions.
Photographs and documents are packaged separately, with their own index and the SHA-256 hash of each file, so integrity can be checked file by file.
- Geometries Always GeoJSON in EPSG:4326, reprojected by the server.
- Dates and identifiers ISO 8601 and UUIDs as text.
- Multilingual text Flattened to the language requested.
- Audit Every export is logged: who requested it, from which IP, with which filters, how many rows and the package hash. A full dump contains personal data, so the audit trail is not optional.
Five endpoints, each with a different purpose.
Worth keeping them apart: one tells you what you can read, one reads, one keeps things up to date, one takes everything and the last one opens work from outside.
| Endpoint | What it does |
|---|---|
/resources | Returns the catalogue of what that specific key can read, with its declared limits. |
/data/{recurso} | Reads any resource, with cursor-based pagination: assets, work orders and their full record, incidents, readings, photographs and documents. |
/sync | Incremental sync: what has changed since a given date, per entity, stating whether each record is new, modified or deleted. |
/exports | Asynchronous full dump of the entire organisation. |
/issues | Incident creation from an ERP or a control system, with the source system's external reference and protection against resubmission; lookup by external reference and a catalogue of types, criticalities and statuses to build the mapping table. |
Pagination is cursor-based, not by page number. Across millions of assets, skipping by offset forces the database to scan and discard everything before it on every page.
Keep another system up to date without downloading everything every night.
The difference matters when the inventory has a hundred thousand items. One endpoint returns everything that has changed since a given date, per entity, with cursor-based pagination. Your system stores its watermark and, on the next pass, asks only for the difference.
That is what lets you feed a corporate dashboard without downloading the whole asset portfolio every night.
Your system hears about a change when it happens, without asking every few minutes.
Maptainer emits outbound webhooks on work orders and incidents. It is the natural return path for incident creation through the API: the ERP reports the fault and Maptainer tells it about the work order, its closure and its outcome, with the external reference in every event.
Events are recorded in the same operation as the change, whether it comes from the web, the app, a scheduled task or the API, and if the change is rolled back the event is too. Each event states whether the change was made by an API key, so the receiver can recognise the echo of its own submissions.
- Work orders Created, any status change, and completed, validated, closed or cancelled.
- Incidents Created, any status change, and approved, resolved, closed or rejected.
- Alerts Alert escalated, when an alert moves up a level with the webhook channel.
- Signature Following the Standard Webhooks specification, with a secret shown only once that can be rotated without downtime.
Thirteen events in total. A status change produces both the generic and the specific event, so anyone who only wants closures subscribes just to "work order closed".
A key reaches what it was granted, and nothing more.
Each API key carries its list of scopes: assets:read, readings:read, work_orders:read, issues:read, inventory:read, personnel:read, files:read and export:full.
Creating incidents also requires the incident write permission, which is the API's only write operation. A key restricted to one customer can only create and see that customer's incidents.
A granted scope is not enough on its own: it is also checked against the modules the organisation has subscribed to, with the same check that governs a user’s permissions in the web application. A key with readings:read on an organisation without the readings module gets an explicit error, not an empty list.
A quota of 120 requests per minute per key, and 10 on the export endpoints, with the standard rate-limit headers and the wait time in the response.
A machine identity, with no user attached.
- Keys with their own prefix Recognisable at a glance in a log or a configuration file.
- Expiry Each key has its own expiry date.
- Scopes The key only reaches the entities and actions it was granted.
- Managed from the application Create, revoke and review, with configuration permissions.
What the API does not do, before you find out for yourself.
The API does not create or modify work orders: you can read them, with their full record, but they cannot be written from outside. The way for another system to open work is to create an incident, which goes through the same rules as the web — review, deadlines, alerts — and becomes a work order when appropriate. Nor does it write readings: they come in through the field app.
Each resource also publishes two flags, in the API itself and in the package manifest. Whether it supports incremental reads: some resources have no modification timestamp, so the date filter does not narrow them down and they are exported in full. And whether it reports deletions: only resources with soft deletion can tell you that something has gone.
Publishing those limits instead of hiding them is deliberate: it stops anyone building a replica with gaps while believing it is up to date.
Only one active export per organisation is allowed. A second request gets an error with the identifier of the export already in progress.
When the inventory lives in another system.
Maptainer can connect to external REST APIs to import an inventory that lives elsewhere and keep it up to date. That is the route if you already have an asset register and do not want to duplicate the source of truth.
Swagger and ReDoc, open without a key.
The public API reference is its own documentation, generated from the code and browsable without credentials. You can review all of it before signing anything.
Frequently asked questions
Can I create or modify work orders through the API?
Does the system notify my applications when something changes?
Can my ERP open work in Maptainer?
Can I take all my data with me?
Last updated:
The reference is open, and so is the functional documentation.
Your team can review both before the evaluation session. If a technical question is still open after that, the answer comes from the people who build the product.