Refonte AI

Create a task

A task is a discrete piece of work that needs to be completed by a Contributor. The task and the data that needs to be tagged are mapped 1:1. For instance, there would be a single job for every image, video, or lidar series that required labeling.

When you make an API request with a set of task parameters to the desired endpoint, you indicate how the labeling for a certain job should be done.

Tasks have a type such as "Image Annotation", "Video Annotation", "Lidar Segmentation", or "Document Transcription".

For information on how to create specific task types, you can click on the links below:

Task Metadata

There is a metadata parameter on tasks objects. This option can be used to associate tasks with key-value data.

You can store extra structured information about an object using metadata, particularly information that will assist you understand the task response or remember what content this task relates to.

Metadata is not used by Refonte.Ai (e.g., to affect how the task is done).

Common use-cases for metadata:

  • Internal identifiers
  • File paths
  • Scenario / Run / Case identifiers
  • Environment details (time of day, location)
  • Sensor information
  • Guideline / Taxonomy versions

Example Task Object

{
  "task_id": "576ba74eec471ff9b01557cc",
  "created_at": "2016-06-23T09:09:34.752Z",
  "updated_at": "2016-06-23T09:10:02.798Z",
  "completed_at": "2016-06-23T09:10:02.798Z",  
  "type": "categorization",
  "status": "completed",
  "instruction": "Would you say this item is big or small?",
  "params": {
    "attachment_type": "text",
    "attachment": "car",
    "categories": [
      "big",
      "small"
    ]
  },
  "callback_url": "http://www.example.com/callback",
  "callback_completed": true,
  "response": {
    "category": "big"
  },
  "metadata": {},
  "audits": [
    {
      "audited_by": "admin@refone.ai",
      "audited_at": "2016-06-24T15:32:03.585Z",
      "audit_time_secs": 120,
      "audit_result": "accepted",
      "audit_source": "customer"
    },
    {
      "audited_by": "admin@refone.ai",
      "audited_at": "2016-06-23T10:01:02.352Z",
      "audit_time_secs": 511,
      "audit_result": "fixed",
      "audit_source": "refonte"
    }
  ],
  "tags": ["experiment_1", "owner:david"],
  "unique_id": "product_experiment_dg3d9x83"
}

Retrieve a task

Quickly obtain comprehensive task details, with the option to access a particular work by its task ID. This clever feature makes it possible to integrate jobs seamlessly and analyze them thoroughly, which improves the data-driven capabilities of your workflow. Examine task information with ease using this crucial endpoint.

Path Params

taskId string required

Request

Python

GET  /v1/task/{taskId}
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json"
}

# Adding authentication to the GET request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "task_id": "601ba74eec471ff9b01557cc",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "canceled",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "metadata": {
    "key": "value",
    "key2": "value2"
  }
}

Retrieve Multiple Tasks

This is a paginated endpoint that retrieves a list of your tasks.

The tasks will be returned in descending order based on created_at time. All time filters expect an ISO 8601-formatted string, like '2021-04-25' or '2021-04-25T03:14:15-07:00'

The pagination is based on the limit and next_token parameters, which determine the page size and the current page we are on. The value of `next_token` is a unique pagination token for each page (nerdy details if you were curious). Make the call again using the returned token to retrieve the next page.

Query Params

start_time string

The minimum value of created_at for tasks to be returned

Request

Python

GET  /v1/tasks
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint with query parameters

params = {
    status: completed,
    type: imageannotation,
    project: kitten_labeling,
    batch: kitten_labeling_2020-07,
    customer_review_status: accepted,
    limit: 100,
    include_attachment_url: true
}

url = "https://api.refonte.com/v1/tasks?params"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json"
}

# Adding authentication to the GET request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.get(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "docs": [
    {
      "task_id": "601ba74eec471ff9b01557cc",
      "created_at": "2021-06-23T09:09:34.752Z",
      "callback_url": "http://www.example.com/callback",
      "type": "imageannotation",
      "status": "canceled",
      "instruction": "Label every object in this image",
      "params": {
        "attachment": "https://example.com/image.jpg",
        "geometries": {
          "box": {
            "objects_to_annotate": [
              "vehicle",
              "pedestrian"
            ]
          }
        }
      },
      "metadata": {
        "key": "value",
        "key2": "value2"
      }
    }
  ],
  "total": 220,
  "limit": 100,
  "has_more": true,
  "next_token": "eyJ0YXNrX2lkIjoiNjBkYjgwZTFkYmRkNTMwMDExNDZlMzg..."
}

Cancel Task

The endpoint will return a 400 error code if you try to cancel a job that has already been finished. You can only cancel tasks that are still pending.

If the task to be cancled had a unique id, specifying

`clear_unique_id=true` will remove the unique id. Canceling tasks is idempotent such that calling this endpoint multiple times will still return a 200 success response.

Path Params

taskId string required

Query Params

clear_unique_id string

If true, will clear a task's unique_id, thus allowing the same unique id to be used in future tasks.

Request

Python

POST  /v1/task/{taskId}/cancel
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint with query parameters
params = {
    clear_unique_id: true
}
url = "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc/cancel?params"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json"  
}

# Adding authentication to the POST request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.post(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "task_id": "601ba74eec471ff9b01557cc",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "canceled",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "metadata": {
    "key": "value",
    "key2": "value2"
  }
}

Set Task Metadata

This endpoint sets the `metadata` field on a task. You may set the metadata field on any existing task using valid key-value data.

A 200 success response will still be returned if you contact this endpoint more than once because updating a task's metadata field is idempotent.

Path Params

taskId string required

Request

Python

POST  /v1/task/{taskId}/setMetadata
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url =
 "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc/setMetadata"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json",
    "content-type": "application/json"
}

# Define the payload for setting metadata
payload = {
    # Add your metadata here
    # For example: "metadata_key": "metadata_value"
}

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, headers=headers, json=payload, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "task_id": "601ba74eec471ff9b01557cc",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "canceled",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "metadata": {
    "key": "value",
    "key2": "value2"
  }
}

Update unique_id

The Refonte.Ai Update Task Unique ID API endpoint makes it simple to improve task management and data accuracy. Task identifiers may be easily changed and optimized to keep your task tracking and organization accurate and effective. This API provides a simplified method for managing unique IDs linked to jobs in your workflow, enabling you to preserve data flexibility and integrity. Examine this flexible endpoint to easily customize task identification based on your changing requirements.

Path Params

taskId string required

ID of the Task to modify

Request

Python

POST  /v1/task/{task_id}/unique_id
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url =
    "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc/unique_id"

# Define the payload to set the unique ID for the task
payload = {
    # Unique ID to be set
    "unique_id": "56766ba764ee6c4761f6f9b6015657cc6"
}

# Set up the headers for the request
headers = {
     # Specify that we want the response in JSON format
    "accept": "application/json",
    "content-type": "application/json"
}

# Adding authentication to the POST request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.post(url, json=payload, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "task_id": "601ba74e98762345bcbcaaaa",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "completed",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "unique_id": "new_unique_id"
  "metadata": {}
}

Delete unique_id

Gives you more control over your data management procedures by enabling the safe removal of task identifiers. With confidence, you can remove unnecessary or duplicate task unique IDs from your system, preserving data correctness and enhancing workflow structure. Integrate this feature seamlessly into your task management process to guarantee that your records are kept clear and current. To improve your data management procedures, take advantage of the Refonte Delete Task Unique ID endpoint's ease of use and adaptability.

Path Params

taskId string required

ID of the Task to modify

Request

Python

DELETE  /v1/task/{task_id}/unique_id
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc/unique_id"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json"
}

# Adding authentication to the DELETE request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.delete(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Response

{
  "task_id": "601ba74e98762345bcbcaaaa",
  "created_at": "2021-06-23T09:09:34.752Z",
  "callback_url": "http://www.example.com/callback",
  "type": "imageannotation",
  "status": "completed",
  "instruction": "Label every object in this image",
  "params": {
    "attachment": "https://example.com/image.jpg",
    "geometries": {
      "box": {
        "objects_to_annotate": [
          "vehicle",
          "pedestrian"
        ]
      }
    }
  },
  "metadata": {}
}

Add Task Tag

You can attach a list of tags to a job by using this endpoint. To prevent duplication, a tag that is already attached to the job will be disregarded. It is not permitted to set an empty or null string as a tag, please note. To correctly update the task's tags, make sure the tags list contains valid, non-empty strings.

Path Params

taskId string required

ID of the Task to modify

Body Params

RAW_BODY array of strings

List of tags to add to the task

Request

Python

POST  /v1/task/{task_id}/tags
import requests

# Replace with your actual API key
API_KEY = 'your_api_key_here'

# Define the URL for the API endpoint
url = "https://api.refonte.com/v1/task/576ba74eec471ff9b01557cc/tags"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json",       
    "content-type": "application/json"
}

# Define the payload to set the tags for the task
payload = [
    "tag1",
    "tag2",
    "tag3"
]

# Adding authentication to the PUT request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.put(url, headers=headers, json=payload, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Set Task Tag

This endpoint allows you to set a completely new list of tags on a task. This will replace all currently existing tags on it if the target exists.

Path Params

taskId string required

ID of the Task to modify

Body Params

RAW_BODY array of strings

List of tags to add to the task

Request

Python

POST  /v1/task/{task_id}/tags
import requests

# Replace with your actual API key and task ID
API_KEY = 'your_api_key_here'
TASK_ID = 'task_id_here'

# Define the URL for the API endpoint
url = f"https://api.refonte.com/v1/task/{TASK_ID}/tags"

# Set up the headers for the request
headers = {
    # Specify that we want the response in JSON format
    "accept": "application/json",       
    "content-type": "application/json"
}

# Define the payload to set the tags for the task
payload = [
    "tag1",
    "tag2",
    "tag3"
]

# Adding authentication to the POST request
# The auth parameter requires a tuple with the API key and an empty string
response = requests.post(url, headers=headers, json=payload, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Delete Task Tag

A list of tags that should be added to a task can be included with this endpoint. In order to prevent redundancy, a tag that is already attached to the task will be disregarded. Please be aware that it is not permitted to set an empty or null string as a tag. For the task's tags to be correctly updated, make sure the tags list contains valid, non-empty strings.

Path Params

taskId string required

ID of the Task to modify

Body Params

RAW_BODY array of strings

List of tags to add to the task

Request

Python

POST  /v1/task/{task_id}/tags
import requests

# Replace with your actual API key and task ID
API_KEY = 'your_api_key_here'
TASK_ID = 'task_id_here'

# Define the URL for the API endpoint
url = f"https://api.refonte.com/v1/task/{TASK_ID}/tags"

# Set up the headers for the request
headers = {
     # Specify that we want the response in JSON format
    "accept": "application/json",      
    "content-type": "application/json"
}

# Adding authentication to the DELETE request
# The auth parameter requires a tuple
# with the API key and an empty string
response = requests.delete(url, headers=headers, auth=(API_KEY, ''))

# Print the response text to see the result
print(response.text)

Avoiding Duplicate Tasks

Creating duplicate tasks is an issue every team should be mindful to avoid.

To stop duplicate tasks from being produced in its task generation endpoints, Refonte.Ai AI offers two distinct techniques. This reduces the possibility of generating duplicate jobs when you resubmit requests that might have failed in transit or otherwise need to be retried.

Option 1: The unique_id field. The unique_id field is a field available on every task type Refonte provides.

Any subsequent task creation requests with the same unique_id will fail with a 409 error that conveniently points to the conflicting task once a unique_id has been given to refonte. When you retrieve tasks from our platform, the values you enter into the unique_id field will always be returned to you and will be permanently connected with the job. Using our Task Retrieval endpoints, you can query for tasks directly at any time based on the unique_id field.

Best Practices:

  • Consider unique_id to be your personal, modifiable task id. Ideally, with the information you have at your disposal, finding this ID should be simple. A suitable unique_id may be the filename that is being submitted, or additional metadata that you utilize internally, such as a run id or scene id.
  • Globally, unique_id is established for all task kinds and projects. We advise only preceding or adding the project or task type to the unique id itself if you'd like to guarantee uniqueness solely within a project or task type. Problem solved!

Option 2: The Idempotency-Key header

To use this feature, provide a header Idempotency-Key: ‹key›. You, the client, are responsible for ensuring the uniqueness of your chosen keys. We recommend using V4 UUIDs.

Request responses with an idempotency key specified are stored. We won't create a new task if we subsequently receive a matching request with the same idempotency key; instead, we'll return the saved response. Notably, this effect persists even in cases where the response is incorrect. The keys are taken out after a day.

We will return a 409 error if an incoming request has the same idempotency key as a saved request, but the parameters of the two requests differ or the users linked to the two requests are not the same.

In rare instances, if two matching requests with the same idempotency key are sent at the same time, we might respond with a 429 error. It is okay to try again in this instance.

When would I use this instead of the unique_id field?

When you would be instantly retrying the exact same request, using the header-based technique is helpful in retry logic that detects network or other temporary failure modes. Code integrations are made simpler by the functionality that enables you to effortlessly receive the same task response back even if the payload has changed.

You are able to use both options simultaneously as well.

Workflow Support

Because Unique Ids are inextricably linked to a work, it may be difficult to recover on your own in the event of an unforeseen circumstance. To enable stronger workflows, we have implemented two features.

Canceling Tasks

When canceling tasks, there is a clear_unique_id query parameter you can specify on the request. See the Cancel Task endpoint for more details.

Errored Tasks

An error may occasionally arise when a task is submitted, particularly when processing attachments. You can set clear_unique_id_on_error: true anywhere you can set a unique id. As the name of the parameter implies, the unique id will be immediately unset if the task enters an error status, allowing you to submit a new task with the same new unique id.

Request

Python

import refonteapi
from refonteapi.tasks import TaskType
from refonteapi.exceptions import refonteDuplicateResource

# Initialize the RefonteClient with your API key
client = refonteapi.RefonteClient("YOUR_API_KEY_HERE")

# Define the task payload
payload = {
    "project": "your_project_name",
    "callback_url": "http://www.example.com/callback",
    "instruction": "Draw a box around each object.",
    "attachment_type": "image",
    "attachment": "http://i.imgur.com/v4cBreD.jpg",
    "unique_id": "unique_task_id_12345",
    "geometries": {
        "box": {
            "objects_to_annotate": ["Object"],
            "min_height": 10,
            "min_width": 10,
        }
    },
}

# Attempt to create the task, handling duplicates
try:
    task = client.create_task(TaskType.ImageAnnotation, **payload)
    print(f"Task created successfully: {task.as_dict()}")
except refonteDuplicateResource as err:
    print(f"Task creation failed: {err.message}")

Adding unique_id to your payload

{  
  	"unique_id": "s3://bucket/file.png",
    "instruction": "Do the thing",
  	"callback_url": "refonte@callback.com",
  	...
}

Example 409 Error

{
    "status_code": 409,
    "error": 'The unique_id ("s3://bucket/file.png")
        is already used for a different task
        (602c399c6d092c00115aa3c9).'
}

Example Idempotent Key Header

curl
  "https://api.refonte.com/v1/task/comparison"
    -u "{{ApiKey}}:"
    -H "Idempotency-Key: UNIQUE_IDENTIFIER"
    -d callback_url="http://www.example.com/callback"
  ...

Updated about 2 months ago