GET /v1/analytics/briefing returns: alerts, delivery exceptions, pending approvals, consumption and cycle times. muveya builds the file in the background, so the flow has three steps: request it, poll it, download it.
POST /v1/analytics/exports is the only operation on /v1 that writes anything, and what it writes is the export job itself. It changes nothing in your operation.
Who can do it
A key with the scopeanalytics:read (see Scopes). The same scope covers requesting, polling and downloading.
The flow
Step 1: request the export
string
default:"daily"
The briefing cadence:
daily or weekly. Any other value is refused with 400 and the code common.invalid_request. The body is optional; without it you get a daily briefing. Send no other field.string
default:"en"
The language of the
label column in the CSV: en, es or pt. It is fixed when you request the export, because the file is built later. Metric keys, dimensions, units, values and evidence ids are the same in every language.202 Accepted
exportId: it is the only handle to the job.
There is no idempotency key for this operation. Every
POST creates a new, independent export job. If a request times out before you receive the exportId, send it again; the extra job is harmless and is deleted with the others after 7 days.Step 2: poll until it is ready
CallGET /v1/analytics/exports/{exportId} every few seconds (for example, every 3 seconds). Each poll counts toward your rate limit.
200 OK (building)
200 OK (ready)
string
required
The job id you received when you requested the export.
string
required
pending, building, ready or failed.string
required
The report in the file. Always
briefing today.string
required
daily or weekly, as requested.integer
The size of the file in bytes. Present once
ready.string
The SHA-256 of the file, as 64 lowercase hexadecimal characters. Present once
ready.string
A signed download link. Present only when
ready. A new link is issued on every poll.string
When the current
downloadUrl stops working (UTC).string
A machine-readable reason. Present when
failed. A job that failed once and was retried automatically keeps this field while building and after it becomes ready, so always check status first.Step 3: download and verify
- The
downloadUrlworks for 5 minutes after the poll that returned it. It carries its own signature: do not add your API key or any other header to the download request. - Download right away. Do not store the link or share it: while it is valid, anyone who has it can download the file. If it expired, poll the job again to get a fresh link.
- The file name is
management-briefing-daily.csvormanagement-briefing-weekly.csv. - Compare the SHA-256 of the bytes you received with
checksum, and their length withbyteSize. If they differ, download again.
Complete example
The CSV file
- Encoding UTF-8 with a byte order mark, so spreadsheet programs open accents correctly. Lines end with CRLF.
- One header row, then one row per briefing figure.
- Cells that contain a comma, a quote or a line break are quoted. A cell that starts with
=,+,-,@, a tab or a carriage return is prefixed with a single quote ('), so that a spreadsheet never runs it as a formula.
management-briefing-weekly.csv (excerpt, Accept-Language: en)
GET /v1/analytics/briefing for the same period at the moment the file was built. Supply names appear as they are in your catalog. For what each metric means, see Management analytics.
What the file never contains
The export is redacted by construction: it holds counts, quantities, durations, labels and evidence ids. It never contains costs, order values, patient references or the names of team members. It covers every location and warehouse of the dental clinic, like any other API key read.What muveya records
- Each request is recorded in the audit trail of your dental clinic, with the API key as the actor, the report type and the period.
- When the file is built, the audit trail also records its size and its SHA-256 checksum, so the file you hold can be checked against the record later.
- Export jobs are kept for 7 days after the request. After that, polling the job returns
404with the codecommon.not_found: request a new export.
When an export fails
If new exports keep failing, write to team@muveya.com with the
exportId.