Tasks

A task in smenso is a defined unit of work that contributes toward achieving project objectives. Tasks can be assigned to individuals or teams and may be organized into folders, phases, or hierarchical structures using subtasks.

Tasks contain attributes such as:

• title and description,
• status and priority,
• start and due dates,
• estimated and actual effort,
• attachments, comments, and dependencies.

Tasks can represent anything from simple checklist items to complex work packages with detailed execution steps. They belong to a specific project and can carry both standard fields and custom metadata via flavors.

Tasks are flexible and support a wide range of project management scenarios, enabling teams to structure, assign, and track their work consistently across smenso.

Prerequisites (Getting Started)

This guide assumes you're familiar with:

• Authentication: https://developers.smenso.de/docs/authentication
• Integration tickets (async processing & polling): https://developers.smenso.de/docs/integration-tickets-async-processing-polling
• Dates & time zones: https://developers.smenso.de/docs/dates-time-zones
• Permissions & privacy: https://developers.smenso.de/docs/permissions-privacy

Available Endpoints

Integration JSON API (read & write)

📘

Create and update requests are processed asynchronously. The response contains a status ticket id that you poll via GET /api/integration/status/json/{ticketId}. The only exception is Create task from a template, which returns the new task ID directly.

Comments and attachments of a task have their own endpoints. See the Attachments guide.

IDs & Correlation

Common identifiers you'll encounter:

• id / taskId: internal task GUID used by endpoints like Update or Delete.
• projectId: GUID of the project the tasks belong to.
• externalId: optional identifier to correlate tasks with external systems. Set useExternalId: true on update requests to identify tasks by it.
• tempId: a value you choose and send in the request body. The status ticket returns it together with the ID of the created task (createdIds), so you can match input rows to results.
• parentId: ID of the parent task. Setting it creates the task as a subtask.

Key Fields (commonly used)

For the full schema, see the API reference of each endpoint. Frequently used fields include:

Create Tasks (Bulk)

POST /api/integration/task/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "timezoneId": "W. Europe Standard Time",
  "projectId": "4f9c2b2e-1234-5678-9abc-0a1b2c3d4e5f",
  "task": [
    {
      "tempId": 1,
      "title": "Prepare launch checklist",
      "appointedPersons": "<member id>"
    },
    {
      "tempId": 2,
      "title": "Review checklist",
      "parentId": "<id of an existing parent task>"
    }
  ]
}

The response contains a status ticket ID:

{
  "id": "e0c5a2c8-3f7a-4c0e-9b7d-5a1f6e2b9c10",
  "received": "2026-11-02T09:00:00Z"
}

Poll the ticket to get the result. For created tasks, the ticket contains the mapping from your tempId to the new task ID:

{
  "createdIds": {
    "1": "a1b2c3d4-0000-1111-2222-333344445555"
  }
}

📘

Nested subtasks: parentId expects the ID of an existing task. To create several levels, create the levels one after another, because the ID of a new task is only available in the status ticket.

📘

If the request contains invalid JSON content, the API can respond with HTTP 400 and the same body as above. The error details are then available in the status ticket (messages).

Update Tasks (Bulk)

Only the fields you include are changed. All other fields stay as they are. This makes it safe to send a minimal payload, for example to change only the workflow status:

PUT /api/integration/task/json
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "projectId": "4f9c2b2e-1234-5678-9abc-0a1b2c3d4e5f",
  "task": [
    {
      "id": "a1b2c3d4-0000-1111-2222-333344445555",
      "workflowStatusId": "<workflow status id>"
    }
  ]
}

Use description for the task description. The following HTML elements are kept: <p>, <br>, <strong>, <ul>, <li>. Images (<img>) are removed. To add a file to a task, use the attachment endpoints.

To set custom fields, pass an array of flavor values:

{
  "id": "a1b2c3d4-0000-1111-2222-333344445555",
  "flavor": [
    { "target": "<flavor name or id>", "value": "<value>" }
  ]
}

📘

Update by externalId: set useExternalId to true and put the external ID into id.

Create a Task from a Template

Creates a task based on a task template and returns its ID directly (no status ticket).

POST /api/integration/task/json/{templateId}
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "projectId": "4f9c2b2e-1234-5678-9abc-0a1b2c3d4e5f",
  "title": "Prepare launch checklist",
  "overrideStatus": true,
  "overridePriority": true,
  "overrideWorkflow": true,
  "overrideWorkflowStatus": true
}

{
  "id": "a1b2c3d4-0000-1111-2222-333344445555"
}

The override... flags default to true. To set further fields on the new task (for example flavors or the description), send an update request afterwards.

Apply a Template to an Existing Task

Applies a task template to a task that already exists. You choose which parts of the template are applied.

PUT /api/integration/task/json/{taskId}/{templateId}
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

{
  "flavors": true,
  "labels": true,
  "description": true,
  "overwriteValues": false
}

All flags default to false. Set the parts you want to apply to true. The response is a boolean.

Get Tasks

GET /api/integration/task/json/{projectId}?lang=en&timezone=W. Europe Standard Time&viewId={viewId}
Authorization: Basic {YOUR_TOKEN}

The response contains the tasks of the project with fields like Id, Code, Title, Parent Id, Folder, and one Flavor:<Name> entry per flavor.

Get task with subtasks returns only a list of IDs: the task itself and all of its subtasks. To get the fields of those tasks, read them from the project's task list.

Task Dependencies

A dependency connects a predecessor (the task that must be completed first) with a successor (the task that is blocked until then). In both dependency endpoints, the taskId in the URL is always the successor.

Add or change dependencies

Dependencies that are not part of the request remain unchanged.

PATCH /api/integration/task/json/{taskId}/dependencies
Content-Type: application/json
Authorization: Basic {YOUR_TOKEN}

[
  { "taskId": "<predecessor task id>", "type": "FS", "lag": 2 }
]

To attach several predecessors, send several objects.

Remove dependencies

DELETE /api/integration/task/json/{taskId}/dependencies?taskIds={predecessorId1}&taskIds={predecessorId2}
Authorization: Basic {YOUR_TOKEN}

taskIds lists the predecessors that should no longer block the task. Dependencies not listed are kept.

📘

You can also manage dependencies in create and update requests with dependentOn (comma-separated predecessor IDs), dependencySet, and dependencyRemove. The constraintType field accepts "", SNET, SNLT, FNET, FNLT, MSO, or MFO.

Delete a Task

DELETE /api/integration/task/json/{taskId}
Authorization: Basic {YOUR_TOKEN}

Permissions & Visibility

Tasks follow the permission model of the project and the privacy settings of the task. If a user cannot perform an action in the UI, the API does not allow it either. See the Permissions & Privacy guide.

FAQ

Why is my change not visible right after the request?

Create and update requests are asynchronous. Poll the status ticket until it reports a result. See Integration Tickets.

How do I find out which ID belongs to which row I sent?

Send a tempId with each task. The status ticket returns createdIds, which maps every tempId to the ID of the created task.

How do I create a subtask?

Set parentId to the ID of an existing task. For several levels, create one level after the other.

Does an update overwrite the whole task?

No. Only the fields included in the request are changed.

Which end of a dependency is the taskId in the URL?

Always the successor, the task that depends on others. The taskId in the request body or in the taskIds query parameter identifies the predecessors.