Skip to main content
A briefing export is a CSV file of the management briefing, the same digest that 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 scope analytics: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
Keep the 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

Call GET /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 downloadUrl works 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.csv or management-briefing-weekly.csv.
  • Compare the SHA-256 of the bytes you received with checksum, and their length with byteSize. 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)
The figures are the same as those of 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 404 with the code common.not_found: request a new export.

When an export fails

If new exports keep failing, write to team@muveya.com with the exportId.

Errors