Tasks

A task is an action item, often derived from a meeting. These endpoints list, search, create, update, complete and delete tasks. A further endpoint lists the task categories, which resolve the taskCategoryId of a task.

Every endpoint below shows its parameters and response fields in the middle. On the right you find request samples in cURL, JavaScript and Python, an example response and Try it, which sends the request for real with your own token.

Lists the tasks of a directory (paginated, optionally filtered)

GET/v1.0/directories/{directoryId}/tasksTry it →

The ?filter selects a task view (default myTasks); the all* variants are admin/owner only. An optional ?search substring matches the task subject. Pagination via ?page + ?pageSize (max. 100). Resolve responsibleUserId/ownerId via GET /v1.0/directories/{directoryId}/memberships/users/{userId}.

Field overview from the specification

Response fields:

page / pageSize / total / hasMore: pagination envelope (current page, page size, total count, whether more pages follow).
items (array): the tasks on this page. Each item has:
- taskId (string): id of the task.
- subject (string): task subject.
- description (string | null): task description; null if unset.
- ownerId (string): id of the user who owns (created) the task.
- responsibleUserId (string | null): id of the user responsible for the task; null if unassigned.
- taskCategoryId (string | null): id of the task category; null if none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
- dueDate (string | null): due date (ISO 8601); null if no due date is set.
- isDone (boolean): whether the task is marked as done.
- doneOn (string | null): timestamp when the task was completed (ISO 8601); null if not done.
- isCanceled (boolean): whether the task is canceled.
- canceledOn (string | null): timestamp when the task was canceled (ISO 8601); null if not canceled.
- recordingSummaryId (string | null): id of the recording summary this task originated from; null if none.
- appointmentId (string | null): id of the appointment this task is linked to; null if none.
- createdOn (string): creation timestamp (ISO 8601).
- modifiedOn (string): last modification timestamp (ISO 8601).

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

filterstringoptional
Named preset that combines scope and state. my… covers every task the calling user is involved in, which means they are the responsible person OR the owner; all… every task of the directory the caller may see. The state part is Tasks (any), Open, Overdue, Completed or Forwarded. Forwarded is the one exception to the scope above: it lists only what the caller handed to someone else (owner is the caller, responsible is not). Omitted means no preset filter.
Allowed values: myTasksmyOpenmyOverduemyCompletedmyForwardedallTasksallOpenallOverdueallCompletedallForwarded
searchstringoptional
Case-insensitive substring match on the task subject. The term may appear at the start, middle, or end.
pagenumberoptional
Page number, 1-based. Defaults to 1.
pageSizenumberoptional
Items per page. Defaults to 25, capped at 100.
fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Response: each entry in items

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Every page also carries page, pageSize, total, hasMore.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
      "subject": "Quarterly planning",
      "description": "string",
      "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
      "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
      "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
      "dueDate": "2026-09-24T09:30:00Z",
      "isDone": true,
      "doneOn": "2026-09-24T09:30:00Z",
      "isCanceled": true,
      "canceledOn": "2026-09-24T09:30:00Z",
      "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Creates a task

POST/v1.0/directories/{directoryId}/tasksTry it →

Creates a task. The caller becomes the owner.

Field overview from the specification

Body fields:

subject (string, required): task subject (1..1000 characters).
description (string, optional): task description (max. 4000 characters); null for none.
responsibleUserId (string, optional): id of the responsible user; null or omitted leaves the task unassigned.
taskCategoryId (string, optional): id of the task category; null or omitted for none. Pick one from GET /v1.0/directories/{directoryId}/task-categories.
dueDate (string, optional): due date as an ISO 8601 string; null for no due date.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Request body application/json

subjectstringrequired
Task subject (1..1000 characters).
descriptionstringoptionalnullable
Task description (max. 4000 characters); null for none.
responsibleUserIdstringoptionalnullable
Id of the responsible user; null for unassigned.
taskCategoryIdstringoptionalnullable
Id of the task category; null for none. Pick one from GET /v1.0/directories/{directoryId}/task-categories; an id from another directory is rejected.
dueDatestringoptionalnullable
Due date as an ISO 8601 string; null for no due date.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Quarterly planning"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subject": "Quarterly planning"
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "subject": "Quarterly planning",
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Searches tasks (parameters in the body)

POST/v1.0/directories/{directoryId}/tasks/searchTry it →

Searches tasks.

Field overview from the specification

Body fields:

search (string, optional): case-insensitive substring over the task subject AND description.
responsible (string, optional): filter by responsible user id — your own is always allowed, another user or omitting it (= all responsibles) requires admin/owner.
status (string, optional): one of open (not done/canceled), completed, overdue (open + past due), canceled; omit for any status.
page (number, optional, default 1): 1-based page number.
pageSize (number, optional, default 25): page size (max. 100).

Results are sorted by due date ascending.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Request body application/json

searchstringoptionalnullable
Case-insensitive substring match on the task subject AND description. The term may appear at the start, middle, or end.
responsiblestringoptionalnullable
Filter by responsible user id. Your own id is always allowed; another user or omitting it (= all responsibles) requires admin/owner.
statusstringoptionalnullable
Filter by status: open (not done/canceled), completed, overdue (open + past due), canceled. Omit for any status.
Allowed values: opencompletedoverduecanceled
pagenumberoptional
Page (1-based, default 1).
pageSizenumberoptional
Page size (default 25, max 100).

Response: each entry in items

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Every page also carries page, pageSize, total, hasMore.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/search" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search": "pricing",
  "responsible": "string",
  "status": "open",
  "page": 1,
  "pageSize": 25
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/search`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "search": "pricing",
    "responsible": "string",
    "status": "open",
    "page": 1,
    "pageSize": 25
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/search",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "search": "pricing",
        "responsible": "string",
        "status": "open",
        "page": 1,
        "pageSize": 25,
    },
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
      "subject": "Quarterly planning",
      "description": "string",
      "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
      "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
      "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
      "dueDate": "2026-09-24T09:30:00Z",
      "isDone": true,
      "doneOn": "2026-09-24T09:30:00Z",
      "isCanceled": true,
      "canceledOn": "2026-09-24T09:30:00Z",
      "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Returns a single task by id

GET/v1.0/directories/{directoryId}/tasks/{taskId}Try it →

The caller must be allowed to view the task (owner, responsible, or admin/owner).

Field overview from the specification

Response fields:

taskId (string): id of the task.
subject (string): task subject.
description (string | null): task description; null if unset.
ownerId (string): id of the user who owns (created) the task.
responsibleUserId (string | null): id of the user responsible for the task; null if unassigned.
dueDate (string | null): due date (ISO 8601); null if no due date is set.
isDone (boolean): whether the task is marked as done.
doneOn (string | null): timestamp when the task was completed (ISO 8601); null if not done.
isCanceled (boolean): whether the task is canceled.
canceledOn (string | null): timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryId (string | null): id of the recording summary this task originated from; null if none.
appointmentId (string | null): id of the appointment this task is linked to; null if none.
createdOn (string): creation timestamp (ISO 8601).
modifiedOn (string): last modification timestamp (ISO 8601).

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Updates a task (partial update)

PATCH/v1.0/directories/{directoryId}/tasks/{taskId}Try it →

Updates a task. Only the provided fields are changed; omitted fields keep their current value, a null value explicitly clears a field. The caller must be allowed to edit the task.

Field overview from the specification

Body fields:

subject (string, optional): new task subject (1..1000 characters).
description (string, optional): new task description (max. 4000 characters); null to clear.
responsibleUserId (string, optional): new id of the responsible user; null to unassign.
taskCategoryId (string, optional): new id of the task category; null to clear. Pick one from GET /v1.0/directories/{directoryId}/task-categories.
dueDate (string, optional): new due date as an ISO 8601 string; null to clear.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Request body application/json

subjectstringoptional
New task subject (1..1000 characters).
descriptionstringoptionalnullable
New task description (max. 4000 characters); null to clear.
responsibleUserIdstringoptionalnullable
New id of the responsible user; null to unassign.
taskCategoryIdstringoptionalnullable
New id of the task category; null to clear. Pick one from GET /v1.0/directories/{directoryId}/task-categories; an id from another directory is rejected.
dueDatestringoptionalnullable
New due date as an ISO 8601 string; null to clear.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X PATCH "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Quarterly planning",
  "description": "string",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
  "dueDate": "2026-09-24T09:30:00Z"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subject": "Quarterly planning",
    "description": "string",
    "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
    "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
    "dueDate": "2026-09-24T09:30:00Z"
  }),
});
const data = await response.json();

import os
import requests

response = requests.patch(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "subject": "Quarterly planning",
        "description": "string",
        "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
        "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
        "dueDate": "2026-09-24T09:30:00Z",
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Deletes a task (soft-delete)

DELETE/v1.0/directories/{directoryId}/tasks/{taskId}Try it →

Only the owner or an admin/owner may delete a task.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Status codes

204Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X DELETE "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
console.log(response.status); // 204

import os
import requests

response = requests.delete(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
print(response.status_code)  # 204

Response example 204 No Content

No content. A successful call returns an empty body.

Toggles the done status of a task

POST/v1.0/directories/{directoryId}/tasks/{taskId}/doneTry it →

Toggles the done status of a task.

Field overview from the specification

Body fields:

isDone (boolean, required): true to mark the task as done, false to reopen it.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskCategoryId, taskId.
Example: appointmentId,canceledOn

Request body application/json

isDonebooleanrequired
True to mark the task as done, false to reopen it.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
taskCategoryIdstringrequirednullable
Id of the task category; null if the task has none. Resolve via GET /v1.0/directories/{directoryId}/task-categories.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Try it

Send this request for real, with your own token and your own data.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID/done" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isDone": true
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}/done`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "isDone": true
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}/done",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "isDone": True,
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

GET/v1.0/directories/{directoryId}/task-categoriesTry it →

Returns the categories a task can carry: the ones the directory owns plus the global Sally defaults, ordered by name.

Deactivated categories are included with active: false so a task that still carries one stays resolvable; they are no longer offered for new tasks.

Field overview from the specification

Response fields:

items (array): the task categories. Each item has:
- taskCategoryId (string): id of the category.
- name (string): category name.
- description (string | null): what the category covers; this text is what Sally is given when it picks a category for a recognized task. Null if unset.
- active (boolean): whether the category is still offered for new tasks.
- isGlobal (boolean): true for a global Sally default, false for one the directory owns.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: active, description, isGlobal, name, taskCategoryId.
Example: active,description

Response

itemsobject[]required
The task categories of the directory.
5 child fields
- taskCategoryIdstringrequired
  Id of the task category.
- namestringrequired
  Category name.
- descriptionstringrequirednullable
  What the category covers. This text is what Sally is given when it picks a category for a recognized task. Null if unset.
- activebooleanrequired
  Whether the category is still offered for new tasks. A deactivated category stays readable so existing tasks keep resolving.
- isGlobalbooleanrequired
  True for a global Sally default, false for a category the directory owns.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/task-categories" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/task-categories`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/task-categories",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "items": [
    {
      "taskCategoryId": "3c13ce69-a48a-44df-ad01-7b55ce3e61e5",
      "name": "Example",
      "description": "string",
      "active": true,
      "isGlobal": true
    }
  ]
}

Lists the tasks of a directory (paginated, optionally filtered)​

Path parameters

Query parameters

Response: each entry in items

Status codes

Creates a task​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Searches tasks (parameters in the body)​

Path parameters

Query parameters

Request body application/json

Response: each entry in items

Status codes

Returns a single task by id​

Path parameters

Query parameters

Response

Status codes

Updates a task (partial update)​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Deletes a task (soft-delete)​

Path parameters

Status codes

Toggles the done status of a task​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Lists the task categories of a directory (resolves `taskCategoryId`)​

Path parameters

Query parameters

Response

Status codes

Lists the tasks of a directory (paginated, optionally filtered)

Creates a task

Searches tasks (parameters in the body)

Returns a single task by id

Updates a task (partial update)

Deletes a task (soft-delete)

Toggles the done status of a task

Lists the task categories of a directory (resolves `taskCategoryId`)