Skip to main content
POST
/
api
/
reports
/
{id}
/
generate
Generate report output
curl --request POST \
  --url https://clarus-api.com/api/reports/{id}/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '{}'
{
  "data": {
    "id": 123,
    "type": "documents",
    "attributes": {
      "category": "report",
      "file_name": null,
      "file_path": null,
      "file_type": null,
      "status": "queued",
      "user_id": 1
    }
  }
}

​
Workflow

  1. Call this endpoint — returns a Document with status: queued
  2. Poll the document status via GraphQL until status becomes available (or failed)
  3. Download the file via GET /documents/{id}/download to get a presigned S3 URL
  4. Use the presigned URL to download the generated report file

​
Request Body (Optional)

You can optionally pass variables to override the report’s stored variable values: 
{
  "variables": [
    { "name": "date_from", "value": "2024-01-01 00:00:00" },
    { "name": "date_to", "value": "2024-01-31 23:59:59" }
  ]
}
If no variables are provided, the report’s stored variables are used. Passed variables are merged with stored variables (passed values take precedence).

​
Variable Values

Variables support Chronic-style date parsing:
  • today 00:00:00 — start of today
  • 3 days ago — 3 days before now
  • beginning of month — first day of current month
  • 2024-01-15 09:00:00 — explicit date/time

​
Access Control

Only the report owner can generate it. Returns 403 if the authenticated user is not the owner.

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication. Use the client credentials or authorization code flow to obtain an access token.

​
X-Clarus-Subdomain
string
header
required

The subdomain/tenant name identifying which tenant's data to access. Required for all API requests.

Path Parameters

​
id
integer
required

The unique identifier of the report to generate

Body

application/json
​
variables
object[]

Optional variable overrides for report generation

Response

Report generation queued successfully. Returns a Document record.

​
data
object