{"openapi":"3.0.1","info":{"title":"Tasks","description":"Tasks","contact":{"name":"Perspio","url":"https://developers.perspio.io/"},"version":"v3"},"servers":[{"url":"https://talk.perspio.io/tasks/v3","description":"AU Region"},{"url":"https://us-talk.perspio.io/tasks/v3","description":"US Region"}],"paths":{"/":{"get":{"tags":["Tasks"],"summary":"Get Tasks","description":"Fetch the tenant's tasks, filtered by status and type and a created-date range. Returns task summaries; when full=true the response is paged and returns the full task records along with the ContinuationToken, ResultCount and TotalCount headers.","operationId":"gettasks","parameters":[{"name":"full","in":"query","description":"Return full task records instead of compact summaries. When true the response body is the paged wrapper {\"key\": \"<continuation token>\", \"value\": [tasks]} (not a bare array) and the ContinuationToken/ResultCount/TotalCount response headers are returned.","schema":{"type":"boolean"},"example":"False"},{"name":"status","in":"query","description":"Filter by task status — a TaskStatusTypes name or its integer value.","schema":{"type":"string"},"example":"CompletedOK"},{"name":"type","in":"query","description":"Filter by task type — a TaskTypes name or its integer value.","schema":{"type":"string"},"example":"ImportAssets"},{"name":"from","in":"query","description":"Start of the created-date range (ISO 8601, UTC). When omitted the service default window applies.","schema":{"type":"string","format":"date-time"},"example":"2026-06-01T12:00:00.0000000+00:00"},{"name":"to","in":"query","description":"End of the created-date range (ISO 8601, UTC).","schema":{"type":"string","format":"date-time"},"example":"2026-06-30T11:59:59.0000000+00:00"},{"name":"page_size","in":"query","description":"Maximum tasks per page (applies when full=true).","schema":{"type":"integer"},"example":500},{"name":"token","in":"query","description":"Continuation token to fetch the next page. Equivalent to the ContinuationToken request header.","schema":{"type":"string"},"example":"eyJ0b2tlbiI6IjEwMDAifQ=="},{"name":"daterange","in":"query","description":"Named date range shortcut (alternative to from/to), evaluated in the supplied timezone.","schema":{"type":"string"},"example":"last7days"},{"name":"timezone","in":"query","description":"IANA timezone used to evaluate daterange. Defaults to UTC.","schema":{"type":"string"},"example":"Australia/Sydney"},{"name":"ContinuationToken","in":"header","description":"Continuation token from a previous page (used when full=true).","schema":{"type":"string"},"example":"eyJ0b2tlbiI6IjUwMCJ9"}],"responses":{"200":{"description":"OK. Array of task summaries. When full=true, the full TaskRecord items are returned, paged, with the ContinuationToken/ResultCount/TotalCount headers.","headers":{"ContinuationToken":{"description":"Opaque token to fetch the next page; pass it back via the ContinuationToken request header. Present on the paged (full=true) response.","schema":{"type":"string"},"example":"eyJ0b2tlbiI6IjEwMDAifQ=="},"ResultCount":{"description":"Number of tasks in this page (full=true response).","schema":{"type":"integer","format":"int32"},"example":25},"TotalCount":{"description":"Total tasks across all pages (full=true response).","schema":{"type":"integer","format":"int64"},"example":137}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskShortResponse"}},"example":[{"id":"in-task-cd88e1d4-706d-469b-884f-7cc17bb2e3cf","taskType":1,"taskResult":{"status":0},"createdDateUTC":"2026-06-01T08:30:00.0000000+00:00","updatedDateUTC":"2026-06-01T08:31:10.0000000+00:00","createdBy":"user@tenant.com"},{"id":"in-task-6405f3a4-ed08-497f-a430-3a9e7d25d228","taskType":2,"taskResult":{"status":3},"createdDateUTC":"2026-06-02T02:05:00.0000000+00:00","updatedDateUTC":"2026-06-02T02:20:42.0000000+00:00","createdBy":"user@tenant.com"}]}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerspioError"},"example":{"functionName":"Perspio.API.Tasks.TasksApi.GetTasks","errorType":"ArgumentException","statusCode":400,"request":"GET /api/v3/tasks","tenantId":"in-93b1a4c6-1234-4c1c-9d2a-1f2e3d4c5b6a","message":"Invalid value for TaskTypes: 99"}}}},"401":{"description":"Invalid API Key provided or Invalid Access token"},"403":{"description":"Forbidden. The caller lacks the required role for the tenant."},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerspioError"},"example":{"functionName":"Perspio.API.Tasks.TasksApi.GetTasks","errorType":"NullReferenceException","statusCode":500,"request":"GET /api/v3/tasks","tenantId":"in-93b1a4c6-1234-4c1c-9d2a-1f2e3d4c5b6a","message":"Internal Server Error: Object reference not set to an instance of an object."}}}}}},"post":{"tags":["Tasks"],"summary":"Create Task","description":"Create a task of the given type with the supplied task object. Returns the summary of the newly created task.","operationId":"createtasks","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreateRequest"},"example":{"taskType":1,"taskObject":{"scope":{"scopeType":5,"objectRefs":["in-000052"]},"patchItems":[{"value":null,"path":"metadata.hierarchy.operationalHierarchyL3","op":"replace"}]}}}}},"responses":{"200":{"description":"Created. The summary of the new task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskShortResponse"},"example":{"id":"in-task-cd88e1d4-706d-469b-884f-7cc17bb2e3cf","taskType":1,"taskResult":{"status":0},"createdDateUTC":"2026-06-01T08:30:00.0000000+00:00","updatedDateUTC":"2026-06-01T08:31:10.0000000+00:00","createdBy":"user@tenant.com"}}}},"400":{"description":"Invalid Request"},"401":{"description":"Invalid API Key provided or Invalid Access token"},"403":{"description":"Forbidden. The caller lacks the required role for the tenant."},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerspioError"},"example":{"functionName":"Perspio.API.Tasks.TasksApi.CreateTask","errorType":"NullReferenceException","statusCode":500,"request":"POST /api/v3/tasks","tenantId":"in-93b1a4c6-1234-4c1c-9d2a-1f2e3d4c5b6a","message":"Internal Server Error: Object reference not set to an instance of an object."}}}}}}},"/{id}":{"get":{"tags":["Tasks"],"summary":"Get Task","description":"Fetch a single task by id. Returns the task summary; when full=true the complete task record is returned.","operationId":"gettask","parameters":[{"name":"id","in":"path","description":"Task Id","required":true,"schema":{"type":"string","example":"in-task-2d2f61c4-efd1-4d92-b134-a5cf3ac9c6c2"}},{"name":"full","in":"query","description":"Return the full task record (all fields) instead of the compact summary.","schema":{"type":"boolean"},"example":"False"}],"responses":{"200":{"description":"OK. The task summary. When full=true the complete TaskRecord is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskShortResponse"},"example":{"id":"in-task-cd88e1d4-706d-469b-884f-7cc17bb2e3cf","taskType":1,"taskResult":{"status":0},"createdDateUTC":"2026-06-01T08:30:00.0000000+00:00","updatedDateUTC":"2026-06-01T08:31:10.0000000+00:00","createdBy":"user@tenant.com"}}}},"400":{"description":"Invalid Request"},"401":{"description":"Invalid API Key provided or Invalid Access token"},"403":{"description":"Forbidden. The caller lacks the required role for the tenant."},"404":{"description":"Resource Not Found"},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PerspioError"},"example":{"functionName":"Perspio.API.Tasks.TasksApi.GetTask","errorType":"NullReferenceException","statusCode":500,"request":"GET /api/v3/tasks/in-task-2d2f61c4-efd1-4d92-b134-a5cf3ac9c6c2","tenantId":"in-93b1a4c6-1234-4c1c-9d2a-1f2e3d4c5b6a","message":"Internal Server Error: Object reference not set to an instance of an object."}}}}}}}},"components":{"schemas":{"TaskCreateRequest":{"required":["taskType","taskObject"],"type":"object","properties":{"taskType":{"type":"integer","description":"Task type (TaskTypes enum, serialized as its integer value).","format":"int32"},"taskObject":{"type":"object","description":"The task payload; its shape depends on taskType (for an AssetUpdate task: a scope and JSON-patch items)."}},"description":"Request to create a task."},"TaskShortResponse":{"type":"object","properties":{"id":{"type":"string","description":"Task identifier.","example":"in-task-cd88e1d4-706d-469b-884f-7cc17bb2e3cf"},"taskType":{"type":"integer","description":"Task type (TaskTypes enum, serialized as its integer value).","format":"int32"},"taskResult":{"type":"object","properties":{"status":{"type":"integer","description":"Task status (TaskStatusTypes enum, serialized as its integer value).","format":"int32"}},"description":"Task result summary."},"createdDateUTC":{"type":"string","description":"UTC time the task was created.","format":"date-time"},"updatedDateUTC":{"type":"string","description":"UTC time the task was last updated.","format":"date-time"},"createdBy":{"type":"string","description":"Identity that created the task."}},"description":"Summary view of a task."},"PerspioError":{"type":"object","properties":{"functionName":{"type":"string","description":"Name of the backend function that raised the error."},"errorType":{"type":"string","description":"Exception/error type name."},"statusCode":{"type":"integer","description":"HTTP status code of the error.","format":"int32"},"request":{"type":"string","description":"Method and URL of the failing request."},"tenantId":{"type":"string","description":"Tenant the request was executed for."},"message":{"type":"string","description":"Human-readable error message."}},"description":"Standard Perspio backend error body (ErrorResultObject emitted by the error-handling middleware)."}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"Client credentials from your Perspio API application. See Get Access Token.","flows":{"clientCredentials":{"tokenUrl":"/auth/v3/token","scopes":{}}}},"subscriptionKey":{"type":"apiKey","name":"Ocp-Apim-Subscription-Key","in":"header","description":"Your tenant's subscription key, from your API application."},"tenantId":{"type":"apiKey","name":"tid","in":"header","description":"Your tenant ID (tid), from your API application."}}},"security":[{"oauth2":[],"subscriptionKey":[],"tenantId":[]}],"tags":[{"name":"Tasks","description":"Asynchronous task records — create and query."}],"x-readme":{"oauth-options":{"useInsecureClientAuthentication":true}}}