khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 02:09:45 +07:00
Code Issues Packages Projects Releases Wiki Activity
Files
f4fd7e76cfe5d2b08695fbbe98076d69fbac336c
nextcloud-docs/developer_manual/client_apis/OCS/ocs-taskprocessing-api.rst
Marcel Klehr 5143d3eb94 feat: Add docs for \OCP\TaskProcessing 
Signed-off-by: Marcel Klehr <mklehr@gmx.net>
2024-05-08 10:11:08 +02:00

257 lines
14 KiB
ReStructuredText
Raw Blame History

.. _ocs-taskprocessing-api:
======================
OCS TaskProcessing API
======================
.. versionadded:: 30.0.0
The OCS Text processing API allows you to run text processing tasks, like prompting large language models implemented by apps using :ref:`the backend Text Processing API<text_processing>`.
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
------------------------
.. versionadded:: 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
---------------
.. versionadded:: 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
------------------
.. versionadded:: 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
-------------
.. versionadded:: 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
-------------
.. versionadded:: 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
----------------------
.. versionadded:: 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
-----------------
.. versionadded:: 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
---------------
.. versionadded:: 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
Reference in New Issue View Git Blame Copy Permalink