This quickstart gets you from a new token to your first task in minutes.

​
Requirements

  • A Fragment account (preferably a dev environment)
  • Make sure you have the super admin role

​
1. Create an API token

In the app, go to Settings > Developers and create a token. We’ll call it token below. For convenience, you can set an environment variable (in your .bashrc file for example): 
export FRAGMENT_TOKEN=your_api_token_here
And load it at the beginning of your script like this:
quickstart.py
import os

token = os.getenv("FRAGMENT_TOKEN")
To learn more, see Authentication.

​
2. Verify authentication

To verify your authentication, make a request to the GET /v1/accounts/me endpoint.
quickstart.py
import requests

response = requests.get(
    "https://api.onfragment.com/api/v1/accounts/me",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
You should get a 200 OK response with your account information.

​
3. Create your first task

Let’s create a first task with
  • 2 standard fields: title (required) and url (optional)
  • a custom field: country
quickstart.py
import requests

response = requests.post(
    "https://api.onfragment.com/api/v1/tasks",
    json={
        "fields": {
            "title": "My first task",
            "url": "https://google.com",
            "country": "FR",
        }
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
uid = task["uid"]
You should get a 200 OK response with your task information. The uid key stores the task unique identifier (a UUID). We’ll use it to find the task later. 
{
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "TODO",
    "due_at": "2025-09-11T12:00:00.000Z",
    "fields": {
        "title": "My first task",
        "url": "https://google.com",
        "country": "FR",
    }
}
Notice how the task was created with
  • default status TODO
  • default due date (due_at) set to the current date and time.
For now, we don’t have to worry about the other available properties.
Unless you have already configured queues on Fragment, the task will not enroll in any task queue and won’t appear in the backlog page.You can search for “My first task” in the search bar to find the task.

​
4. Get the task by its UUID

To retrieve the task we just created, we can use the GET /v1/tasks/{uid} endpoint.
quickstart.py
import requests

response = requests.get(
    f"https://api.onfragment.com/api/v1/tasks/{uid}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
You should get a 200 OK response with your task information.

​
5. Search tasks by country

We can also search for tasks. For example, let’s search for tasks with the country field set to FR using the GET /v1/tasks endpoint.
quickstart.py
import requests

response = requests.get(
    "https://api.onfragment.com/api/v1/tasks",
    params={"country": "FR"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0"  ,
    }
)
response.raise_for_status()
data = response.json()
tasks = data["items"]
Notice how we get a list of tasks under the items key. To learn more about pagination, see Pagination.

​
5. Update task status

To update the task, we can use the PATCH /v1/tasks/{uid} endpoint. For example, let’s complete the task by updating its status to DONE.
quickstart.py
import requests

response = requests.patch(
    f"https://api.onfragment.com/api/v1/tasks/{uid}",
    json={"status": "DONE"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
You should get a 200 OK response with your task information. 
{
    "uid": "123e4567-e89b-12d3-a456-426614174000",
    "status": "DONE",
    "due_at": "2025-09-11T12:00:00.000Z",
    "done_at": "2025-09-11T12:10:00.000Z", // Automatically set when the status is updated to DONE
    "fields": {
        "title": "My first task",
        "url": "https://google.com",
        "country": "FR",
    }
}
Notice how status is a native field and doesn’t need to be nested in the fields key like title, url, or country.

​
6. (Optional) Add a comment

To add a comment to the task, we can use the POST /v1/tasks/{uid}/comments endpoint. For example, let’s add a comment to the task.
quickstart.py
import requests

response = requests.post(
    f"https://api.onfragment.com/api/v1/tasks/{uid}/comments",
    json={"text": "This is a comment"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
comment = response.json()
You should get a 200 OK response with your comment information.

​
Recap & full code

To recap what we’ve done
  • We’ve created an API token and verified authentication
  • We’ve created a task and retrieved it by its uid
  • We’ve searched for tasks by country
  • We’ve updated the task status
  • We’ve added a comment to the task
Full code
quickstart.py
import requests
import os

token = os.getenv("FRAGMENT_TOKEN")

# Verify authentication
resp = requests.get(
    "https://api.onfragment.com/api/v1/accounts/me",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
resp.raise_for_status()
print("Authentication successful")

# Create a task
response = requests.post(
    "https://api.onfragment.com/api/v1/tasks",
    json={
        "fields": {
            "title": "My first task",
            "url": "https://google.com",
            "country": "FR",
        }
    },
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
uid = task["uid"]
print(f"Task created with uid: {uid}")

# Get the task by its `uid`
response = requests.get(
    f"https://api.onfragment.com/api/v1/tasks/{uid}",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
print(f"Task retrieved with uid: {uid}")
print(task)

# Search tasks by `country`
response = requests.get(
    "https://api.onfragment.com/api/v1/tasks",
    params={"country": "FR"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
data = response.json()
tasks = data["items"]
print(f"Tasks found: {len(tasks)}")
print(tasks)

# Update the task status
response = requests.patch(
    f"https://api.onfragment.com/api/v1/tasks/{uid}",
    json={"status": "DONE"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
task = response.json()
print(f"Task updated with status: {task['status']}")

# Add a comment to the task
response = requests.post(
    f"https://api.onfragment.com/api/v1/tasks/{uid}/comments",
    json={"text": "This is a comment"},
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
        "User-Agent": "quickstart/1.0",
    }
)
response.raise_for_status()
comment = response.json()
print(f"Comment added with uid: {comment['uid']}")
print(comment)

​
Troubleshooting

  • 401 Unauthorized: check your token and Authorization: Bearer header.
  • 422 Unprocessable Entity: verify payload shape; see the Task object.
  • 429 Too Many Requests: reduce frequency and add retries; see Rate limiting.

​
Further reading

See the Task object guide for more details.