Resources
API resources
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 amongTODO
,LOCKED
,ASSIGNED
, orDONE
- userId
string
: task owner - at
date
: date at which the task entered this status
- name
-
createdAt
date
(optional) : if not specified, current time -
dueAt
date
(optional) : if not specified, current time -
startedAt
date
(optional) : date the task entered theSTARTED
status -
doneAt
date
(optional) : date the task entered theDONE
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.