> For the complete documentation index, see [llms.txt](https://docs.imerit.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.imerit.net/api/docs/tasks.md).
# Tasks
Task and annotation management
## Get Project Tasks
> Retrieves all tasks for a specific project with optional filtering
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"parameters":{"ProjectIdParam":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project ID"},"PageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1},"description":"Page number (1-indexed). Sending it without `limit` sets the page size to 10. Without it no rows are skipped."},"LimitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1},"description":"Items per page. Not capped by the server. Without it and without `page`, every matching row is returned; `listProjects` is the exception, see its own description."}},"schemas":{"TaskListResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/LabelTask"}},"total":{"type":"integer"}}}}},"LabelTask":{"type":"object","properties":{"_id":{"type":"string"},"project":{"type":"string"},"asset":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Asset"}],"description":"Populated Asset object on list/detail responses; id string on annotate/review responses."},"stage":{"type":"string"},"status":{"type":"string"},"assignee":{"type":"string"},"externalId":{"type":"string"},"batches":{"type":"array","items":{"type":"string"}},"priority":{"type":"number"},"answer":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/project/{projectId}/tasks":{"get":{"tags":["Tasks"],"summary":"Get Project Tasks","description":"Retrieves all tasks for a specific project with optional filtering","operationId":"getProjectTasks","parameters":[{"$ref":"#/components/parameters/ProjectIdParam"},{"$ref":"#/components/parameters/PageParam"},{"$ref":"#/components/parameters/LimitParam"},{"name":"filter","in":"query","schema":{"type":"string"},"description":"JSON stringified filter object (MongoDB-style query)"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by task status"},{"name":"stage","in":"query","schema":{"type":"string"},"description":"Filter by stage ID"},{"name":"assignee","in":"query","schema":{"type":"string"},"description":"Filter by assignee email"},{"name":"batches","in":"query","schema":{"type":"string"},"description":"Filter by a single batch id, or a JSON array string of batch ids (e.g. [\"id1\",\"id2\"])"}],"responses":{"200":{"description":"Tasks retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```
## Requeue Tasks
> Move tasks from one stage to another based on filter criteria
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"parameters":{"ProjectIdParam":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project ID"}},"schemas":{"RequeueTasksRequest":{"type":"object","required":["toStageId","filters"],"properties":{"toStageId":{"type":"string","description":"Destination stage ID"},"filters":{"$ref":"#/components/schemas/TaskFilters"},"options":{"type":"object","description":"Options for task requeue operation","properties":{"removeAnnotations":{"type":"boolean","description":"Remove existing annotations when requeuing","default":false},"removeAssignee":{"type":"boolean","description":"Remove task assignee when requeuing","default":false},"removeStageHistory":{"type":"boolean","description":"Remove stage history when requeuing","default":false}}}}},"TaskFilters":{"type":"object","description":"Filter criteria for task operations","properties":{"taskIds":{"type":"array","items":{"type":"string"},"description":"Array of task IDs"},"externalIds":{"type":"array","items":{"type":"string"},"description":"Array of external IDs"},"assetIds":{"type":"array","items":{"type":"string"},"description":"Array of asset IDs"},"fromStageIds":{"type":"array","items":{"type":"string"},"description":"Array of source stage IDs"},"batches":{"type":"array","items":{"type":"string"},"description":"Array of batch IDs"}}},"RequeueResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"modifiedCount":{"type":"integer"}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/project/{projectId}/requeueTasks":{"post":{"tags":["Tasks"],"summary":"Requeue Tasks","description":"Move tasks from one stage to another based on filter criteria","operationId":"requeueTasks","parameters":[{"$ref":"#/components/parameters/ProjectIdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequeueTasksRequest"}}}},"responses":{"200":{"description":"Tasks requeued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequeueResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```
## Update Task Priority
> Update priority for multiple tasks based on filter criteria
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"parameters":{"ProjectIdParam":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project ID"}},"schemas":{"UpdatePriorityRequest":{"type":"object","required":["priority","filters"],"properties":{"priority":{"type":"number","minimum":-1000,"maximum":1000,"description":"Priority value (-1000 to 1000)"},"filters":{"$ref":"#/components/schemas/TaskFilters"},"options":{"type":"object"}}},"TaskFilters":{"type":"object","description":"Filter criteria for task operations","properties":{"taskIds":{"type":"array","items":{"type":"string"},"description":"Array of task IDs"},"externalIds":{"type":"array","items":{"type":"string"},"description":"Array of external IDs"},"assetIds":{"type":"array","items":{"type":"string"},"description":"Array of asset IDs"},"fromStageIds":{"type":"array","items":{"type":"string"},"description":"Array of source stage IDs"},"batches":{"type":"array","items":{"type":"string"},"description":"Array of batch IDs"}}},"PriorityUpdateResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"result":{"type":"object","properties":{"modifiedCount":{"type":"integer"},"priority":{"type":"number"}}}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/project/{projectId}/updatePriority":{"post":{"tags":["Tasks"],"summary":"Update Task Priority","description":"Update priority for multiple tasks based on filter criteria","operationId":"updatePriority","parameters":[{"$ref":"#/components/parameters/ProjectIdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePriorityRequest"}}}},"responses":{"200":{"description":"Priority updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriorityUpdateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```
## Set Benchmark Tasks
> Turns tasks into benchmark tasks, or turns them back. Only tasks currently in the opposite state are touched, and tasks that are themselves benchmark or consensus copies are skipped, so the returned count can be lower than what you sent. Every task it does touch is moved to the Complete stage, loses its assignee, has its running durations folded into the totals and is dropped from the work queues. With \`isBenchmark\` true, one benchmark copy is created for every project member (each assignee plus the owner) on every task, so the number of new tasks is tasks times members; with false the existing copies are deleted. Task IDs that belong to another project, or that are already deleted, are skipped as well. Any field outside \`tasks\` and \`isBenchmark\` is rejected with 400.
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"parameters":{"ProjectIdParam":{"name":"projectId","in":"path","required":true,"schema":{"type":"string"},"description":"Project ID"}},"schemas":{"BenchmarkTasksRequest":{"type":"object","required":["tasks","isBenchmark"],"properties":{"tasks":{"type":"array","minItems":1,"description":"Task IDs, each a 24 character hex string","items":{"type":"string"}},"isBenchmark":{"type":"boolean","description":"True marks the tasks as benchmark, false reverts them"}}},"BenchmarkTasksResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"benchmarkTasks":{"type":"object","properties":{"isBenchmark":{"type":"boolean"},"modifiedCount":{"type":"integer","description":"Tasks actually changed, skipped ones are not counted"},"tasks":{"type":"array","description":"IDs of the tasks that were changed","items":{"type":"string"}}}}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized - invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/project/{projectId}/benchmark-tasks":{"post":{"tags":["Tasks"],"summary":"Set Benchmark Tasks","description":"Turns tasks into benchmark tasks, or turns them back. Only tasks currently in the opposite state are touched, and tasks that are themselves benchmark or consensus copies are skipped, so the returned count can be lower than what you sent. Every task it does touch is moved to the Complete stage, loses its assignee, has its running durations folded into the totals and is dropped from the work queues. With `isBenchmark` true, one benchmark copy is created for every project member (each assignee plus the owner) on every task, so the number of new tasks is tasks times members; with false the existing copies are deleted. Task IDs that belong to another project, or that are already deleted, are skipped as well. Any field outside `tasks` and `isBenchmark` is rejected with 400.","operationId":"setBenchmarkTasks","parameters":[{"$ref":"#/components/parameters/ProjectIdParam"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkTasksRequest"}}}},"responses":{"200":{"description":"Benchmark flag applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BenchmarkTasksResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```
## Get Task Details
> Retrieves detailed information about a specific task
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"TaskResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/LabelTask"}}}}},"LabelTask":{"type":"object","properties":{"_id":{"type":"string"},"project":{"type":"string"},"asset":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Asset"}],"description":"Populated Asset object on list/detail responses; id string on annotate/review responses."},"stage":{"type":"string"},"status":{"type":"string"},"assignee":{"type":"string"},"externalId":{"type":"string"},"batches":{"type":"array","items":{"type":"string"}},"priority":{"type":"number"},"answer":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/task/{taskId}":{"get":{"tags":["Tasks"],"summary":"Get Task Details","description":"Retrieves detailed information about a specific task","operationId":"getTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"}],"responses":{"200":{"description":"Task retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```
## Get Task History
> Retrieves the complete history of changes for a task
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"TaskHistoryListResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"taskHistory":{"type":"array","items":{"$ref":"#/components/schemas/TaskHistory"}},"total":{"type":"integer"}}}}},"TaskHistory":{"type":"object","properties":{"_id":{"type":"string"},"labelTaskId":{"type":"string","description":"Reference to the label task"},"project":{"type":"string"},"organization":{"type":"string"},"asset":{"$ref":"#/components/schemas/Asset"},"stage":{"type":"string"},"assignee":{"type":"string"},"prevAssignee":{"type":"string"},"reviewStatus":{"type":"string","enum":["Accepted","Rejected"]},"rework":{"type":"boolean"},"isSkipped":{"type":"boolean"},"type":{"type":"string"},"answer":{"type":"object"},"duration":{"type":"number"},"idleDuration":{"type":"number"},"blurDuration":{"type":"number"},"batches":{"type":"array","items":{"type":"string"}},"consensusAverage":{"type":"number"},"consensusDetailed":{"type":"array","items":{"type":"object"}},"consensusIteration":{"type":"integer"},"benchmarkAverage":{"type":"number"},"benchmarkDetailed":{"type":"array","items":{"type":"object"}},"brushDataUrl":{"type":"string"},"medicalBrushDataUrl":{"type":"string"},"rootStageId":{"type":"string"},"deleted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"updatedBy":{"type":"string"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}}}},"paths":{"/task/{taskId}/history":{"get":{"tags":["Tasks"],"summary":"Get Task History","description":"Retrieves the complete history of changes for a task","operationId":"getTaskHistory","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"},{"name":"populateAnswer","in":"query","schema":{"type":"string","enum":["true","false"],"default":"true"},"description":"Include the annotation answer in each history entry (default true; set \"false\" to strip)"}],"responses":{"200":{"description":"Task history retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskHistoryListResponse"}}}}}}}}}
```
## Get Task History Entry
> Retrieves a specific task history entry by ID
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"TaskHistoryResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"taskHistory":{"$ref":"#/components/schemas/TaskHistory"}}}}},"TaskHistory":{"type":"object","properties":{"_id":{"type":"string"},"labelTaskId":{"type":"string","description":"Reference to the label task"},"project":{"type":"string"},"organization":{"type":"string"},"asset":{"$ref":"#/components/schemas/Asset"},"stage":{"type":"string"},"assignee":{"type":"string"},"prevAssignee":{"type":"string"},"reviewStatus":{"type":"string","enum":["Accepted","Rejected"]},"rework":{"type":"boolean"},"isSkipped":{"type":"boolean"},"type":{"type":"string"},"answer":{"type":"object"},"duration":{"type":"number"},"idleDuration":{"type":"number"},"blurDuration":{"type":"number"},"batches":{"type":"array","items":{"type":"string"}},"consensusAverage":{"type":"number"},"consensusDetailed":{"type":"array","items":{"type":"object"}},"consensusIteration":{"type":"integer"},"benchmarkAverage":{"type":"number"},"benchmarkDetailed":{"type":"array","items":{"type":"object"}},"brushDataUrl":{"type":"string"},"medicalBrushDataUrl":{"type":"string"},"rootStageId":{"type":"string"},"deleted":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"updatedBy":{"type":"string"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}}}},"paths":{"/taskHistory/{taskHistoryId}":{"get":{"tags":["Tasks"],"summary":"Get Task History Entry","description":"Retrieves a specific task history entry by ID","operationId":"getTaskHistoryEntry","parameters":[{"name":"taskHistoryId","in":"path","required":true,"schema":{"type":"string"},"description":"Task history entry ID"},{"name":"populateAnswer","in":"query","schema":{"type":"string","enum":["true","false"],"default":"true"},"description":"Include the annotation answer in the entry (default true; set \"false\" to strip)"}],"responses":{"200":{"description":"Task history entry retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskHistoryResponse"}}}}}}}}}
```
## Assign Tasks to User
> Assigns one or more tasks to a specific user at a specific stage
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"TaskAssignRequest":{"type":"object","required":["user","project","tasks","stage"],"properties":{"user":{"type":"string","description":"User email to assign to"},"project":{"type":"string","description":"Project ID"},"tasks":{"type":"array","items":{"type":"string"},"description":"Array of task IDs"},"stage":{"type":"string","description":"Stage ID"}}},"TaskAssignResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"task":{"type":"object","properties":{"updatedCount":{"type":"integer"},"assignedTasks":{"type":"object","properties":{"count":{"type":"integer"}}},"message":{"type":"string"}}}}}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}},"responses":{"BadRequestError":{"description":"Bad request - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/task/assign":{"post":{"tags":["Tasks"],"summary":"Assign Tasks to User","description":"Assigns one or more tasks to a specific user at a specific stage","operationId":"assignTask","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAssignRequest"}}}},"responses":{"200":{"description":"Tasks assigned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAssignResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"}}}}}}
```
## Submit Annotation
> Submits annotation answer for a task
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"AnnotateRequest":{"type":"object","required":["answer"],"properties":{"answer":{"type":"object","description":"Annotation answer object (structure depends on project categorySchema)"}}},"LabelResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"label":{"$ref":"#/components/schemas/LabelTask"}}}}},"LabelTask":{"type":"object","properties":{"_id":{"type":"string"},"project":{"type":"string"},"asset":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Asset"}],"description":"Populated Asset object on list/detail responses; id string on annotate/review responses."},"stage":{"type":"string"},"status":{"type":"string"},"assignee":{"type":"string"},"externalId":{"type":"string"},"batches":{"type":"array","items":{"type":"string"}},"priority":{"type":"number"},"answer":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}}}},"paths":{"/annotate/{taskId}":{"post":{"tags":["Tasks"],"summary":"Submit Annotation","description":"Submits annotation answer for a task","operationId":"annotateTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"},{"name":"isPlugin","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Set to 'true' if annotation from plugin"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotateRequest"}}}},"responses":{"200":{"description":"Annotation submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelResponse"}}}}}}}}}
```
## Submit Review Decision
> Submits a review decision (accept/reject) for a task in a Review stage.\
> \
> This endpoint is used to submit review decisions for tasks that are currently in a Review stage\
> of the workflow. When a review decision is submitted, the task automatically advances to the\
> next stage in the workflow.\
> \
> \*\*Important\*\*: The task must be in a Review stage. Use \`/annotate/{taskId}\` for Label stages.
```json
{"openapi":"3.0.3","info":{"title":"Ango Hub API v2","version":"2.0.0"},"tags":[{"name":"Tasks","description":"Task and annotation management"}],"servers":[{"url":"https://imeritapi.ango.ai/v2","description":"EU Production Server"},{"url":"https://us-api.ango.ai/v2","description":"US Production Server"},{"url":"https://in-api.ango.ai/v2","description":"India Production Server"},{"url":"https://testapi.ango.ai/v2","description":"Test Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"apikey","description":"API key for authentication. Format - apikey YOUR_API_KEY"}},"schemas":{"ReviewRequest":{"type":"object","required":["reviewStatus"],"properties":{"reviewStatus":{"type":"string","enum":["Accepted","Rejected"],"description":"Review decision for the task.\n- `Accepted`: Approve the task and move it to the next stage\n- `Rejected`: Reject the task (typically sends it back for correction)\n"},"answer":{"type":"object","description":"Optional annotation modifications (structure depends on project categorySchema)"},"duration":{"type":"number","description":"Time spent reviewing in seconds"},"idleDuration":{"type":"number","description":"Idle time during review in seconds"},"blurDuration":{"type":"number","description":"Time window was blurred/unfocused in seconds"}}},"LabelResponse":{"type":"object","properties":{"status":{"type":"string"},"data":{"type":"object","properties":{"label":{"$ref":"#/components/schemas/LabelTask"}}}}},"LabelTask":{"type":"object","properties":{"_id":{"type":"string"},"project":{"type":"string"},"asset":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/Asset"}],"description":"Populated Asset object on list/detail responses; id string on annotate/review responses."},"stage":{"type":"string"},"status":{"type":"string"},"assignee":{"type":"string"},"externalId":{"type":"string"},"batches":{"type":"array","items":{"type":"string"}},"priority":{"type":"number"},"answer":{"type":"object"},"createdAt":{"type":"string","format":"date-time"},"duration":{"type":"number","description":"Duration in seconds"}}},"Asset":{"type":"object","description":"When an asset is private, carries a `storage`, or is NRRD, and its `data` is a URL, the read endpoints replace `data`, `dataset` and `overlay` with pre-signed URLs and set `head` to a signed HEAD URL. Otherwise `head` equals `data`.","properties":{"_id":{"type":"string"},"id":{"type":"string","description":"Same value as `_id`"},"data":{"type":"string","description":"Asset URL"},"dataset":{"type":"array","items":{"type":"string"}},"overlay":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}]}},"head":{"type":"string","description":"Signed HEAD URL for the asset, or the same value as `data`"},"project":{"type":"string","description":"Project ID, or the project object when `populate=project` is used"},"organization":{"type":"string"},"storage":{"type":"string","description":"Storage integration ID, null for assets in the platform bucket","nullable":true},"externalId":{"type":"string"},"editorType":{"type":"string","enum":["ango","pct","llm","nrrd","iframe"]},"uploadStatus":{"type":"string","enum":["READY","PCT_WAITING","METADATA_WAITING","PCT_FAILED","METADATA_FAILED"],"description":"An asset is READY once it can be annotated. PCT and preprocessing assets get their task only after the waiting state clears."},"isPrivate":{"type":"boolean"},"isPreLabeled":{"type":"boolean"},"batches":{"type":"array","items":{"type":"string"},"description":"Batch IDs the asset belongs to"},"metadata":{"$ref":"#/components/schemas/AssetMetadata"},"attachments":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"label":{"type":"object"}}}},"contextData":{"type":"object"},"labelTasks":{"type":"array","description":"Returned only when populated, as objects carrying `_id`, `id`, `stage` and `assignee`. The project assets list always populates it.","items":{"type":"object","properties":{"_id":{"type":"string"},"id":{"type":"string"},"stage":{"type":"string"},"assignee":{"type":"string"}}}},"deleted":{"type":"boolean","description":"Deleted assets are excluded from responses by default, so this is false"},"preprocessEnqueuedAt":{"type":"string","format":"date-time","description":"When the asset was queued for preprocessing"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"}}},"AssetMetadata":{"type":"object","description":"Technical asset metadata. Only these fields are stored; any other key is dropped on write. For a video asset, supply width, height and frameTotal to skip server-side preprocessing.","properties":{"width":{"type":"integer"},"height":{"type":"integer"},"size":{"type":"integer"},"frameStep":{"type":"integer"},"frameTotal":{"type":"integer"},"frameRate":{"type":"number"},"numOfPages":{"type":"integer"},"numOfWords":{"type":"integer"},"duration":{"type":"integer","description":"Duration in milliseconds"},"hasVariableFrameRate":{"type":"boolean"}}},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","enum":["fail","error"]},"message":{"type":"string"}}}}},"paths":{"/review/{taskId}":{"post":{"tags":["Tasks"],"summary":"Submit Review Decision","description":"Submits a review decision (accept/reject) for a task in a Review stage.\n\nThis endpoint is used to submit review decisions for tasks that are currently in a Review stage\nof the workflow. When a review decision is submitted, the task automatically advances to the\nnext stage in the workflow.\n\n**Important**: The task must be in a Review stage. Use `/annotate/{taskId}` for Label stages.\n","operationId":"reviewTask","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string"},"description":"Task ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequest"}}}},"responses":{"200":{"description":"Review submitted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelResponse"}}}},"400":{"description":"Bad request - task not in Review stage or invalid reviewStatus","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Task or stage not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.imerit.net/api/docs/tasks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.