WorkMesh Developers
Connect WorkMesh data to the tool you already use.
The WorkMesh External API gives approved Business connections governed access to stable Systems, Fields and records. Choose a simple reporting format for analytics tools or the richer REST contract for application integrations.
https://api.workmesh.work/v1
Availability is enabled per WorkMesh Business. Your Business administrator creates a Connection, grants Systems and supplies a bearer credential.
Overview
One governed API, several client-friendly representations
Every External API request uses the same Business-scoped bearer credential, scopes, System grants, Field governance, rate controls and usage accounting. The response representation changes to suit the client; the authority model does not.
Choose a connection style
Start from your client, not from API internals
| Client / use case | Recommended endpoint | Why |
|---|---|---|
| Power BI, Tableau, Qlik, Excel and straightforward reporting | /systems/{system_key}/records/flat | Root JSON array with WorkMesh Fields and linked Reference data promoted directly to columns. |
| CSV-oriented reporting or import tools | /systems/{system_key}/records.csv | Direct tabular CSV with no JSON expansion or Reference-table join step. |
| Custom REST application or middleware | /systems/{system_key}/records | Rich canonical JSON envelope with logical record metadata and typed Field values. |
| Warehouse or recurring synchronisation | /changes plus record endpoints | Use a high-water cursor to retrieve only material changes after the initial snapshot. |
Quick start
Call your first endpoint
Create a Connection in WorkMesh, grant the required Systems, copy the bearer credential when it is shown, then call the API.
List granted Systems
Every request receives an X-Request-Id response header for support and diagnostics.
Authentication
Business-owned bearer credentials
Send the credential in the HTTP Authorization header. WorkMesh does not accept External API credentials in query strings.
A credential is displayed once when created or rotated. WorkMesh stores only a protected digest. Do not place credentials in URLs, public source code or distributed browser/mobile client code.
Environments
Use the credential created for the environment you are connecting to
The normal API contract uses https://api.workmesh.work/v1. When connecting to a WorkMesh Test Business, use https://test.workmesh.work/v1 and the Test credential issued there. Test credentials use the wmk_test_ prefix; Production and Test credentials are not interchangeable.
API reference
Core read endpoints
/businessConnected Business identity.
/systemsSystems explicitly granted to the Connection.
/systems/{system_key}Current logical System metadata.
/systems/{system_key}/schemaCurrent governed Field dictionary.
/systems/{system_key}/recordsCanonical paged REST records.
/systems/{system_key}/records/flatReporting-friendly flat JSON array.
/systems/{system_key}/records.csvReporting-friendly CSV rows.
/systems/{system_key}/changesIncremental material changes using an opaque cursor.
/systems/{system_key}/records/{record_id}/historyGoverned immutable History when the Connection has history scope.
Reporting tools
Rows and columns without Power Query surgery
The flat JSON and CSV representations promote each authorised WorkMesh Field to a top-level column using its stable field_key. Record metadata uses reserved columns beginning with an underscore, such as _record_id, _state and _updated_at.
Reference Fields are denormalised for reporting. When a System Field links to a Flat, Hierarchical or Heatmap Reference Table, WorkMesh resolves the selected Reference row and adds its business values directly to the reporting row using <field_key>__<reference_field> columns. The reporting client does not need to retrieve a Reference ID and perform another join. Raw Reference row IDs and physical table names are not exposed.
Flat and Hierarchical Reference Fields follow the same rule: all configured business fields on the selected Reference row are projected under the owning System Field prefix. Heatmap References expose the selected horizontal axis, vertical axis and cell data points. Choice Fields may retain field__key/field__keys, and Person Fields may retain a governed field__id; Reference Fields themselves are expanded instead of returning an opaque Reference link.
Use /records/flat when the client handles JSON arrays well. Use /records.csv when you want the simplest tabular feed. Linked Reference values are already present as normal columns in both representations. Both count against the same Connection and Business usage controls as REST calls.
REST applications
Use the canonical envelope when your application needs richer semantics
The canonical records endpoint retains the structured response used for application integrations, including logical Reference identities where the application needs relationship semantics.
Restricted Fields are omitted server-side. Physical database names, table names, SQL columns and physical row IDs are not part of the customer API contract.
Paging and sync
Bounded extraction that scales beyond one page
Record endpoints default to 500 records and accept up to 1,000 per request, subject to the normal response-size guard. The canonical REST profile carries paging metadata in meta. Reporting profiles expose the same information in response headers, including X-WorkMesh-Next-Cursor, X-WorkMesh-High-Water-Cursor, X-WorkMesh-Record-Count and X-WorkMesh-Schema-Revision.
For recurring synchronisation, establish a high-water cursor, take the current snapshot, then use /changes?cursor=... to retrieve later material changes.
Usage
Every representation is measured against the same Business usage ledger
WorkMesh records bounded request metadata including Connection, credential, endpoint, records returned, response data size, status and duration. Business administrators can review current-month and lifetime API usage, including data volume by credential. Payload values and bearer secrets are not stored in the request ledger.
Where a Business contract later includes a monthly External API data allowance, the same measured usage can be shown against that allowance. No separate reporting-tool bypass exists.
Limits
Protect normal integrations without forcing tiny pages
| Guardrail | Starting contract |
|---|---|
| Requested page size | 500 default; maximum 1,000 |
| Normal response target | Approximately 5 MiB uncompressed; a page may stop earlier |
| Concurrency | Up to 5 concurrent requests per credential unless configured otherwise |
| Request rate | Up to 60 requests/minute per credential unless configured otherwise |
| Business protection | Aggregate Business limits also apply so multiple credentials cannot multiply capacity without bound |
When throttled, WorkMesh returns HTTP 429 plus Retry-After when appropriate and rate-limit headers.
Errors
Stable machine codes and a useful request ID
| Status | Meaning |
|---|---|
| 400 | Malformed request or invalid cursor. |
| 401 | Missing, invalid, expired, revoked or wrong-environment credential. |
| 403 | Credential is valid but the Business capability or required scope does not allow the operation. |
| 404 | Resource does not exist or is intentionally indistinguishable from inaccessible. |
| 410 | Change or record cursor expired or was invalidated by a continuity-breaking restore. |
| 429 | Credential or Business protection limit reached. |
| 500/503 | Unexpected server or temporary service/configuration failure. |
Security
Fail closed and preserve Business isolation
A bearer credential resolves its authoritative Business before WorkMesh opens a tenant database. The client cannot supply a trusted Business ID to redirect that credential into another Business. Connection scopes, System grants and Field policies narrow access further, regardless of whether the client chooses REST JSON, flat JSON or CSV.
WorkMesh stores bounded operational metadata for usage, support and platform protection. It does not store unrestricted Business response bodies in the External API request ledger.