Task REST API

Published: 2024-05-15

Last Updated: 2026-08-26

Retrieve a task or subtask, or create or update a task or subtask in MDCMS.

JSON payloads

All MDCMS REST API request and response bodies use JSON. Send Content-Type: application/json on POST.

GET

Return information about a specific task or subtask.

GET /task

Authorization

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for the MDSEC user. See Authenticate requests to the MDCMS REST API server.

A missing or invalid token returns HTTP 401 Unauthorized.

Query parameters

Parameter	Type	Required	Description
`proj`	string	Yes	Project ID.
`task`	integer	Yes	Task number within the project.
`stsk`	integer	Yes	Subtask within the task. Pass `0` to retrieve information for the task itself.

Example

Replace {endpoint} with the URL endpoint defined for the MDCMS HTTP server.

cURLHTTP

curl -H "Authorization: Bearer {token}" \
  "https://{endpoint}/task?proj=MDSD&task=141&stsk=0"

GET /task?proj=MDSD&task=141&stsk=0 HTTP/1.1
Host: {endpoint}
Authorization: Bearer {token}

Response body

Schema

Property	Type	Description
`proj`	string	Project ID.
`task`	integer	Task number.
`stsk`	integer	Subtask number. `0` when the record is the task itself.
`tskt`	string	Task type.
`sum`	string	Brief description of the task.
`agp`	string	Application code applied to the task.
`iref`	string	Internal reference code.
`pri`	integer	Priority. See Priority.
`sts`	string	Task status.
`dued`	integer	Date when the task or subtask is expected to be completed. Format `YYYYMMDD`.
`duet`	integer	Time when the task or subtask is expected to be completed. Format `HHMMSS`.
`agrp`	string	User group assigned to the task.
`ausr`	string	User assigned to the task.
`tstg`	string	User group responsible for testing the results of the task.
`tstu`	string	User responsible for testing the results of the task.
`requester`	string	User who requested the task.
`requestDate`	string	Request date. Format `YYYYMMDD`.
`requestTime`	string	Request time. Format `HHMMSS`.
`closer`	string	User who closed the task.
`closeDate`	string	Close date. Format `YYYYMMDD`.
`closeTime`	string	Close time. Format `HHMMSS`.
`hrse`	decimal	Hours expected to complete the task.
`cste`	decimal	Expected cost to complete the task.
`hrsa`	decimal	Actual hours.
`csta`	decimal	Actual cost.

Example

{
  "proj": "MDSD",
  "task": "141",
  "stsk": "0",
  "tskt": "SD_ENHANCE",
  "sum": "Default Project and Task Types",
  "agp": "",
  "iref": "",
  "pri": "3",
  "sts": "7",
  "dued": "0",
  "duet": "0",
  "agrp": "",
  "ausr": "MMORGAN",
  "tstg": "",
  "tstu": "",
  "requester": "JIRA",
  "requestDate": "20190211",
  "requestTime": "191136",
  "closer": "JIRA",
  "closeDate": "20190416",
  "closeTime": "121142",
  "hrse": ".00",
  "cste": ".00",
  "hrsa": ".00",
  "csta": ".00"
}

POST

Create or update a task or subtask in MDCMS.

For an update, include a property in the body only when a new value should be set. Omitted properties keep their existing values.

POST /task

Authorization

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token for the MDSEC user. See Authenticate requests to the MDCMS REST API server.
`Content-Type`	string	Yes	`application/json`

A missing or invalid token returns HTTP 401 Unauthorized.

Request body

Schema

Property	Type	Required	Description
`proj`	string	Yes	ID of an existing, open project.
`task`	integer	No	Existing task number, or `0` if the information is for a new task. MDCMS automatically generates the number for a new task.
`stsk`	integer	No	Existing subtask number. Combined with `nsts`, this controls whether the API processes the task, an existing subtask, or a new subtask. See New subtask.
`nsts`	string	No	Whether values should be saved to a new subtask, and how `iref` is used. See New subtask.
`tskt`	string	No	Valid task type. If omitted for a new task, the default type is used.
`sum`	string	Yes, when new	Brief description of the task.
`agp`	string	No	Optional application code to apply to the task.
`iref`	string	No	Optional internal reference code for the task.
`pri`	integer	No	Priority. If omitted for a new task, the priority is set to `3` (Medium). See Priority.
`sts`	string	No	Task status. If omitted for a new task, the status is set to `1` (Open).
`dued`	integer	No	Date when the task or subtask is expected to be completed. Format `YYYYMMDD`.
`duet`	integer	No	Time when the task or subtask is expected to be completed. Format `HHMMSS`.
`agrp`	string	No	User group to assign the task to.
`ausr`	string	No	Specific user to assign the task to.
`tstg`	string	No	User group responsible for testing the results of the task.
`tstu`	string	No	Specific user responsible for testing the results of the task.
`hrse`	decimal	No	Hours expected to complete the task.
`cste`	decimal	No	Expected cost to complete the task.
`musr`	string	No	User to register as the creator or modifier of the task.
`edsc`	string	No	Extended description of the task.

New subtask

Use nsts with task, stsk, and iref to control create versus update.

Value	Description
`*NO`	If `task` is `0`, create a new task. If `task` is greater than `0` and `stsk` is `0`, update the existing task. If `task` is greater than `0` and `stsk` is greater than `0`, update the existing subtask.
`*YES`	If `task` is `0`, create a new task. If `task` is greater than `0`, create a new subtask for the task.
`*REF`	If `iref` is found in the database for the given project, update the referenced task or subtask. If `task` is `0` and `iref` is not found, create a new task. If `task` is greater than `0` and `iref` is not found, create a new subtask for the task.
`*NOREF`	If `iref` is found in the database for the given project, update the referenced task or subtask. If `iref` is not found, nothing occurs.

Example

Update an existing subtask. Replace {endpoint} with the URL endpoint defined for the MDCMS HTTP server.

JSONcURLHTTP

{
  "proj": "demopro",
  "task": "1",
  "stsk": "1",
  "tskt": "admin",
  "sum": "a subtask created directly from the rest api",
  "nsts": "*no",
  "agp": "TEST",
  "agrp": "pgmr 1",
  "pri": "2",
  "sts": "3",
  "musr": "mmorgan",
  "dued": "20190415",
  "duet": "110000"
}

curl -X POST "https://{endpoint}/task" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"proj":"demopro","task":"1","stsk":"1","tskt":"admin","sum":"a subtask created directly from the rest api","nsts":"*no","agp":"TEST","agrp":"pgmr 1","pri":"2","sts":"3","musr":"mmorgan","dued":"20190415","duet":"110000"}'

POST /task HTTP/1.1
Host: {endpoint}
Authorization: Bearer {token}
Content-Type: application/json

{
  "proj": "demopro",
  "task": "1",
  "stsk": "1",
  "tskt": "admin",
  "sum": "a subtask created directly from the rest api",
  "nsts": "*no",
  "agp": "TEST",
  "agrp": "pgmr 1",
  "pri": "2",
  "sts": "3",
  "musr": "mmorgan",
  "dued": "20190415",
  "duet": "110000"
}

Response body

The response provides a rtn object.

Schema

Property	Type	Description
`rtn`	object	Result object. See Result object.

Result object

Property	Type	Description
`sev`	string	Result severity. See Severity.
`msg`	string	Message text.

Example

{
  "rtn": {
    "sev": "10",
    "msg": "Subtask DEMOPRO 1.1 updated"
  }
}

Priority

Value	Meaning
`1`	Critical
`2`	High
`3`	Medium
`4`	Low
`5`	Optional

Severity

Value	Meaning
`10`	Processed without errors or warnings
`20`	Processed, but warnings occurred
`30`	Did not process successfully due to errors

Resource	Description
Project REST API	Create, update, or retrieve a project
Open Tasks REST API	List active tasks for a project
Open Subtasks REST API	List active subtasks for a project and task

Task REST API

GET

Authorization

Query parameters

Example

Response body

Schema

Example

POST

Authorization

Request body

Schema

New subtask

Example

Response body

Schema

Result object

Example

Priority

Severity

Related resources