# Create a report

`POST https://api.morevoice.ai/v1/reports`

Schedules a report: it is computed and emailed to its recipients on its cadence (the first send is `next_run_at`). Needs a live key.

Authenticate with a secret API key: `Authorization: Bearer $MOREVOICE_API_KEY`.

Operation ID: `reports_create`.

## Parameters

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MoreVoice-Version` | `string` | no | The API version to use for this request. Defaults to the version the API key is pinned to. |
| `Idempotency-Key` | `string` | no | A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice. |

## Request body

Required, `application/json`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | yes | — |
| `widgets` | `object[]` | yes | — |
| `cadence` | `object` | yes | — |
| `cadence.frequency` | `"daily" \| "weekly" \| "monthly"` | yes | — |
| `cadence.time` | `string` | yes | — |
| `cadence.day_of_month` | `integer` | no | monthly: 1–31, or -1 for the last day. |
| `cadence.days` | `("sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat")[]` | no | weekly: at least one weekday. |
| `cadence.timezone` | `string` | no | Default Asia/Jerusalem. |
| `enabled` | `boolean` | no | — |
| `filters` | `object` | no | — |
| `filters.agent_ids` | `string[]` | no | — |
| `filters.assistant_ids` | `string[]` | no | — |
| `filters.campaign_ids` | `string[]` | no | — |
| `filters.flow_ids` | `string[]` | no | — |
| `filters.queue_ids` | `string[]` | no | — |
| `filters.team_ids` | `string[]` | no | — |
| `formats` | `object` | no | Default: email and PDF. |
| `formats.csv` | `boolean` | no | — |
| `formats.email` | `boolean` | no | — |
| `formats.pdf` | `boolean` | no | — |
| `language` | `"he" \| "en"` | no | Default he. |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | no | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. Default yesterday. |
| `recipients` | `object[]` | no | — |

Example:

```json
{
  "cadence": {
    "frequency": "daily",
    "time": "08:00",
    "timezone": "Asia/Jerusalem"
  },
  "formats": {
    "email": true,
    "pdf": true
  },
  "name": "Daily contact-centre summary",
  "period": "yesterday",
  "recipients": [
    {
      "type": "email",
      "value": "ops@example.com"
    }
  ],
  "widgets": [
    {
      "key": "w1",
      "type": "kpis"
    },
    {
      "key": "w2",
      "params": {
        "sla_sec": 20
      },
      "type": "queues"
    }
  ]
}
```

## Responses

### 200 OK

OK Returns `Report`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | `"report"` | — |
| `id` | `string` | A report ID (prefix `rpt_`). |
| `livemode` | `boolean` | `true` in live mode, `false` in test mode. |
| `name` | `string` | — |
| `enabled` | `boolean` | Disabled reports are not sent on their schedule (they can still be sent now). |
| `widgets` | `object[]` | — |
| `period` | `"today" \| "yesterday" \| "last7" \| "last30" \| "thisWeek" \| "lastWeek" \| "thisMonth" \| "lastMonth"` | The window each report covers, in its time zone: `today`, `yesterday`, `last7`, `last30`, `thisWeek`, `lastWeek`, `thisMonth` or `lastMonth`. |
| `filters` | `object` | — |
| `filters.queue_ids` | `string[]` | Only these (queues); empty: all. |
| `filters.assistant_ids` | `string[]` | Only these (assistants); empty: all. |
| `filters.campaign_ids` | `string[]` | Only these (campaigns); empty: all. |
| `filters.agent_ids` | `string[]` | Only these (agents); empty: all. |
| `filters.team_ids` | `string[]` | Only these (teams); empty: all. |
| `filters.flow_ids` | `string[]` | Only these (flows); empty: all. |
| `cadence` | `object` | — |
| `cadence.frequency` | `"daily" \| "weekly" \| "monthly"` | — |
| `cadence.time` | `string` | Local send time, HH:MM (24-hour). |
| `cadence.days` | `("sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat")[]` | weekly: the weekdays it is sent on. |
| `cadence.day_of_month` | `integer \| null` | monthly: 1–31 (a shorter month sends on its last day), or -1 for the last day. |
| `cadence.timezone` | `string` | IANA time zone of `time` and of the period. |
| `recipients` | `object[]` | — |
| `formats` | `object` | — |
| `formats.email` | `boolean` | The report in the email body (charts inline). |
| `formats.pdf` | `boolean` | A PDF attachment. |
| `formats.csv` | `boolean` | A CSV attachment. |
| `language` | `"he" \| "en"` | — |
| `owner_id` | `string \| null` | `usr_…` ID. |
| `next_run_at` | `string \| null` | — |
| `last_run_at` | `string \| null` | — |
| `last_run` | `object \| null` | The latest run (list responses only; null on others). |
| `last_run.id` | `string` | A report run ID (prefix `rptrun_`). |
| `last_run.status` | `string` | — |
| `last_run.trigger` | `string` | — |
| `last_run.started_at` | `string` | An ISO-8601 timestamp in UTC. |
| `last_run.error` | `string \| null` | — |
| `created` | `string` | An ISO-8601 timestamp in UTC. |
| `updated` | `string` | An ISO-8601 timestamp in UTC. |

Example:

```json
{
  "cadence": {
    "day_of_month": null,
    "days": [],
    "frequency": "daily",
    "time": "08:00",
    "timezone": "Asia/Jerusalem"
  },
  "created": "2026-11-03T09:14:22.000Z",
  "enabled": true,
  "filters": {
    "agent_ids": [],
    "assistant_ids": [],
    "campaign_ids": [],
    "flow_ids": [],
    "queue_ids": [],
    "team_ids": []
  },
  "formats": {
    "csv": false,
    "email": true,
    "pdf": true
  },
  "id": "rpt_2dXk9QmZ4rTv",
  "language": "he",
  "last_run": null,
  "last_run_at": null,
  "livemode": true,
  "name": "Daily contact-centre summary",
  "next_run_at": "2026-11-04T06:00:00.000Z",
  "object": "report",
  "owner_id": null,
  "period": "yesterday",
  "recipients": [
    {
      "type": "email",
      "value": "ops@example.com"
    }
  ],
  "updated": "2026-11-03T09:14:22.000Z",
  "widgets": [
    {
      "key": "w1",
      "params": {
        "limit": null,
        "sla_sec": null
      },
      "title": null,
      "type": "kpis"
    },
    {
      "key": "w2",
      "params": {
        "limit": null,
        "sla_sec": 20
      },
      "title": null,
      "type": "queues"
    }
  ]
}
```

### 400 Bad Request

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown. Returns `ErrorEnvelope`.

### 401 Unauthorized

No valid API key was sent. Returns `ErrorEnvelope`.

### 403 Forbidden

The key may not do this (a missing scope, a plan limit, or a compliance block). Returns `ErrorEnvelope`.

### 409 Conflict

The request conflicts with the object's state, or the Idempotency-Key was reused with other parameters. Returns `ErrorEnvelope`.

### 429 Too Many Requests

Too many requests, or no call capacity right now. Retry after the Retry-After delay. Returns `ErrorEnvelope`.

### 500 Internal Server Error

Something went wrong on MoreVoice's side. Retry with the same Idempotency-Key. Returns `ErrorEnvelope`.

## Code samples

**TypeScript**

```ts
import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const report = await mv.reports.create({
	cadence: {
		frequency: "daily",
		time: "08:00",
		timezone: "Asia/Jerusalem",
	},
	formats: {
		email: true,
		pdf: true,
	},
	name: "Daily contact-centre summary",
	period: "yesterday",
	recipients: [
		{
			type: "email",
			value: "ops@example.com",
		},
	],
	widgets: [
		{
			key: "w1",
			type: "kpis",
		},
		{
			key: "w2",
			params: {
				sla_sec: 20,
			},
			type: "queues",
		},
	],
});
console.log(report);
```

**Python**

```python
from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.reports.create({
    "cadence": {
        "frequency": "daily",
        "time": "08:00",
        "timezone": "Asia/Jerusalem",
    },
    "formats": {
        "email": True,
        "pdf": True,
    },
    "name": "Daily contact-centre summary",
    "period": "yesterday",
    "recipients": [
        {
            "type": "email",
            "value": "ops@example.com",
        },
    ],
    "widgets": [
        {
            "key": "w1",
            "type": "kpis",
        },
        {
            "key": "w2",
            "params": {
                "sla_sec": 20,
            },
            "type": "queues",
        },
    ],
})
print(report)
```

**cURL**

```sh
curl -X POST https://api.morevoice.ai/v1/reports \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "cadence": {
    "frequency": "daily",
    "time": "08:00",
    "timezone": "Asia/Jerusalem"
  },
  "formats": {
    "email": true,
    "pdf": true
  },
  "name": "Daily contact-centre summary",
  "period": "yesterday",
  "recipients": [
    {
      "type": "email",
      "value": "ops@example.com"
    }
  ],
  "widgets": [
    {
      "key": "w1",
      "type": "kpis"
    },
    {
      "key": "w2",
      "params": {
        "sla_sec": 20
      },
      "type": "queues"
    }
  ]
}'
```