This guide will walk you through the process of creating tasks on Fragment.

​
Requirements

​
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": "Task 1",
            "url": "https://backoffice.com/tasks/1",
            "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()

# Optional: store the task ID in your system
save_task_uuid(task["uid"])

​
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 (see Map IDs). 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(
    "https://api.onfragment.com/api/v1/tasks/{uid}",
    json={
        "fields": {
            "title": "Ticket 123",
            "url": "https://example.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(
    "https://api.onfragment.com/api/v1/tasks/{task_uuid}",
    json={
        "fields": {
            "country": "US",
        }
    },
    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

​
Eventual consistency

Depending on your use case, the synchronization between your existing system and Fragment might not be immediate and only eventually consistent. To avoid consistency issues and ghost tasks, you can set an eventual consistency delay in Fragment settings. This will temporarily hide newly created tasks in the backlog for this amount of time, to let enough time for any update to be propagated to Fragment that might close the task and result in unnecessary work.