Schedules

Schedules automate recurring test execution. Assign tests to a schedule, set a daily run time, and the system runs them on a rotating basis, most-overdue first.

Overview

A schedule ties a set of tests and test plans to a recurring cadence. You define when to run (time of day, which days of the week) and the system launches every item at that time. There is no selection or rotation logic — a schedule is a cron: what's on it runs, every time.

Schedule items

Each schedule contains a list of items. An item targets exactly one runnable entity — a test or a test plan. Every item is launched on every run.

Email digest

Schedules can be configured to send an email digest after each run. The digest summarizes the results of all agents that ran and can be set to send always or only when failures occur. Configure recipients and optionally filter by finding severity.

GET /api/v1/schedules

List schedules

Parameters

Parameter	Type	In	Required	Description
`project_id`	uuid	query	No	Restrict schedules to one project.
`limit`	integer	query	No	Maximum schedules to return.
`after`	uuid	query	No	Continue below this schedule ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/schedules" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Tenant schedules.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`schedules`	object[]
`schedules[].id`	uuid
`schedules[].tenant_id`	uuid
`schedules[].project_id`	uuid
`schedules[].name`	string
`schedules[].run_at`	string
`schedules[].run_days`	integer[]
`schedules[].enabled`	boolean
`schedules[].digest_config`	object	Delivery and severity settings for schedule digests.
`schedules[].digest_config.enabled`	boolean
`schedules[].digest_config.channels`	string[]
`schedules[].digest_config.notify_on`	string	Values: always, failures_only.
`schedules[].digest_config.recipients`	string[]
`schedules[].digest_config.min_severity`	string	Values: critical, high, medium, low.
`schedules[].last_tick_at`	date-time
`schedules[].pattern`	object	Weekly, monthly-weekday, or one-time fire pattern.
`schedules[].pattern.kind`	string	Values: weekly, monthly_weekday, once.
`schedules[].pattern.days`	integer[]
`schedules[].pattern.ordinal`	string	Values: first, second, third, fourth, last.
`schedules[].pattern.weekday`	integer
`schedules[].pattern.offset_days`	integer
`schedules[].pattern.date`	date
`schedules[].timezone`	string
`schedules[].variables`	object
`schedules[].created_at`	date-time
`schedules[].updated_at`	date-time
`next_cursor`	uuid

POST /api/v1/schedules

Create a schedule

Request Body (application/json)

Field	Type	Required	Description
`project_id`	uuid	Yes	Project ID
`name`	string	Yes	Schedule name
`run_at`	string	No	Time of day the schedule fires, formatted HH:MM in the schedule timezone. Defaults to 09:00.
`run_days`	json	No	ISO day numbers to run on (Mon=1..Sun=7). Default: all days. Example: [1,2,3,4,5] for weekdays. Compatibility alias for a weekly pattern.
`pattern`	json	No	Weekly, monthly-weekday, or one-time fire pattern.
`timezone`	string	No	IANA timezone for fire evaluation (e.g. Europe/Brussels). Empty = tenant timezone.
`variables`	json	No	Static string variables forwarded to scheduled test-plan runs, merged under the per-fire built-ins fire_date and fire_id. Applied only where the plan declares the variable. Example: {"environment": "staging"}.
`test_ids`	string[]	No	Test IDs to include
`digest_config`	json	No	Delivery and severity settings for schedule digests.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/schedules" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "project_id": "<uuid>",
    "name": "<string>"
  }'

Status Codes

Code	Description
`201`	Schedule created.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (201)

Field	Type	Description
`schedule`	object	Recurring automation configuration.
`schedule.id`	uuid
`schedule.tenant_id`	uuid
`schedule.project_id`	uuid
`schedule.name`	string
`schedule.run_at`	string
`schedule.run_days`	integer[]
`schedule.enabled`	boolean
`schedule.digest_config`	object	Delivery and severity settings for schedule digests.
`schedule.digest_config.enabled`	boolean
`schedule.digest_config.channels`	string[]
`schedule.digest_config.notify_on`	string	Values: always, failures_only.
`schedule.digest_config.recipients`	string[]
`schedule.digest_config.min_severity`	string	Values: critical, high, medium, low.
`schedule.last_tick_at`	date-time
`schedule.pattern`	object	Weekly, monthly-weekday, or one-time fire pattern.
`schedule.pattern.kind`	string	Values: weekly, monthly_weekday, once.
`schedule.pattern.days`	integer[]
`schedule.pattern.ordinal`	string	Values: first, second, third, fourth, last.
`schedule.pattern.weekday`	integer
`schedule.pattern.offset_days`	integer
`schedule.pattern.date`	date
`schedule.timezone`	string
`schedule.variables`	object
`schedule.created_at`	date-time
`schedule.updated_at`	date-time
`items`	object[]
`items[].id`	uuid
`items[].schedule_id`	uuid
`items[].test_id`	uuid
`items[].test_plan_id`	uuid
`items[].created_at`	date-time

GET /api/v1/schedules/{id}

Get a schedule

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/schedules/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Schedule with items and recent runs.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`name`	string
`run_at`	string
`run_days`	integer[]
`enabled`	boolean
`digest_config`	object	Delivery and severity settings for schedule digests.
`digest_config.enabled`	boolean
`digest_config.channels`	string[]
`digest_config.notify_on`	string	Values: always, failures_only.
`digest_config.recipients`	string[]
`digest_config.min_severity`	string	Values: critical, high, medium, low.
`last_tick_at`	date-time
`pattern`	object	Weekly, monthly-weekday, or one-time fire pattern.
`pattern.kind`	string	Values: weekly, monthly_weekday, once.
`pattern.days`	integer[]
`pattern.ordinal`	string	Values: first, second, third, fourth, last.
`pattern.weekday`	integer
`pattern.offset_days`	integer
`pattern.date`	date
`timezone`	string
`variables`	object
`created_at`	date-time
`updated_at`	date-time
`items`	object[]
`items[].id`	uuid
`items[].schedule_id`	uuid
`items[].test_id`	uuid
`items[].test_plan_id`	uuid
`items[].created_at`	date-time
`runs`	object[]
`runs[].agent_id`	uuid
`runs[].test_id`	uuid
`runs[].plan_run_id`	uuid
`runs[].triggered_at`	date-time
`runs[].status`	string

DELETE /api/v1/schedules/{id}

Delete a schedule

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/schedules/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Schedule deleted.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

PATCH /api/v1/schedules/{id}

Update a schedule

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Request Body (application/json)

Field	Type	Required	Description
`name`	string	No	New name
`run_at`	string	No	Time of day the schedule fires, formatted HH:MM in the schedule timezone.
`run_days`	json	No	ISO day numbers (Mon=1..Sun=7). Compatibility alias for a weekly pattern.
`enabled`	boolean	No	Enable or disable
`pattern`	json	No	Weekly, monthly-weekday, or one-time fire pattern.
`timezone`	string	No	IANA timezone for fire evaluation. Empty string reverts to the tenant timezone.
`variables`	json	No	Static variables for scheduled test-plan runs. Empty object clears them.
`digest_config`	json	No	Email digest settings (see Create for shape). Set to null to disable.

Example Request

curl

curl -X PATCH "http://app.aiqaramba.com/api/v1/schedules/<id>" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "<string>",
    "run_at": "<string>",
    "run_days": {},
    "enabled": true,
    "pattern": {},
    "timezone": "<string>",
    "variables": {},
    "digest_config": {}
  }'

Status Codes

Code	Description
`200`	Updated schedule.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`name`	string
`run_at`	string
`run_days`	integer[]
`enabled`	boolean
`digest_config`	object	Delivery and severity settings for schedule digests.
`digest_config.enabled`	boolean
`digest_config.channels`	string[]
`digest_config.notify_on`	string	Values: always, failures_only.
`digest_config.recipients`	string[]
`digest_config.min_severity`	string	Values: critical, high, medium, low.
`last_tick_at`	date-time
`pattern`	object	Weekly, monthly-weekday, or one-time fire pattern.
`pattern.kind`	string	Values: weekly, monthly_weekday, once.
`pattern.days`	integer[]
`pattern.ordinal`	string	Values: first, second, third, fourth, last.
`pattern.weekday`	integer
`pattern.offset_days`	integer
`pattern.date`	date
`timezone`	string
`variables`	object
`created_at`	date-time
`updated_at`	date-time

GET /api/v1/schedules/{id}/digest

Preview a schedule digest

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/schedules/<id>/digest" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Structured digest preview.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`schedule_id`	uuid
`schedule_name`	string
`project_id`	uuid
`project_name`	string
`agent_ids`	uuid[]
`digest`	object
`reason`	string

POST /api/v1/schedules/{id}/digest

Send a schedule digest now

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/schedules/<id>/digest" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Digest queued.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`queued`	boolean
`agent_ids`	uuid[]

POST /api/v1/schedules/{id}/items

Add a schedule target

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Request Body (application/json)

Field	Type	Required	Description
`test_id`	uuid	No	Test to add. Mutually exclusive with test_plan_id.
`test_plan_id`	uuid	No	Test plan to add. Mutually exclusive with test_id.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/schedules/<id>/items" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "test_id": "<uuid>",
    "test_plan_id": "<uuid>"
  }'

Status Codes

Code	Description
`201`	Target added.
`400`	The request is malformed or failed validation.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (201)

Field	Type	Description
`id`	uuid
`schedule_id`	uuid
`test_id`	uuid
`test_plan_id`	uuid
`created_at`	date-time

DELETE /api/v1/schedules/{id}/items/{itemId}

Remove a schedule target

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.
`itemId`	uuid	path	Yes	Schedule item ID.

Example Request

curl

curl -X DELETE "http://app.aiqaramba.com/api/v1/schedules/<id>/items/<itemId>" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`204`	Target removed.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

GET /api/v1/schedules/{id}/next-fires

Preview schedule fire times

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.
`n`	integer	query	No	Number of future fires.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/schedules/<id>/next-fires" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Upcoming fire moments.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`schedule_id`	uuid
`timezone`	string
`description`	string
`next_fires`	date-time[]

GET /api/v1/schedules/{id}/runs

List schedule runs

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.
`limit`	integer	query	No	Maximum runs to return.

Example Request

curl

curl "http://app.aiqaramba.com/api/v1/schedules/<id>/runs" \
  -H "Authorization: Bearer $AIQA_API_KEY"

Status Codes

Code	Description
`200`	Recent schedule-launched agents.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`runs`	object[]
`runs[].agent_id`	uuid
`runs[].test_id`	uuid
`runs[].plan_run_id`	uuid
`runs[].triggered_at`	date-time
`runs[].status`	string

POST /api/v1/schedules/{id}/trigger

Trigger a schedule now

Parameters

Parameter	Type	In	Required	Description
`id`	uuid	path	Yes	Schedule ID.

Request Body (application/json)

Field	Type	Required	Description
`variables`	json	No	Extra per-fire variables for this trigger only, overriding schedule variables and built-ins. Example: {"run_tag": "release-42"}.

Example Request

curl

curl -X POST "http://app.aiqaramba.com/api/v1/schedules/<id>/trigger" \
  -H "Authorization: Bearer $AIQA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": {}
  }'

Status Codes

Code	Description
`200`	Trigger result.
`401`	Authentication is missing or invalid.
`404`	The requested resource does not exist.
`500`	The server could not complete the request.

Response Fields (200)

Field	Type	Description
`id`	uuid
`tenant_id`	uuid
`project_id`	uuid
`name`	string
`run_at`	string
`run_days`	integer[]
`enabled`	boolean
`digest_config`	object	Delivery and severity settings for schedule digests.
`digest_config.enabled`	boolean
`digest_config.channels`	string[]
`digest_config.notify_on`	string	Values: always, failures_only.
`digest_config.recipients`	string[]
`digest_config.min_severity`	string	Values: critical, high, medium, low.
`last_tick_at`	date-time
`pattern`	object	Weekly, monthly-weekday, or one-time fire pattern.
`pattern.kind`	string	Values: weekly, monthly_weekday, once.
`pattern.days`	integer[]
`pattern.ordinal`	string	Values: first, second, third, fourth, last.
`pattern.weekday`	integer
`pattern.offset_days`	integer
`pattern.date`	date
`timezone`	string
`variables`	object
`created_at`	date-time
`updated_at`	date-time
`launched`	integer
`failed`	integer