TaskMonk (v1.1)

Download OpenAPI specification: Download

APIs to integrate with TaskMonk service. Refer to http://docs.taskmonk.io/concepts.html for an overview.

Use preprod.taskmonk.io to test the APIs and api.taskmonk.io for production use.

Authentication

oauth_2_0

OAuth2 is a protocol that lets external apps request authorization to TaskMonk

Security scheme type: OAuth2
OAuth2 Flow clientCredentials
Token URL /api/oauth2/token

OAuth2 Scopes

Batch

Create a batch

Creates a batch for a project.

Parameters
path Parameters ?
project_id
string Required
Request Body

batch_name
string Required
priority
integer <int32>

An optional priority for the batch based on which tasks will be executed. Higher priority batches are processed first.
comments
string

An optional message that is displayed to the analyst as they work on the tasks.
notifications
Notification

Notifications can be used for the requestors to be notified when milestones for a batch are completed.
start_time
string

An optional start time (YYYY-MM-DD) to specify that when the batch should be made active. If the date is specified and is beyond the current date, the batch status will be set to "Scheduled" instead of "Active"

This cannot be changed if the batch is already Active

Responses

200 Returns the batch id
Response Schema
id
string Required
post
/api/project/{project_id}/batch

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/batch
Request samples
Copy Expand all Collapse all 
{
  • "batch_name": "string",
  • "priority": 0,
  • "comments": "string",
  • "notifications": 
    [
    ],
  • "start_time": "string"
}

Response samples

  • 200 Returns the batch id

Copy Expand all Collapse all 
{
  • "id": "string"
}

Get batches of a projects

Retrieves batches for the project id

Parameters
path Parameters ?
project_id
string Required

Responses

200 Sequence of batches
Response Schema
id
string Required

Id for the batch
project_id
string Required
name
string Required

name of the batch
priority
integer <int32>

An optional priority for the batch based on which tasks will be executed. Higher priority batches are processed first.
comments
string

An optional message that is displayed to the analyst as they work on the tasks.
notifications
Notification

Notifications can be used for the requestors to be notified when milestones for a batch are completed.
get
/api/project/{project_id}/batch

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/batch

Response samples

  • 200 Sequence of batches

Copy Expand all Collapse all 
{
  • "id": "string",
  • "project_id": "string",
  • "name": "string",
  • "priority": 0,
  • "comments": "string",
  • "notifications": 
    [
    ]
}

Edit batch

Edit details for a batch

Parameters
path Parameters ?
projectId
string Required
batchId
string Required
Request Body

batch_name
string Required
priority
integer <int32>

An optional priority for the batch based on which tasks will be executed. Higher priority batches are processed first.
comments
string

An optional message that is displayed to the analyst as they work on the tasks.
notifications
Notification

Notifications can be used for the requestors to be notified when milestones for a batch are completed.
start_time
string

An optional start time (YYYY-MM-DD) to specify that when the batch should be made active. If the date is specified and is beyond the current date, the batch status will be set to "Scheduled" instead of "Active"

This cannot be changed if the batch is already Active

Responses

200 success
Response Schema
success
boolean Required
message
string
put
/api/project/{projectId}/batch/{batchId}

Server URL

https://preprod.taskmonk.io/api/project/{projectId}/batch/{batchId}
Request samples
Copy Expand all Collapse all 
{
  • "batch_name": "string",
  • "priority": 0,
  • "comments": "string",
  • "notifications": 
    [
    ],
  • "start_time": "string"
}

Response samples

  • 200 success

Copy 
"{
  "success": false,
  "message": "Batch already active"
}
"

Change batch state

Changes the state of a batch.

Parameters
path Parameters ?
projectId
string Required
batchId
string Required
Request Body

state
string Required

New state for the batch. Allowed values are

'Cancelled' - Allowed only if the batch is not started

Responses

200 Returns success with value true/false and a message.
Response Schema
success
boolean Required
message
string
put
/api/batch/{batchId}/state

Server URL

https://preprod.taskmonk.io/api/batch/{batchId}/state
Request samples
Copy 
"{
  "state": "CANCELLED"
}
"

Response samples

  • 200 Returns success with value true/false and a message.

Copy 
"{
  "success": false,
  "message": "Batch already active"
}
"

Query batches

Query for batches matching the criteria

Parameters
path Parameters ?
projectId
object Required
query Parameters ?
start_batch
string

Batches with ids greater than start_batch are retrieved. This is not inclusive. If not specified, all batches from the beginning are matched.

end_batch
string

Batches with ids lesser than end_batch are retrieved. This is not inclusive If not specified, all batches till the end are matched.

start_create_time
string <date>

Batches with creation time greater than start_create_time are retrieved. This is not inclusive If not specified, all batches from the beginning are matched. Format is "dd-MM-yyyy"

end_create_time
string <date>

Batches with creation time lesser than end_create_time are retrieved. This is not inclusive If not specified, all batches till the end are matched. Format is "dd-MM-yyyy"

page_size
integer <int32>

The number of batches to be retrieved. The default is 20.

page_number
integer <int32>

The page number for the retrieval starting with 0 offset. By default the first page is retrieved

Responses

200 sequence of batches
Response Schema
items
BatchDetail Required
page
integer <int32> Required

The page number of the batch results returned. This will match the request
page_size
integer <int64>

The number of batches returned in api. This will match the request
total
integer <int64> Required

The total number of batches the query matched
get
/api/project/{project_id}/batch/query

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/batch/query

Response samples

  • 200 sequence of batches

Copy Expand all Collapse all 
{
  • "items": 
    [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Query projects and batches

Query for projects and batches matching the date range of transactions

Parameters
path Parameters ?
org_id
object Required
query Parameters ?
start_date
string <date>

Projects and batches with submission date greater than start_date are retrieved. If not specified, all batches from the beginning are matched. Format is "yyyy-mm-dd"

end_date
string <date>

Projects and batches with submission date lesser than end_date are retrieved. If not specified, all batches till the end are matched. Format is "yyyy-mm-dd"

batch_state
string

Retrieve batches with provided state only. If not specified, all batches irrespective of their current state are matched.

Responses

200 sequence of project and its batches
Response Schema
project
ProjectDetail Required
batches
ProjectBatchDetail Required
get
/api/organization/{org_id}/projectsandbatches

Server URL

https://preprod.taskmonk.io/api/organization/{org_id}/projectsandbatches

Response samples

  • 200 sequence of project and its batches

Copy Expand all Collapse all 
[
  • {
    }
]

taxonomy

Get taxonomy

Get taxonomy detail

Parameters
path Parameters ?
project_id
string Required
taxonomy_id
string Required
query Parameters ?
file_type
string Required

Responses

200 success
Response Schema
taxonomy
Taxonomy Required
categories
TaxonomyCategory Required
get
/api/project/v2/{project_id}/taxonomy/{taxonomy_id}

Server URL

https://preprod.taskmonk.io/api/project/v2/{project_id}/taxonomy/{taxonomy_id}

Response samples

  • 200 success

Copy Expand all Collapse all 
{
  • "taxonomy": 
    {
    },
  • "categories": 
    [
    ]
}

Create new taxonomy

Creates a new taxonomy

Parameters
path Parameters ?
project_id
string Required
Request Body

name
string Required

Name of the new taxonomy

Responses

201 Returns the taxonomy id
Response Schema
post
/api/project/{project_id}/taxonomy

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/taxonomy
Request samples
Copy Expand all Collapse all 
{
  • "name": "string"
}

Response samples

  • 201 Returns the taxonomy id

Copy Expand all Collapse all 
{
  • "id": "string"
}

Import Taxonomy

Imports the categories for the taxonomy. Uses multipart form-data with the taxonomy file uploaded with the key 'file'.

Parameters
path Parameters ?
project_id
string Required
taxonomy_id
string Required
query Parameters ?
file_type
string

Specifies the file type of the content attached. Current options are 'CSV' or 'Excel'. Defaults to 'Excel'

Responses

201 Imported taxonomy categories
post
/api/project/v2/{project_id}/taxonomy/{taxonomy_id}/import

Server URL

https://preprod.taskmonk.io/api/project/v2/{project_id}/taxonomy/{taxonomy_id}/import

Task Upload

Import Tasks from File

Imports tasks from attached file. This is used to upload tasks from a local CSV/Excel file. The contents of the file forms the body of the request.

Parameters
path Parameters ?
project_id
string Required
batch_id
string Required

Batch to upload the tasks to

query Parameters ?
fileType
string Required

Specifies the file type of the content attached. Current options are 'CSV' or 'Excel'

Responses

200 Returns the job_id
Response Schema
job_id
string Required

The job id for the upload tasks. Can be used to track the progress of the upload.

401 User is not authorised

404 Project does not exist
post
/api/project/{project_id}/import/tasks/batch/{batch_id}

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/import/tasks/batch/{batch_id}

Response samples

  • 200 Returns the job_id

Copy Expand all Collapse all 
{
  • "job_id": "string"
}

Import Tasks from a dictionary

Imports tasks from a dictionary of key value pairs in the body

The content can be compressed using gzip. The header "Content-Encoding" should be set to gzip in this case.

Parameters
path Parameters ?
batch_id
string Required

Batch to upload the tasks to

Request Body

array of key value pairs


external_id
string

The external id that was set for the task when importing. This is optional and may not be set
batch_id
string

The batch id for the task. This is optional and might not be present when batch id is known
data
object

The input and output fields and values for the task

Responses

200 Returns the list of task ids created

401 User is not authorised

404 Project does not exist
post
/api/batch/{batch_id}/tasks/import/dictionary

Server URL

https://preprod.taskmonk.io/api/batch/{batch_id}/tasks/import/dictionary
Request samples
Copy 
"[
  {
    "external_id": "item1",
    "batch_id": "batch1",
    "data": {
      "field1": "value1",
      "field2": "value2",
    }
   },
  {
    "external_id": "item2",
    "batch_id": "batch1",
    "data": {
      "field1": "value1",
      "field2": "value2",
    }
   },
]
"

Import Tasks from Url

Imports tasks from a publicly accessible url.

Parameters
path Parameters ?
project_id
string Required
batch_id
string Required

Batch to upload the tasks to

query Parameters ?
file_url
string Required

Path to publicly accessible file

file_type
string Required

Specifies the file type of the content attached. Current options are 'CSV' or 'Excel'

Responses

200 Returns the job_id
Response Schema
job_id
string Required

The job id for the upload tasks. Can be used to track the progress of the upload.

401 User is not authorised

404 Project does not exist
post
/api/batch/{batch_id}/tasks/import/url

Server URL

https://preprod.taskmonk.io/api/batch/{batch_id}/tasks/import/url

Response samples

  • 200 Returns the job_id

Copy Expand all Collapse all 
{
  • "job_id": "string"
}

Import Tasks from source

Imports tasks from customers data source. This could be from cloud storage or jdbc connection.

Parameters
path Parameters ?
project_id
string Required
batch_id
string Required

Batch to upload the tasks to

Request Body

Input data for tasks from source


source_type
string
"Azure" "S3" "Google Cloud Storage" "JDBC"

The type of source. Could be one of 'Azure', 'S3', 'Firebase', 'JDBC'
access_info
dictionary

Key value representation of access info for the source. The keys depend on the type of source

  • S3
    • bucket_name
    • client_id
    • access_key
  • Azure
    • storage_account
    • folder_path
    • conn_info
  • JDBC
    • connection_url
    • source_query
refresh_interval
integer
0

Time to wait in seconds before refreshing tasks. A value of 0 indicates that tasks are read only once

Responses

200 Returns the job_id
Response Schema
job_id
string Required

The job id for the upload tasks. Can be used to track the progress of the upload.

401 User is not authorised

404 Project does not exist
post
/api/batch/{batch_id}/tasks/import/source

Server URL

https://preprod.taskmonk.io/api/batch/{batch_id}/tasks/import/source
Request samples
Copy Expand all Collapse all 
{
  • "source_type": "Azure",
  • "access_info": null,
  • "refresh_interval": 0
}

Response samples

  • 200 Returns the job_id

Copy Expand all Collapse all 
{
  • "job_id": "string"
}

Add a new task to a batch

Adds a new task to an existing batch

Parameters
path Parameters ?
project_id
string Required
batch_id
string Required
Request Body

id
string Required
externalId
string Required
project_id
string Required
batch_id
string Required
next_level
integer <integer> Required
status
integer <integer> Required
input
object Required
output
LevelUserOutput Required
unique_field_value
string
error
task.ErrorLevels
lastModifiedTime
string <date>
pendingUsers
integer <integer> Required
pendingCompletion
integer <integer> Required
metaData
object Required
sortField
integer <int32>

Responses

200 Id of the newly created task
Response Schema
id
string Required
post
/api/batch/{batch_id}/task

Server URL

https://preprod.taskmonk.io/api/batch/{batch_id}/task
Request samples
Copy Expand all Collapse all 
{
  • "id": "string",
  • "externalId": "string",
  • "project_id": "string",
  • "batch_id": "string",
  • "next_level": 0,
  • "status": 0,
  • "input": { },
  • "output": 
    [
    ],
  • "unique_field_value": "string",
  • "error": 
    {
    },
  • "lastModifiedTime": "2025-04-06",
  • "pendingUsers": 0,
  • "pendingCompletion": 0,
  • "metaData": { },
  • "sortField": 0
}

Response samples

  • 200 Id of the newly created task

Copy Expand all Collapse all 
{
  • "id": "string"
}

Status

Get Job Progress

Returns progress of the job

Parameters
path Parameters ?
job_id
string Required

The job_id from a previous upload call

Responses

200 success
Response Schema
completed
integer <int32> Required

The tasks that have been uploaded to TaskMonk
total
integer <int32> Required

The total tasks contained in the import job
error_msg
string

Will contain appropriate error message if upload of tasks fails for some reason
get
/api/project/job/{job_id}/status

Server URL

https://preprod.taskmonk.io/api/project/job/{job_id}/status

Response samples

  • 200 success

Copy Expand all Collapse all 
{
  • "completed": 0,
  • "total": 0,
  • "error_msg": "string"
}

Get status of a batch

Retrieves status for the batch id

Parameters
path Parameters ?
batchId
string Required

Responses

200 success
Response Schema
in_progress
integer <int32> Required
completed
integer <int32> Required
total
integer <int32> Required
eta
string

Specifies an estimate of when the batch is expected to be completed by the Annotation Partner. This is optional and depends on the capacity of the annotation partner being set. This can also be udpdated manually by the Annotation Partner The format is "YYYY-MM-DD"
eta_type
string

Can be one of

"Calculated" - If the eta is an approximate value that is calculated based on partner capacity

"Manual" - If the eta has been set by the partner
state
string Required

Returns a state for the batch. The supported state are:

"Active" - The batch is being worked on by the analysts

"Pending" - Work has not started on the batch

"Scheduled" - A start time for the batch has been set and will be worked on after that date

"Cancelled" - The execution of the batch has been cancelled by the customer
get
/api/batch/{batchId}/status

Server URL

https://preprod.taskmonk.io/api/batch/{batchId}/status

Response samples

  • 200 success

Copy Expand all Collapse all 
{
  • "in_progress": 0,
  • "completed": 0,
  • "total": 0,
  • "eta": "string",
  • "eta_type": "string",
  • "state": "string"
}

Export Data

Get output of a batch.

Retrieves output for the batch id This should be called once Batch Status API indicates that all tasks have been processed

Parameters
path Parameters ?
project_id
string Required
batch_id
string Required
query Parameters ?
output_format
string

Specifies the format for the output file. Options are 'CSV' or 'Excel'

Request Body

field_names
string Required

The fields that should be included in the output file. The names should match the project configuration and the headers in the input file that was used for the task upload. Pass an empty string to retrieve all fields

Responses

200 success
Response Schema
file_url
string Required

The path where the output file will be uploaded
job_id
string Required

The job_id for the upload of the output file. file_url will be valid once the status of this job shows as completed
post
/api/project/v2/{project_id}/batch/{batch_id}/output

Server URL

https://preprod.taskmonk.io/api/project/v2/{project_id}/batch/{batch_id}/output
Request samples
Copy Expand all Collapse all 
{
  • "field_names": 
    [
    ]
}

Response samples

  • 200 success

Copy Expand all Collapse all 
{
  • "file_url": "string",
  • "job_id": "string"
}

Get output of a batch in dictionary format.

Retrieves output for the batch id This should be called once Batch Status API indicates that all tasks have been processed

The content may be compressed using gzip. The header "Content-Encoding" will be set in this case.

Parameters
path Parameters ?
batch_id
string Required
query Parameters ?
start_task
string

Tasks with external ids greater than end_batch are retrieved. This is not inclusive If not specified, all tasks from the beginning of the batch are matched

end_task
string

Tasks with external ids lesser than end_batch are retrieved. This is not inclusive If not specified, all tasks till the end are matched.

task_complete_start
string

Tasks with completion time greater than task_complete_start are retrieved. This is not inclusive If not specified, all tasks from the beginning of the batch are matched. Format is "dd-MM-yyyy"

task_complete_end
string

Tasks with completion time lesser than task_complete_end are retrieved. This is not inclusive If not specified, all tasks till the end are matched. Format is "dd-MM-yyyy"

task_state
string

Tasks with particular state are returned. Allowed values are 'COMPLETED', 'PENDING'

page_size
integer <int32>

The number of batches to be retrieved. The default is 20.

page_number
integer <int32>

The page number for the retrieval starting with 0 offset. By default the first page is retrieved

field_names
Comma Separated string

Optional list of fields to be included in the output. If none are specified, all fields are returned.

Responses

200 Page with list of key value pairs of the fields specified for the tasks in the batch
Response Schema
items
ExternalTask Required
page
integer <int32> Required

The page number of the task results returned. This will match the request
page_size
integer <int64>

The number of task returned in api. This will match the request
total
integer <int64> Required

The total number of tasks the query matched
post
/api/batch/{batch_id}/output/dictionary

Server URL

https://preprod.taskmonk.io/api/batch/{batch_id}/output/dictionary

Response samples

  • 200 Page with list of key value pairs of the fields specified for the tasks in the batch

Copy Expand all Collapse all 
{
  • "items": 
    [
    ],
  • "page": 0,
  • "page_size": 0,
  • "total": 0
}

Get output of a project.

Retrieves output for the project id This should be called with a date range of maximum 30 days

Parameters
path Parameters ?
project_id
string Required
query Parameters ?
output_format
string

Specifies the format for the output file. Options are 'CSV' or 'Excel'

Request Body

start_time
string <date>

All the tasks submitted after this date will be exported. Sample format "2024-10-05 09:36:00"
end_time
string <date>

All the tasks submitted before this date will be exported. Sample format "2024-10-06 09:36:00" Should not be more than 30 days from start time.
field_names
string

The fields that should be included in the output file. The names should match the project configuration and the headers in the input file that was used for the task upload. Pass an empty string to retrieve all fields

Responses

200 success
Response Schema
file_url
string Required

The path where the output file will be uploaded
job_id
string Required

The job_id for the upload of the output file. file_url will be valid once the status of this job shows as completed
post
/api/project/{project_id}/output/file

Server URL

https://preprod.taskmonk.io/api/project/{project_id}/output/file
Request samples
Copy Expand all Collapse all 
{
  • "start_time": "2025-04-06",
  • "end_time": "2025-04-06",
  • "field_names": 
    [
    ]
}

Response samples

  • 200 success

Copy Expand all Collapse all 
{
  • "file_url": "string",
  • "job_id": "string"
}