Create Period (Appium2)

13 min

This endpoint creates or updates the period configuration of a test plan.

If the plan does not have a period, a new period is created and assigned to the plan. If the plan already has a period, the existing period is updated.

Endpoint Information

URL: {gateway-url}/plan-periods/plan/{planId}

Method: POST

Authentication: Required (Bearer Token)

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token used for authentication. Example: Bearer <your_access_token>
Content-Type	Yes	Must be application/json.
X-Company-Id	Yes	The company ID used by the gateway to authorize and route the request.

Path Variables

Parameter	Type	Required	Description
planId	Long	Yes	The ID of the test plan. Must be a positive number.

Request Body - Manual

{
  "periodType": "MANUAL",
  "startDate": null,
  "endDate": null,
  "onceDate": null,
  "daysOfWeek": null,
  "repeatPeriod": null,
  "scheduled": false
}

Request Body - Once

{
  "periodType": "ONCE",
  "startDate": null,
  "endDate": null,
  "onceDate": "2026-09-10T09:30:00Z",
  "daysOfWeek": null,
  "repeatPeriod": null,
  "scheduled": false
}

Request Body - Repetitive

{
  "periodType": "REPETITIVE",
  "startDate": "2026-09-01T00:00:00Z",
  "endDate": "2026-10-01T00:00:00Z",
  "onceDate": null,
  "daysOfWeek": "1,2,3,4,5",
  "repeatPeriod": 60,
  "scheduled": false
}

Request Body Parameters

Field	Type	Required	Description
periodType	String	Yes	Period type. Supported values: MANUAL, ONCE, REPETITIVE.
startDate	DateTime	No	Start date of the repetitive schedule. Use ISO-8601 format.
endDate	DateTime	No	End date of the repetitive schedule. Use ISO-8601 format.
onceDate	DateTime	No	Execution date for ONCE period type. Use ISO-8601 format.
daysOfWeek	String	No	Comma-separated day values used for repetitive schedules.
repeatPeriod	Integer	No	Repeat interval value used for repetitive schedules.
scheduled	Boolean	No	Internal scheduling flag used by the backend while creating or updating scheduler records.

Response Body

{
  "data": {
    "id": 631,
    "periodType": "MANUAL",
    "startDate": null,
    "endDate": null,
    "onceDate": null,
    "daysOfWeek": null,
    "repeatPeriod": null
  }
}

Response Fields

Field	Type	Description
data	Object	Created or updated period payload.
data.id	Long	Unique identifier of the period.
data.periodType	String	Period type. Possible values: MANUAL, ONCE, REPETITIVE.
data.startDate	DateTime	Start date of the repetitive schedule.
data.endDate	DateTime	End date of the repetitive schedule.
data.onceDate	DateTime	Execution date for one-time schedules.
data.daysOfWeek	String	Comma-separated day values used for repetitive schedules.
data.repeatPeriod	Integer	Repeat interval value.

Error Response Format

{
  "instance": "/plan-periods/plan/999999",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.testinium.com/exception",
  "timestamp": "2026-08-18T12:08:41.165927056Z",
  "errorType": "EXCEPTION",
  "errors": {
    "code": 10003,
    "message": "Plan with id 999999 not found!"
  }
}

HTTP Error Codes

HTTP Code	Error Message	Description
400	Bad Request	Request body is invalid, malformed, or contains an invalid enum/date value.
401	Unauthorized	Authentication is missing or invalid.
403	Forbidden	User does not have permission for this operation or company.
404	Not Found	Plan was not found, deleted, disabled, or not accessible within the current company scope.
405	Method Not Allowed	The endpoint was called with an unsupported HTTP method.
500	Internal Server Error	An unexpected error occurred on the server side.
503	Service Unavailable	Project service or scheduler service is unavailable.

Application Error Codes

Code	HTTP Status	Source	Description
10003	404	Project	Test plan not found.
10001	401	Gateway	Authentication is required.
10002	401	Gateway	Token is invalid or cannot be verified.
10003	403	Gateway	Authorization failed for the requested resource.
10004	400	Gateway	A required header, such as X-Company-Id, is missing or invalid.
10008	503	Gateway	Routed service is unavailable.
10007	503	Common	Downstream service is unavailable.
20005	400	Common Validation	Request body or path variable validation failed.
20007	400	Common Validation	Invalid enum value.
20008	400	Common Validation	Path variable type is invalid.
20009	405	Common Validation	HTTP method is not supported.

Example Request

curl --location '{gateway-url}/plan-periods/plan/{planId}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Company-Id: <company_id>' \
  --data '{
    "periodType": "MANUAL",
    "startDate": null,
    "endDate": null,
    "onceDate": null,
    "daysOfWeek": null,
    "repeatPeriod": null,
    "scheduled": false
  }'