Task

The Task object is the core entity in Fragment. It represents a single item of work. It can be used as a one-off task that is generated as part of a broader workflow. It can also be used to represent a ticket that is passed along between different teams.

Example

In this first example, the task has the default fields title, url, and custom fields ticket_id and country.

{
    "status": "TODO",
    "due_at": "2025-09-11T12:00:00.000Z",
    "fields": {
        "title": "Ticket 123",
        "url": "https://backoffice.com/tickets/123",
        "ticket_id": 123, 
        "country": "FR"
    }
}

Custom fields

The task stores its custom attributes in the fields key, including two default fields:

title - A human-readable title for the task
url - An optional URL that provides additional context or links to related resources. The Fragment player will open this URL when the task is opened in the chrome extension.

You can add custom fields to store any additional data relevant to your workflow. Prefer using snake_case for custom field attributes though any valid JSON key is allowed. The API will accept any valid JSON.

No type validation is performed on the custom fields. You are responsible for ensuring the data type is consistent.

To configure how the custom fields behaved in the UX, see Configure the data model.

Relevant API endpoints

POST /tasks: create a task
PUT /tasks/:id: create or update a task (idempotent)
PATCH /tasks/:id: update a task
POST /tasks/batch: bulk create tasks
PUT /tasks/batch: bulk create or update tasks (idempotent)
PATCH /tasks/batch: bulk update tasks

Create tasks

Use the POST /tasks endpoint to create the task in Fragment.

create.py

import requests


response = requests.post(
    "https://api.onfragment.com/api/v1/tasks",
    json={
        "fields": {
            "title": "Ticket 123",
            "url": "https://backoffice.com/tickets/123",
            "country": "FR",
            "ticket_id": 123,
        }
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "acme/1.0",
    }
)
response.raise_for_status()
task = response.json()

Upsert tasks (idempotent)

To avoid double task creation in case of retries and network errors, you can use the PUT /tasks/{uid} endpoint instead of POST /tasks. The PUT endpoint is idempotent and requires you to generate a task ID that is stable across retries. For example:

upsert.py

import requests

# Generate a task UUID that is stable across retries
# NOTE: it can be a random UUID or a stable hash from the ticket ID
uid = generate_uuid()

# Perform an idempotent PUT request to create the task
response = requests.put(
    f"https://api.onfragment.com/api/v1/tasks/{uid}",
    json={
        "fields": {
            "title": "Ticket 123",
            "url": "https://backoffice.com/tickets/123",
            "country": "FR",
            "ticket_id": 123,
        }
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "acme/1.0",
    }
)
response.raise_for_status()
task = response.json()

Update tasks

When you update a ticket in your existing system or simply need to update the task in Fragment because of some event, you might need to update the corresponding task in Fragment. Use the PATCH /tasks/{uid} endpoint to update the task in Fragment. For example

update.py

# Retrieve the task ID from your system
task_uuid = "123e4567-e89b-12d3-a456-426614174000"

# Perform a PATCH request to update the task
response = requests.patch(
    f"https://api.onfragment.com/api/v1/tasks/{task_uuid}",
    json={
        "fields": {
            "country": "US",
        },
        "status": "DONE"
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "acme/1.0",
    }
)
response.raise_for_status()
task = response.json()

Bulk upserts

If you have a high volume of tickets, you might want to create them in bulk. Relevant endpoints

POST /tasks/batch: create the tasks in Fragment in bulk.
PUT /tasks/batch: create or update the tasks in Fragment in bulk.
PATCH /tasks/batch: update the tasks in Fragment in bulk.

Schema

Task schema, same as Task Model.

uid

string<uuid>

required

archived

boolean

required

status

enum<string>

required

Task Status Enum.

Available options:

TODO,

STARTED,

DONE

legacy_data

Legacy Data · object

required

skills

string<uuid>[]

required

assignee_uid

string<uuid> | null

required

participants

Participants · object

required

Show child attributes

participants.{key}

ParticipantInfo · object

Participant information.

Show child attributes

participants.{key}.subscribed

boolean

required

case_uid

string<uuid> | null

required

parent_uid

string<uuid> | null

required

due_at

string<date-time>

required

snooze_expires_at

string<date-time> | null

required

fields

Fields · object

required

metadata_form_uid

string<uuid> | null

required

form_data

Form Data · object

required

form_type

string | null

required

assigned_at

string<date-time> | null

required

started_at

string<date-time> | null

required

done_at

string<date-time> | null

required

created_at

string<date-time>

required

updated_at

string<date-time>

required

assignee_updated_by

string<uuid> | null

required

queue_updated_by

string<uuid> | null

required

is_assigned_player

boolean | null

required

internal_created_at

string<date-time> | null

required

internal_updated_at

string<date-time> | null

required

external_created_at

string<date-time> | null

required

external_updated_at

string<date-time> | null

required

external_status

enum<string> | null

required

Task Status Enum.

Available options:

TODO,

STARTED,

DONE

external_status_updated_at

string<date-time> | null

required

external_assignee_uid

string<uuid> | null

required

queue_time

integer | null

required

queue_time_business

integer | null

required

work_time

integer | null

required

work_time_business

integer | null

required

incremental_work_time

integer | null

required

incremental_work_time_business

integer | null

required

resolution_time

integer | null

required

resolution_time_business

integer | null

required

num_children

integer

required

num_children_done

integer

required

queue_uid

string<uuid> | null

sla_breach_at

string<date-time> | null

sla_breach_business_at

string<date-time> | null

wait_time

integer | null

wait_time_business

integer | null

review_status

string | null

task_type

string | null

played_at

string<date-time> | null

assignee

User · object

User Schema.

Show child attributes

assignee.uid

string<uuid>

required

assignee.archived

boolean

required

assignee.role

enum<string>

required

User Role Enum.

Available options:

super_admin,

admin,

member

assignee.email

string<email>

required

assignee.first_name

string

required

assignee.last_name

string

required

assignee.skills

string<uuid>[]

required

assignee.legacy_data

Legacy Data · object

required

assignee.created_at

string<date-time>

required

assignee.updated_at

string<date-time>

required

assignee.is_registered

boolean | null

parent

unknown

children

any[] | null

comments

TaskComment · object[] | null

Show child attributes

comments.uid

string<uuid>

required

comments.archived

boolean

required

comments.task_uid

string<uuid>

required

comments.author_uid

string<uuid> | null

required

comments.text

string

required

comments.blocks

TextBlock · object[]

required

Show child attributes

comments.blocks.id

string

required

comments.blocks.type

string

required

comments.blocks.props

Props · object

comments.blocks.content

TextBlockContent · object[]

Show child attributes

comments.blocks.content.type

string

required

comments.blocks.content.text

string | null

comments.blocks.content.href

string | null

comments.blocks.content.content

Content · array

comments.blocks.content.styles

Styles · object

comments.blocks.content.props

Props · object

comments.blocks.children

Children · array

comments.created_at

string<date-time>

required

comments.updated_at

string<date-time>

required

comments.task

unknown

comments.author

User · object

User Schema.

Show child attributes

comments.author.uid

string<uuid>

required

comments.author.archived

boolean

required

comments.author.role

enum<string>

required

User Role Enum.

Available options:

super_admin,

admin,

member

comments.author.email

string<email>

required

comments.author.first_name

string

required

comments.author.last_name

string

required

comments.author.skills

string<uuid>[]

required

comments.author.legacy_data

Legacy Data · object

required

comments.author.created_at

string<date-time>

required

comments.author.updated_at

string<date-time>

required

comments.author.is_registered

boolean | null

Introduction

Guides

Objects

Endpoints

Example

Custom fields

Relevant API endpoints

Create tasks

Upsert tasks (idempotent)

Update tasks

Bulk upserts

Schema

Introduction

Guides

Objects

Endpoints

​Example

​Custom fields

​Relevant API endpoints

​Create tasks

​Upsert tasks (idempotent)

​Update tasks

​Bulk upserts

​Schema

Example

Custom fields

Relevant API endpoints

Create tasks

Upsert tasks (idempotent)

Update tasks

Bulk upserts

Schema