​
Data Types

Dates

We follow the ISO8601 standard with time zone information.

Example 2023-07-28T03:39:51.140537+00:00

In Python, you can generate those dates with

from datetime import datetime, timezone

now = datetime.now(timezone.utc)
now.isoformat()  # '2023-07-28T03:44:17.276943+00:00'

​
Task

This is the core entity of Fragment. It represents a single item of work.

Endpoints

  • POST /v1/tasks/
  • PATCH /v1/tasks/
  • GET /v1/tasks/:id
  • GET /v1/tasks
  • DELETE /v1/tasks/:id

The Task object

Example

{
    "id": "1",
    "url": "https://google.com",
    "title": "Google",
    "tags": {
        "name": "Google",
        "category": "test",
        "priority": "low"
    }
}

Attributes

  • id string : unique identifier. If not given on creation, the API generates one.
  • url string (required) : the URL of the task. The Fragment player takes agents to this URL.
  • title string (optional) : captures the description of the task, displayed to the agent
  • tags hash (optional) : custom attributes used for dispatch by Fragment. The schema for tags is your choice.

Other attributes

  • status hash : if not specified, generated by the API. It identifies the status of the task.

    It has the following child attributes

    • name string : values can be among TODO , LOCKED, ASSIGNED, or DONE
    • userId string : task owner
    • at date : date at which the task entered this status

  • createdAt date (optional) : if not specified, current time

  • dueAt date (optional) : if not specified, current time

  • startedAt date (optional) : date the task entered the STARTED status

  • doneAt date (optional) : date the task entered the DONE status

  • updatedAt date (optional) : if not specified, current time

Create or Update a Task

You can use either the POST or PATCH methods to create a task.

If you use the POST endpoint and a task with the same id already exists, you will get a 403

status code.

The PATCH endpoint is more flexible.

  • If no task exists with the same id it creates a new one
  • If a task exists with the same id it updates the content (overrides the field passed in the request)

Both endpoints return a JSON of the corresponding resource with a 200 status code. This avoids additional calls.

Example

curl --location --request PATCH 'https://api.onfragment.com/v1/tasks' \
--header 'x-api-key: 9d0a33f69da2eb548ef5b47640169af1' \
--header 'Content-Type: application/json' \
--data '{
    "id": "1",
    "url": "https://google.com",
    "title": "Google",
    "tags": {
        "name": "Google",
        "category": "test",
        "priority": "low"
    }
}'

which returns

{
    "createdAt": "2023-07-28T03:39:51.140537+00:00",
    "doneAt": null,
    "dueAt": "2023-07-28T03:39:51.140537+00:00",
    "id": "1",
    "startedAt": null,
    "status":
    {
        "at": null,
        "name": "TODO",
        "userId": null
    },
    "tags":
    {
        "category": "test",
        "name": "Test",
        "priority": "low"
    },
    "title": "Test",
    "updatedAt": "2023-07-28T03:39:51.140537+00:00",
    "url": "https://google.com"
}

Get a task

You can retrieve task with the GET resource by specifying the ID of the task that you received after creating the task. The same information should be returned.

Example

curl --location --request GET 'https://api.onfragment.com/v1/tasks/1' \
--header 'x-api-key: 9d0a33f69da2eb548ef5b47640169af1' \
--header 'Content-Type: application/json' \

List all tasks

Return a list of all the tasks that you previously created.

The tasks are returned in sorted order : first the tasks that are not DONE , ordered by dueDate (past to future), then the tasks that are DONE (from present to the past).

Example

curl --location --request GET 'https://api.onfragment.com/v1/tasks/' \
--header 'x-api-key: 9d0a33f69da2eb548ef5b47640169af1' \
--header 'Content-Type: application/json'

Which responds with status code 200 and a JSON with the following entries

  • items array[Task] : the list of tasks
  • total int : the total number of tasks (not just in the response, but in general)
  • next string (optional) : if specified, the URL for accessing the next page

Pagination

We currently limit the number of returned tasks to 1000

If you have more tasks, the response contains a next attribute that takes you to the next page. If this attribute is null, it means all the data has been retrieved.