Skip to main content
POST
/
v1
/
schedules
curl --request POST \
  --url https://{instance}.omniapp.co/api/v1/schedules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identifier": "12db1a0a",
  "name": "My Webhook schedule",
  "schedule": "0 9 ? * * *",
  "timezone": "UTC",
  "format": "json",
  "destinationType": "webhook",
  "url": "https://webhooksrus.com/1234566"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "message": "Successfully created schedule"
}

Authorizations

​
Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

​
userId
string<uuid>

Only supported when using an Organization API key. The membership ID of the user who should own the schedule. Note: This value is the membership ID, not the user ID. Use the List users endpoint to retrieve membership IDs.

When using an Organization API key:

  • If userId is provided, the schedule is owned by the specified user
  • If userId is not provided, the schedule is owned by the organization

Attempting to use a Personal Access Token (PAT) with this parameter will result in a 403 Forbidden error. When using a PAT, the schedule owner will be the creator of the PAT.

Body

application/json
​
identifier
string
required

The ID of the dashboard where the task will be created. This can be retrieved by:

  • Opening the dashboard settings - Navigate to File > Document settings in the dashboard and then click Settings. The Identifier field contains the dashboard ID.
  • Using the dashboard's URL - The string after /dashboards is the dashboard's ID; for example: https://myorg.omniapp.co/dashboards/12db1a0a
​
name
string
required

The name of the task.

​
schedule
string
required

A cron expression defining when the schedule will run, in Amazon Web Services (AWS) Cloudwatch syntax.

​
timezone
string
required

The IANA timezone where the task should run, such as Asia/Dubai. Refer to the TZ column in this IANA.org timezone description file for a list of accepted values.

​
format
enum<string>
required

The output format of the schedule.

Available options:
csv,
link_only,
json,
pdf,
png,
xlsx
​
destinationType
enum<string>
required

The destination where the task's output should be delivered.

Note: If using slack, you must connect a Slack workspace to Omni first.

Available options:
webhook,
email,
sftp,
slack
​
filterConfig
object

An object specifying the filter conditions to apply to the task. The filter key specified must already exist in the dashboard. If the dashboard doesn't have any filters configured, filters can't be used in the task.

Use the Get dashboard filters and controls endpoint to retrieve filter configuration objects.

Note: Filter keys are case-sensitive and must match exactly.

​
conditionType
enum<string>

Required if conditionQueryMapKey is provided. Defines the type of condition to use for alerts.

Available options:
RESULTS_PRESENT,
RESULTS_CHANGED,
RESULTS_MISSING,
RESULTS_UNCHANGED
​
conditionQueryMapKey
string

Required if conditionType is provided. The ID of the query to monitor for triggering an alert. Must reference a valid query in the dashboard.

​
queryIdentifierMapKey
string

The ID of the query to include in a single tile task. Must reference a valid query in the dashboard.

Required for:

  • format: json with enableFormatting: true
  • format: xlsx with overrideRowLimit: true
​
killJobsOnFailure
boolean
default:false

If true, stop the entire job if any queries included in the task fail.

​
testNow
boolean
default:false

If true, run the task immediately instead of scheduling.

Not supported for RESULTS_CHANGED alert conditions.

​
hideTitle
boolean
default:false

Compatible with pdf and png formats. If true, the content's title will be hidden in the task's output.

​
hideHiddenFields
boolean
default:false

Compatible with csv and xlsx formats. If true, fields marked as hidden won't be displayed in the task's output.

​
enableFormatting
boolean
default:false

Compatible with csv and json formats. If true, formatting will be enabled in the task's output.

If true for json format, queryIdentifierMapKey is required.

​
overrideRowLimit
boolean
default:false

Compatible with csv, json, and xlsx formats. If true, the default row limit will be overridden.

If true for json and xlsx formats, a queryIdentifierMapKey is required.

​
maxRowLimit
integer

Compatible with csv, json, and xlsx formats. Used with overrideRowLimit. Specifies the maximum number of rows.

​
showContentLink
boolean
default:true

Compatible with all formats except link_only. If true, a link to the content will be shown in the task's output.

​
showFilters
boolean
default:true

Compatible with all formats except link_only and csv. If true, filters will be shown in the task's output.

​
expandTablesToShowAllRows
boolean
default:false

Compatible with pdf and png formats. If true, up to 1,000 rows in table visualizations will be included in the delivery.

This parameter cannot be used when paperFormat: fit_page.

​
paperFormat
enum<string>

Compatible with pdf format. Defines the paper format (size) of the resulting PDF.

The fit_page option cannot be used if expandTablesToShowAllRows: true.

Available options:
a3,
a4,
letter,
legal,
fit_page,
tabloid
​
paperOrientation
enum<string>

Compatible with pdf format. Defines the paper orientation of the resulting PDF.

Available options:
portrait,
landscape
​
singleColumnLayout
boolean
default:false

Compatible with pdf and png formats. If true, dashboard tiles will be arranged into a single vertical column.

​
url
string

Required if destinationType: webhook. A webhook URL. Must be a valid HTTP/HTTPS URL.

​
recipients

Required if destinationType: email or destinationType: slack.

For email destinations: An array of strings, each specifying a valid email address.

For Slack destinations: Channel or user IDs. Accepts either a string or array format:

  • Channels can be a single channel ID ("C01234567") or an array with exactly one channel ID (["C01234567"]). Additionally:
    • For private channels, invite the Omni Slackbot to the channel first
    • Only one Slack channel is supported per schedule. Multiple channels will return a 400 error.
  • Users can be a string of comma-separated user IDs ("U111,U222") or an array of user IDs (["U111", "U222"])
​
subject
string

Required if destinationType: email. Email subject line.

​
textBody
string

Applicable to email and Slack destinations. Custom message text included with the delivery.

​
slackRecipientType
enum<string>

Required if destinationType: slack. Specifies whether recipients are a channel or individual users.

  • channel: Deliver to a Slack channel. If the channel is private, you'll also need to invite the Omni Slackbot to the channel.
  • users: Deliver to individual Slack users
Available options:
channel,
users
​
fanOut
boolean
default:false

Applicable to email destinations. If true, send individual emails to each recipient.

​
address
string

Required if destinationType: sftp. SFTP server address.

​
port
integer

Required if destinationType: sftp. SFTP port.

​
username
string

Required if destinationType: sftp. SFTP username.

​
path
string

Required if destinationType: sftp. Remote file path.

​
passwordUnencrypted
string

Applicable to SFTP destinations. SFTP password.

Response

Schedule created successfully

​
id
string<uuid>

The ID of the created schedule.

​
message
string

A success message.

Example:

"Successfully created schedule"