GuidesAPI DocsChangelogMy AppsSeismic Exchange
API Docs

Create a new task

post
https://api.seismic.com/programs/v2/spaces//tasks

Creates a new task with specified properties including title, assignee, priority, due dates, status, custom
properties, and associations. Tasks can be assigned to users, organized hierarchically with parent tasks,
associated with programs for coordinated execution, and tracked through customizable workflow statuses.

Key Features:

  • Create tasks with comprehensive properties including title, description, assignee, and due dates
  • Assign tasks to specific users for accountability
  • Set priority levels (low, medium, high) for work prioritization
  • Define parent-child task relationships for hierarchical organization
  • Associate tasks with programs, content, or requests for coordinated workflows
  • Configure custom properties for extended metadata tracking
  • Set initial workflow status using status schemas

Authorization Logic:

  1. User must have a valid JWT token with management scopes
  2. User must have role-based permissions to manage tasks
  3. Assignee must be a valid user with access to the space

Usage Example:

Create a task named "Review Marketing Materials" assigned to a team member with a high priority and a due date next week, associated with a marketing program for tracking and coordination.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
length between 7 and 22

The unique identifier of the space containing the target entity. This determines the scope of entity queries and ensures proper access control. The space must be accessible to the authenticated user with appropriate permissions. It can be the unique identifier (GUID) of the space or the word "default" to indicate the default programs space. Common values include "default" and "rkr83lapKkyCJuLLWqLqzB".

Body Params

The task creation request containing task properties including title, assignee, priority, due dates, status, custom properties, and associations.

string

Human-readable title or name for the new task that concisely describes what work needs to be accomplished. Required field that serves as the primary identifier in task lists, boards, and reports. Should be clear and actionable, typically 3-80 characters, such as 'Review Q1 Sales Report', 'Update Product Documentation', or 'Schedule Customer Demo'. Used for search, filtering, and quick task identification across the platform. The title should remain meaningful when viewed in isolation from other task details.

string | null

Detailed textual explanation of the task's objectives, requirements, deliverables, and context that helps assignees understand what needs to be done and why. Optional field (nullable) supporting multi-line plain text, typically 50-500 characters though longer descriptions are acceptable. Use to provide instructions, background information, acceptance criteria, or links to related resources. Displayed in task detail views and helps reduce ambiguity about task expectations. Can be null when the title is sufficiently self-explanatory.

string | null

Unique identifier of the user to assign this task to upon creation, in GUID format (e.g., '56d7d33f-1d42-461b-85eb-26b7b2872c88'). Optional field (nullable) that determines who is responsible for completing the task. When provided, must reference a valid user with access to the space. Set to null to create an unassigned task that can be assigned later. Assigning during creation immediately notifies the assignee and sets the assignerId field to track who made the assignment. Use to route work to specific team members at task creation time.

date-time | null

Target date and time when work on this new task is scheduled to begin, in ISO 8601 format with timezone (e.g., '2025-01-15T00:00:00Z'). Optional field (nullable) used for scheduling, resource planning, and timeline visualization. When combined with plannedEndDate, establishes the task's expected execution window. Can be null for tasks without specific start timing. Supports full date-time precision for accurate scheduling. Use to coordinate task timing with resource availability and program milestones.

date-time | null

Target completion date and time when this new task should be finished (due date), in ISO 8601 format with timezone (e.g., '2025-01-20T00:00:00Z'). Optional field (nullable) critical for deadline tracking and milestone management. Should be chronologically after plannedStartDate when both are specified. Can be null for tasks without specific deadlines. Use to establish completion expectations, enable deadline-based prioritization, support timeline tracking, and trigger due date notifications. Essential for time-sensitive deliverables.

int32 | null

Estimated effort required to complete this new task, measured in calendar days from start to finish. Optional field (nullable) represented as a positive integer using int32 format. Typical range is 1-30 days for individual tasks. When plannedStartDate and plannedEndDate are both provided, duration can be calculated automatically. Can be null when duration is unknown or not applicable. Use for workload estimation, capacity planning, resource allocation, and setting realistic completion expectations. Compare with actual duration after completion to improve future estimates.

string | null

Unique identifier of the program to associate this new task with, in base64url format (e.g., 'xH75yTE6xmz6MUvcTDxIRi'). Optional field (nullable) that establishes hierarchical relationships between tasks and programs for portfolio management and organizational structure. When provided, must reference a valid program in the same space. Can be null for standalone tasks not part of any program. Use to group related tasks under strategic initiatives, enable program-level reporting, and maintain organizational hierarchy for better visibility and coordination.

string | null
enum

Priority classification indicating the urgency and importance of this new task. Valid values are 'low' (routine work, flexible timing), 'medium' (normal priority, standard turnaround), 'high' (important work requiring expedited attention), or 'critical' (urgent work demanding immediate focus). Optional field (nullable) that affects how tasks are sorted in work queues, which notifications are triggered, and how resources are allocated. Use to guide workload prioritization, ensure critical tasks receive appropriate attention, and help assignees understand relative importance among their assigned work.

Allowed:
customProperties
array of objects | null

Array of custom field values to assign to this new task at creation time, enabling organizations to capture business-specific metadata beyond standard task fields such as cost center codes, project categories, skill requirements, or approval statuses. Optional field (nullable) where each entry references a custom property definition configured in the space and provides corresponding value(s). Empty array or null indicates no custom properties assigned. Use to enable flexible categorization, filtering, and reporting based on organization-specific taxonomy and business requirements without schema modifications.

customProperties
string | null

Unique identifier of the parent task if this new task should be created as a subtask, in base64url format. Optional field (nullable) that establishes hierarchical task relationships. When provided, must reference a valid task in the same space. The new task becomes a child of the specified parent, inheriting contextual properties and appearing nested in task hierarchies. Can be null for top-level tasks without parents. Use to create work breakdown structures, decompose complex tasks into manageable subtasks, and maintain proper task hierarchies for better organization and progress tracking.

associations
array of objects | null

Array of entity associations to link to this new task at creation time, establishing relationships with existing content, resources, or other work items within the workspace. Optional field (nullable) where each association specifies a spaceId, nodeId, and nodeType (e.g., 'content', 'task', 'request') to create explicit connections. Empty array or null indicates no initial associations. Use to attach relevant documents, link related tasks, or reference supporting materials that provide context or deliverables for completing the task. Associations can be added or modified after task creation through dedicated endpoints.

associations
Responses

Updated 6 days ago

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 6 days ago