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"
        }
      ]
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/reports"

payload = { "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"
                }
            ]
        }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'}
        ]
      }
    }
  })
};

fetch('https://clarus-api.com/api/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
        }
      ]
    }
  }
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

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"
        }
      ]
    }
  }
}
'

import requests

url = "https://clarus-api.com/api/reports"

payload = { "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"
                }
            ]
        }
    } }
headers = {
    "Authorization": "Bearer <token>",
    "X-Clarus-Subdomain": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Clarus-Subdomain': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'}
        ]
      }
    }
  })
};

fetch('https://clarus-api.com/api/reports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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"
        }
      ]
    }
  }
}

{
  "error": "<string>"
}

{
  "errors": [
    {
      "code": 123,
      "symbol": "<string>",
      "details": "<string>",
      "source": "<string>",
      "context": {}
    }
  ]
}

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

Field	Required	Description
`name`	Yes	Report name (max 50 chars)
`report_type`	Yes	Output type: `single` (table), `bar` (bar chart), `pie` (pie chart)
`report_query_id`	Yes	ID of the report query to use
`source_path`	No	Dot-notation path to data in GraphQL response. Must start with `data.` (e.g., `data.tasks.aggregation`, `data.stocks.all.edges`)
`description`	No	Report description (max 500 chars)
`report_fields`	No	Array of field definitions for the report output
`variables`	No	Array 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

Show child attributes

Response

Report created successfully

data

object

Show child attributes

⌘I

​Request Structure

​Key Fields

​source_path

​Variables

Authorizations

Body

Response

Request Structure

Key Fields

source_path

Variables