Screendragon API Integration Use Cases - Tasks

Modified on Tue, 30 Sep at 11:56 AM

Fetch Tasks List
Retrieve Tasks for a Project
Create a new Task
Update a Task
Update Task Status
Delete a Task

Fetch Tasks List

Endpoint

GET /api/tasks

Description

This endpoint retrieves a list of tasks based on various filters such as assignment details, age, project metadata, and assignment filters. This endpoint is designed to support task listing with optional inclusion of workflow tasks and metadata.

Request Parameters

Name	Type	Required	Description
`id`	`Int32`	❌	The ID of the parent task or project. If 0, retrieves top-level tasks.
`showAssignedDetails`	`Boolean`	❌	Indicates whether to include assignment details in the response.
`age`	`Int32`	❌	Filters tasks by age (e.g., days since creation or update).
`assignedFilterType`	`String`	❌	Type of assignment filter (e.g., user, team, role).
`assignedFilterValue`	`String`	❌	Value for the assignment filter (e.g., user ID, team name).
`projectMetaFields`	`String`	❌	Comma-separated list of project metadata fields to include.

Error Handling

Status Code	Message
400	"Invalid filter type specified."
404	"Task not found."
500	"Internal server error."

Notes

This endpoint is intended to support flexible task listing with optional metadata and assignment filtering.
Ensure that the user has appropriate permissions to view the requested tasks.

Sample Request

GET /api/tasks?id=123&showAssignedDetails=true&age=7&assignedFilterType=user
      &assignedFilterValue=456&projectMetaFields=status,priority
Authorization: Bearer <token>

Sample Response (Success)

HTTP/1.1 200 OK
[
  {
    "taskId": 101,
    "title": "Design Review",
    "assignedTo": {
      "userId": 456,
      "name": "Joshua Handley"
    },
    "age": 7,
    "status": "In Progress",
    "priority": "High",
    "projectMeta": {
      "status": "Active",
      "priority": "High"
    }
  },
  ...
]

Sample Response (Error)

HTTP/1.1 400 Bad Request
{
  "error": "Invalid filter type specified."
}

Retrieve Tasks for a Project

Endpoint

GET /api/tasks/{id}

Description

This endpoint retrieves detailed information for a specific task by its ID. This endpoint returns a list of task objects, typically containing metadata and assignment details. It is a simplified wrapper around the GetTaskDetails method with default parameters

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the task.

Error Handling

Status Code	Message
400	"No Data."
500	"Internal Server Error."

Notes

The endpoint automatically includes access level, sub-projects, and layout information without requiring additional query parameters.
Ensure the bearer token is valid and has permission to view the specified project.

Sample Request

GET /api/tasks/101
Authorization: Bearer <token>

Sample Response (Success)

HTTP/1.1 200 OK
[
  {
    "taskId": 101,
    "title": "Design Review",
    "assignedTo": {
      "userId": 456,
      "name": "Joshua Handley"
    },
    "status": "In Progress",
    "priority": "High",
    "createdDate": "2025-09-01T10:00:00Z",
    "dueDate": "2025-09-30T17:00:00Z"
  }
]

Sample Response (Error)

HTTP/1.1 400 Bad Request
{
  "error": "No data"
}

Create a new Task

Endpoint

POST /api/tasks/{projectid}

Description

This endpoint adds a new task to the specified project. Optionally associates the task with a specific phase. Requires task details to be provided in the request body.

Path Parameters

Name	Type	Required	Description
`projectid`	`Int32`	✅	Unique identifier of the project.

Query Parameters

Name	Type	Required	Description
`phase`	`Int32`	❌	Optional phase ID to associate the task with. Defaults to 0.

Body Parameters

Name	Type	Required	Description
`details`	`Object`	✅	Object containing task details. Must include all required task fields.

Error Handling

Status Code	Message
400	"Invalid task details provided."
400	"Project with ID {projectid} not found."
400	"Phase ID {phase} is not valid."

Notes

The user must have permission to add tasks to the specified project.
The TaskObject must include all mandatory fields such as title, assigned user, and due date.
If phase is provided, it must correspond to a valid phase within the project.
The endpoint uses internal user context for authorization and auditing.
If the project or phase is invalid, or the task cannot be created, a descriptive error message is returned.

Sample Request

POST /api/tasks/456?phase=3
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Finalize UI mockups",
  "description": "Complete the design for the dashboard module",
  "assignedTo": "user123",
  "dueDate": "2025-10-15T00:00:00Z",
  "priority": "High"
}

Sample Response (Success)

{
  "taskId": 789,
  "message": "Task successfully added to project."
}

Sample Response (Error)

{
  "error": "Project with ID 456 not found."
}

Update a Task

Endpoint

PUT /api/tasks/{id}

Description

This endpoint updates an existing task with new details. Requires permission checks based on user credentials and group access. Supports updating task metadata such as name, description, dates, and status.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the task to update.

Body Parameters

Name	Type	Required	Description
`details`	`Object`	✅	Object containing updated task fields. Must include name, description, start and end dates, and status.

Error Handling

Status Code	Message
403	"User does not have permission to update this task."
400	"An error occurred while updating the task."

Notes

The user must have at least write-level access to the task via direct or group permissions.
Required fields in TaskObject include name, description, startDate, endDate, and status.
If the user lacks permission or an error occurs during update, a descriptive error message is returned.

Sample Request

PUT /api/tasks/789
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Update wireframes",
  "description": "Revise wireframes based on client feedback",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-10T00:00:00Z",
  "status": "In Progress"
}

Sample Response (Error)

{
  "error": "User does not have permission to update this task."
}

Update Task Status

Endpoint

PUT /api/tasks/status/{id}

Description

This endpoint updates the status of a specific task. Requires the user to have appropriate access rights to the task, either through direct assignment or group membership.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the task.

Query Parameters

Name	Type	Required	Description
`status`	`String`	✅	New status value to apply.

Error Handling

Status Code	Message
400	"No data."

Notes

The user must be assigned to the task or belong to a group with access rights to update it.
Only the status field is updated; other task fields remain unchanged.
If the user lacks permission or an error occurs, a generic error message is returned.
Admin users bypass group-based access checks.

Sample Request

PUT /api/task/status/789?status=Completed
Authorization: Bearer {token}

Sample Response (Error)

{
  "error": "No data"
}

Delete a Task

Endpoint

DELETE /api/tasks/{id}

Description

This endpoint marks a task as deleted and removes all associated task links. The deletion is soft (logical), preserving the task record with a deleted flag. Requires user credentials and access validation.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the task to delete.

Error Handling

Status Code	Message
400	"Task could not be deleted due to an internal error."

Notes

The task is not physically removed; it is flagged as deleted and timestamped.
All task links (source or target) are permanently removed.
If the task does not exist or an error occurs, a descriptive error message is returned.
The deletion also triggers cleanup of associated resource items

Sample Request

DELETE /api/task/789
Authorization: Bearer {token}

Sample Response (Error)

{
  "error": "Task could not be deleted due to an internal error."
}