Skip to main content

Process API

This API provides endpoints for managing processes using Machine-to-Machine communication. The following documentation explains how to use the API, including detailed descriptions of each endpoint and the Data Transfer Objects (DTOs) used.

View the Public API Documentation

Authentication​

To make REST calls, you need to pass an API Key generated from the Frontend Component of entAIngine Studio. Ensure you select the correct space, as API keys are specific to each space. Note that API keys are displayed only once during generation; if you lose your key, you will need to generate a new one.

Include the API Key in the Authorization header of your request as follows:


Authorization: Bearer 0123a.abcd1234TestAPIkey

Example Request​

Here’s the adjusted code snippet using triple backticks for compatibility with MDX:

curl -X 'POST' \
  'https://api.entaingine.com/aiengine/api/v1/m2m/processes' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 0123a.abcd1234TestAPIkey' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Workflow processing",
  "processTemplate": 10001,
  "inputs": [
    {
      "name": "FILE_URL",
      "value": "www.example.com/file.pdf"
    },
    {
      "name": "JSON_TEMPLATE_DESCRIPTION",
      "value": "www.example.com/template_description.json"
    },
    {
      "name": "EXAMPLE_TEXT",
      "value": "this is my example text"
    }
  ],
  "spaceId": ".entaingine.test",
  "private": false
}'

Endpoints​

Create a Process​

Creates a new process based on the provided ProcessRequestDTO.

Endpoint: POST /api/v1/m2m/processes

{
  "description": "Data processing workflow",
  "processTemplate": 123,
  "inputs": [
    {
      "name": "input_1",
      "value": "sample_value"
    }
  ],
  "isPrivate": true,
  "spaceId": "space_123"
}

Get a Process by ID​

Retrieves the process details based on the provided ID.

Endpoint: GET /api/v1/m2m/processes/{id}

{
  "id": 1,
  "description": "Data processing workflow",
  "processOutputUrl": "http://example.com/output.mp3",
  "processOutputText": "Processing completed successfully",
  "spaceId": "space_123",
  "createdBy": "user_123",
  "processTemplate": 123,
  "errorMessage": null,
  "isPrivate": true,
  "dateCreated": "2023-01-01T10:00:00Z",
  "lastUpdated": "2023-01-01T10:00:00Z",
  "totalExecutionTime": 120000
}

Get Inputs for a Process​

Retrieves the list of inputs for the specified process ID.

Endpoint: GET /api/v1/m2m/processes/{id}/inputs

[
  {
    "id": 1,
    "name": "input_1",
    "value": "sample_value"
  }
]

Get Outputs for a Process​

Retrieves the list of outputs for the specified process ID.

Endpoint: GET /api/v1/m2m/processes/{id}/tasks/outputs

{
  "outputs": [
    {
      "id": 1,
      "taskId": 101,
      "taskPosition": 1,
      "position": 1,
      "role": "assistant",
      "outputText": "Processing completed successfully.",
      "outputUrl": "http://example.com/output.mp3",
      "chunkSimilarityMetadata": {
        "chunk1": "value1",
        "chunk2": "value2"
      },
      "executionTime": 5000
    }
  ],
  "isFailed": false,
  "totalExecutionTime": 120000
}

Data Transfer Objects (DTOs)​

This section provides detailed descriptions of the DTOs used in the Process API.

note

Understanding these objects and their fields is essential for making accurate API requests and interpreting responses.

InputDTO​

The InputDTO represents an input for a process.

  • id: Automatically generated unique identifier of the input. No need to pass it if you are creating a process. (Example: 1)
  • name: Name of the input from the input template. (Example: FILE_URL)
  • value: Value of the input. (Example: www.example.com/fileurl.pdf)

OutputDTO​

The OutputDTO represents an output generated by a process.

  • id: Unique identifier of the output. (Example: 1)
  • taskId: Identifier of the associated task. (Example: 101)
  • taskPosition: Position of the task within the process. (Example: 1)
  • position: Position of the output within the task. (Example: 1)
  • role: Role of the output within the process, e.g., assistant, user, system. (Example: assistant)
  • outputText: Text content of the output. (Example: Processing completed successfully.)
  • outputUrl: URL of the output resource if the file was supposed to be generated by the task. (Example: http://example.com/output.pdf)
  • chunkSimilarityMetadata: Metadata for chunk similarity, represented as a map of key-value pairs. (Example: {"chunk1":"value1", "chunk2":"value2"})
  • executionTime: Execution time of the task that generated the output, in milliseconds. (Example: 5000)

OutputResponseDTO​

The OutputResponseDTO represents the response containing outputs for a process.

  • outputs: List of outputs generated by the process.
  • isFailed: Indicates if the process has failed. (Example: false)
  • totalExecutionTime: Total execution time of the process in milliseconds. (Example: 120000)

ProcessDTO​

The ProcessDTO represents the data structure of a process.

  • id: Unique identifier of the process. (Example: 1001)
  • description: Description of the process. (Example: Extraction of the information from the document 1)
  • processOutputUrl: URL of the process output. If the process is supposed to generate a file (e.g., image generation or speech generation), the file URL will be in this field. (Example: http://example.com/output)
  • processOutputText: Final text output of the process. (Example: This document summarizes how entAIngine can be used for...)
  • spaceId: Space identifier associated with the process. (Example: .entaingine.test-space)
  • createdBy: Sub of the user who created the process. (Example: user_123)
  • processTemplate: Template identifier for the process. The process will be created based on this template. (Example: 10002)
  • errorMessage: Error message if the process fails. (Example: An error occurred during processing)
  • isPrivate: Indicates if the process is private or available for all users in the space. (Example: true)
  • dateCreated: Date and time when the process was created. (Example: 2023-01-01T10:00:00Z)
  • lastUpdated: Date and time when the process was last updated. (Example: 2023-01-02T10:00:00Z)

ProcessRequestDTO​

The ProcessRequestDTO represents the data structure required to create a new process.

  • description: Description of the process. (Example: Data processing workflow)
  • processTemplate: Template identifier for the process. (Example: template_123)
  • inputs: List of inputs for the process.
  • isPrivate: Indicates if the process is private or available for all users in the space. (Example: true)
  • spaceId: Space identifier associated with the process. (Example: .entaingine.test-space)

ProcessResponseDTO​

The ProcessResponseDTO extends ProcessDTO with additional fields.

  • totalExecutionTime: Total execution time of the process in milliseconds. (Example: 120000)

This detailed description of the DTOs should help you understand how to structure your API requests and interpret the responses effectively.

Error Handling​

The API returns standard HTTP status codes to indicate the success or failure of an API request. Here are some common status codes:

  • 200 OK: The request was successful.
  • 201 Created: The resource was created successfully.
  • 400 Bad Request: The request was invalid or cannot be otherwise served.
  • 401 Unauthorized: Authentication credentials were missing or incorrect.
  • 403 Forbidden: The request is understood, but it has been refused or access is not allowed.
  • 404 Not Found: The resource could not be found.
  • 500 Internal Server Error: An error occurred on the server.

Example Requests​

Create a Process​

POST /api/v1/m2m/processes HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer 0123a.abcd1234TestAPIkey

{
  "description": "Data processing workflow",
  "processTemplate": 123,
  "inputs": [
    {
      "name": "input_1",
      "value": "sample_value"
    }
  ],
  "isPrivate": true,
  "spaceId": "space_123"
}

Get a Process by ID​

GET /api/v1/m2m/processes/1 HTTP/1.1
Host: example.com
Authorization: Bearer 0123a.abcd1234TestAPIkey

Get Inputs for a Process​

GET /api/v1/m2m/processes/1/inputs HTTP/1.1
Host: example.com
Authorization: Bearer 0123a.abcd1234TestAPIkey

Get Outputs for a Process​

GET /api/v1/m2m/processes/1/tasks/outputs HTTP/1.1
Host: example.com
Authorization: Bearer 0123a.abcd1234TestAPIkey

This documentation should help you understand and utilize the M2M Process API effectively. For any further questions or support, please refer to the official API documentation or contact our support team.