Skip to main content
POST
/
api
/
reports
Create a report
curl --request POST \
  --url https://clarus-api.com/api/reports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Clarus-Subdomain: <api-key>' \
  --data '
{
  "data": {
    "type": "reports",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "report_type": "bar",
      "report_query_id": 1,
      "source_path": "data.tasks.aggregation",
      "report_fields": [
        {
          "name": "Task Type",
          "path": "task_type.code"
        },
        {
          "name": "Tasks Left To Do",
          "path": "total_records"
        }
      ],
      "variables": [
        {
          "name": "created_at_from",
          "value": "start of today",
          "prompt": "true"
        },
        {
          "name": "created_at_to",
          "value": "end of today",
          "prompt": "true"
        }
      ]
    }
  }
}
'
{
  "data": {
    "id": 123,
    "type": "reports",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "report_type": "bar",
      "report_query_id": 1,
      "source_path": "data.tasks.aggregation",
      "report_fields": [
        {
          "name": "Task Type",
          "path": "task_type.code"
        },
        {
          "name": "Tasks Left To Do",
          "path": "total_records"
        }
      ],
      "variables": [
        {
          "name": "created_at_from",
          "value": "start of today",
          "prompt": "true"
        },
        {
          "name": "created_at_to",
          "value": "end of today",
          "prompt": "true"
        }
      ]
    }
  }
}

​
Request Structure

{
  "data": {
    "type": "reports",
    "attributes": {
      "name": "Count of Tasks Left To Do",
      "description": "Count of Tasks Left To Do by Task Type",
      "report_type": "bar",
      "report_query_id": 1,
      "source_path": "data.tasks.aggregation",
      "report_fields": [
        { "name": "Task Type", "path": "task_type.code" },
        { "name": "Tasks Left To Do", "path": "total_records" }
      ],
      "variables": [
        { "name": "created_at_from", "value": "start of today", "prompt": "true" },
        { "name": "created_at_to", "value": "end of today", "prompt": "true" }
      ]
    }
  }
}

​
Key Fields

FieldRequiredDescription
nameYesReport name (max 50 chars)
report_typeYesOutput type: single (table), bar (bar chart), pie (pie chart)
report_query_idYesID of the report query to use
source_pathNoDot-notation path to data in GraphQL response. Must start with data. (e.g., data.tasks.aggregation, data.stocks.all.edges)
descriptionNoReport description (max 500 chars)
report_fieldsNoArray of field definitions for the report output
variablesNoArray of variable values to pass to the report query

​
source_path

The source_path tells the system where to find data in the GraphQL response. It always starts with data. Common patterns:
  • data.{resource}.aggregation — for grouped/summarized results
  • data.{resource}.all.edges — for paginated lists (each item under node)
  • For paginated queries, report_fields paths must start with node. (e.g., node.warehouse.name)

​
Variables

Variables support Chronic-style date values (e.g., start of today, end of today, start of this month) which are parsed at report generation time. Variable names must match parameters defined in the linked report query.

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.

Body

application/json
​
data
object
required

Response

Report created successfully

​
data
object