OCS TaskProcessing API

New in version 30.0.0.

The OCS Text processing API allows you to run text processing tasks, like prompting large language models implemented by apps using the backend Text Processing API.

The base URL for all calls to this API is: <nextcloud_base_url>/ocs/v2.php/taskprocessing/

All calls to OCS endpoints require the OCS-APIRequest header to be set to true.

Get available task types

New in version 30.0.0.

Method: GET
Endpoint: /tasktypes
Response:
- Status code:
  
  200 OK
- Data:

field	type	Description
`types`	array	A map of supported task types. The keys are the task type IDs See below for the values.

Task type fields:

field	type	Description
`name`	string	The name of the task type in the user’s language
`description`	string	A description of the task type in the user’s language
`inputShape`	array	The input shape of this task type
`outputShape`	array	The output shape of this task type

Input and output shape fields are maps from slot key to slot metadata:

field	type	Description
`name`	string	The name of the I/O slot
`description`	string	A description of the I/O slot
`type`	int	The I/O slot type (See backend API for the available types)
`mandatory`	bool	Whether this slot is mandatory or not

Schedule a task

New in version 30.0.0.

Note

The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5

Method: POST
Endpoint: /schedule
Data:

field	type	Description
`input`	array \| The input text for the task
`type`	string	Id of this task’s type.
`appId`	string	The id of the requesting app
`customId` \| string \| An custom app-defined identifier for the task (optional)

Response:
- Status code:
  
  200 OK
  
  400 Bad Request - When the task type is invalid
  
  412 Precondition Failed - When the task type is not available currently
  
  401 Unauthenticated - When the input references a file that the user doesn’t have access to
  
  429 Too Many Requests - When the rate limiting was exceeded
- Data:
  
  input - Only provided in case of 200 OK, the task input, array
  
  type - Only provided in case of 200 OK, the task type, string
  
  id - Only provided in case of 200 OK, the assigned task id, int
  
  status - Only provided in case of 200 OK, the current task status, int, see backend API
  
  userId - Only provided in case of 200 OK, the originating userId of the task, string
  
  appId - Only provided in case of 200 OK, the originating appId of the task, string
  
  customId - Only provided in case of 200 OK, the custom id of the task, string
  
  output - Only provided in case of 200 OK, null
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Fetch a task by ID

New in version 30.0.0.

Note

The endpoint is rate limited as it can be quite resource intensive. Users can make 20 requests in 2 minutes, guests only 5

Method: POST
Endpoint: /task/{id}
Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
  
  input - Only provided in case of 200 OK, the task input, array
  
  type - Only provided in case of 200 OK, the task type, string
  
  id - Only provided in case of 200 OK, the assigned task id, int
  
  status - Only provided in case of 200 OK, the current task status, int, see backend API
  
  userId - Only provided in case of 200 OK, the originating userId of the task, string
  
  appId - Only provided in case of 200 OK, the originating appId of the task, string
  
  customId - Only provided in case of 200 OK, the custom id of the task, string
  
  output - Only provided in case of 200 OK, the output from the model, array or null
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Cancel a task

New in version 30.0.0.

Method: POST
Endpoint: /task/{id}/cancel
Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
- Data:
  
  input - Only provided in case of 200 OK, the task input, array
  
  type - Only provided in case of 200 OK, the task type, string
  
  id - Only provided in case of 200 OK, the assigned task id, int
  
  status - Only provided in case of 200 OK, the current task status, int, see backend API
  
  userId - Only provided in case of 200 OK, the originating userId of the task, string
  
  appId - Only provided in case of 200 OK, the originating appId of the task, string
  
  customId - Only provided in case of 200 OK, the custom id of the task, string
  
  output - Only provided in case of 200 OK, the output from the model, array or null
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Delete a task

New in version 30.0.0.

Method: DELETE
Endpoint: /task/{id}
Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Get task file contents

New in version 30.0.0.

Method: GET
Endpoint: /task/{id}/file/{fileId}
Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
  
  If 200 OK this endpoint returns the raw data of the file
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Set task progress

New in version 30.0.0.

Method: GET
Endpoint: /task/{id}/progress
Data:

field	type	Description
`progress`	float	A number between 0-1 indicating the task progress

Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
- Data:
  
  input - Only provided in case of 200 OK, the task input, array
  
  type - Only provided in case of 200 OK, the task type, string
  
  id - Only provided in case of 200 OK, the assigned task id, int
  
  status - Only provided in case of 200 OK, the current task status, int, see backend API
  
  userId - Only provided in case of 200 OK, the originating userId of the task, string
  
  appId - Only provided in case of 200 OK, the originating appId of the task, string
  
  customId - Only provided in case of 200 OK, the custom id of the task, string
  
  output - Only provided in case of 200 OK, the output from the model, array or null
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed

Set task result

New in version 30.0.0.

Method: POST
Endpoint: /task/{id}/result
Data:

field	type	Description
`output`	array	The task output if the task was successful (optional)
`errorMessage`	string	The error message if the task failed (optional)

Response:
- Status code:
  
  200 OK
  
  404 Not Found - When the task could not be found
- Data:
- Data:
  
  input - Only provided in case of 200 OK, the task input, array
  
  type - Only provided in case of 200 OK, the task type, string
  
  id - Only provided in case of 200 OK, the assigned task id, int
  
  status - Only provided in case of 200 OK, the current task status, int, see backend API
  
  userId - Only provided in case of 200 OK, the originating userId of the task, string
  
  appId - Only provided in case of 200 OK, the originating appId of the task, string
  
  customId - Only provided in case of 200 OK, the custom id of the task, string
  
  output - Only provided in case of 200 OK, the output from the model, array or null
  
  message - Only provided when not 200 OK, an error message in the user’s language, ready to be displayed