Skip to main content
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

​
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

​
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
object
required
​
skills
string<uuid>[]
required
​
assignee_uid
string<uuid> | null
required
​
participants
object
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
object
required
​
metadata_form_uid
string<uuid> | null
required
​
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
object | null

User Schema.

​
parent
object | null

Task schema, same as Task Model.

​
children
Task · object[] | null
​
comments
TaskComment · object[] | null