Execution API

The Execution API allows you to trigger your deployed API and process files through the defined workflow.

Request


Endpoint	`/deployment/api/<organization_id>/<api_name>/`
URL	`https://us-central.unstract.com/deployment/api/<organization_id>/<api_name>/`
Method	`POST`
Headers	`Authorization: Bearer <YOUR API KEY>`
Body	`multipart/form-data`

Parameters

Parameter	Type	Default	Required	Description
files	File		Yes	Specifies the file(s) to be processed. Note: Multiple files can be provided, but the result will be completed only after all files have been processed.
timeout	integer	0	No	Specifies how long to wait for the API to complete the operation before timing out. The value can range from 0 to 300 seconds. If omitted, the request will execute in the background without a timeout.
include_metadata	boolean	false	No	If this parameter is `true`, metadata of the result is included; otherwise, it is not. Note: This flag works only with tools exported from Prompt Studio. It contains usage and cost details of the LLMs and embeddings used.

API Responses

The API can return various responses based on the status of the request.

Possible HTTP Status Codes

HTTP Status	Description	Content-Type
200	OK - The request was successful. The API will return the result in the response body.	`application/json`
400	Bad Request - The request could not be understood or was missing required parameters.	`application/json`
401	Unauthorized - Authentication failed or user does not have permission for the requested operation.	`application/json`
403	Forbidden - The API key is missing or invalid.	`application/json`
404	Not Found - The requested resource could not be found (Or Incorrect API URl)	`application/json`
422	Unprocessable Entity - Validation error, the input could not be processed.	`application/json`
500	Internal Server Error - An error occurred on the server.	`application/json`

Response Structure.

{
    "message": {
        "execution_status": "<Current Status of execution>",
        "status_api": "<URL for checking execution status>",
        "error": "<Error messages>",
        "result": [
            {
                "file": "<file_name>",
                "status": "<The processing status of the file>",
                "result": {
                    "input_file": "<input_file_name>",
                    "result": "<execution result of the file>"
                },
                "error": "<Error details>",
                "metadata": {
                    "source_name": "<source file name>",
                    "source_hash": "<hash value of the file>",
                    "organization_id": "<organization_id>",
                    "workflow_id": "<workflow_id>",
                    "total_elapsed_time": "<total_time>",
                    "tool_metadata": "<list_of_tools_used>"
                }
            }
        ]
    }
}

Descriptions of Keys

execution_status: The current status of the workflow execution (e.g., PENDING, COMPLETED).
status_api: The URL that can be used to check the status of the execution.
error: Any error details if applicable.
result: The results of the execution, if available.
file: The name of the file that failed.
status: The processing status of the file.
metadata: The metadata of the file execution, The details like execution_id and elapsed_time are the data at which the file actually executed without using file history.

Possible Execution status

Status	Description
`PENDING`	Processing is in the queue (async mode).
`EXECUTING`	Execution is in progress (async mode).
`INITIATED`	Execution has started (async mode).
`QUEUED`	Execution task is waiting to be processed (async).
`READY`	Execution is ready for the build phase (async mode).
`COMPLETED`	Execution finished successfully (fully or partially).
`ERROR`	The api is failed to execute completely.

Completed Execution with Results

Upon successful completion of the execution, the API provides a response containing detailed results. The execution_status field will be set to COMPLETED.

Sample response:

{
    "message": {
        "execution_status": "COMPLETED",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Success",
                "result": {
                    "input_file": "<input_file_name>",
                    "result": "<execution result of the file>"
                },
                "metadata": {
                    "source_name": "<source file name>",
                    "source_hash": "<hash value of the file>",
                    "organization_id": "<organization_id>",
                    "workflow_id": "<workflow_id>",
                    "total_elapsed_time": "<total_time>",
                    "tool_metadata": "<list_of_tools_used_during_execution>"
                }
            }
        ]
    }
}

Execution Error

If an error occurs during the execution process, the response will provide details about each file that failed. This helps in understanding what went wrong and allows for corrective actions

sample response

{
    "message": {
        "execution_status": "ERROR",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Failed",
                "error": "<Error details or hint>"
            }
        ]
    }
}

Next Steps:

Check Logs: To get more detailed information about the error, refer to the logs for the API using the provided execution_id.
Contact Admin: If the logs do not provide sufficient information or if further assistance is needed, contact the administrator for additional details.

Mixed Results

If the execution process results in a mix of successful and failed files, the response will include detailed results for each file. This allows you to see which files were processed successfully and which encountered issues.

{
    "message": {
        "execution_status": "COMPLETED",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": [
            {
                "file": "<file_name>",
                "status": "Failed",
                "error": "<Error details or hint>"
            },
            {
                "file": "<file_name>",
                "status": "Success",
                "result": {
                    "input_file": "<input_file_name>",
                    "result": "<execution result of the file>"
                },
                "metadata": {
                    "source_name": "<source file name>",
                    "source_hash": "<hash value>",
                    "organization_id": "<organization_id>",
                    "workflow_id": "<workflow_id>",
                    "total_elapsed_time": "<total_time>",
                    "tool_metadata": "<list_of_tools_used_during_execution>"
                }
            }
        ]
    }
}

Description of each response code with sample

Below are some common response codes and their meanings:

422: Client Error

This response indicates that the pipeline is inactive, and the execution cannot proceed.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Pipeline 'testetl' is inactive, please activate the pipeline",
            "attr": null
        }
    ]
}

400: Missing File

This response occurs when the files parameter is missing or empty.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "File shouldn't be empty",
            "attr": null
        }
    ]
}

200: Executing in Background

This response is returned when the execution is still ongoing, and the results are not yet available.

{
    "message": {
        "execution_status": "EXECUTING",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": null
    }
}

200: Completed

This response is returned when execution is completed, and the results are available.

{
    "status": "COMPLETED",
    "message": []  // Results
}

200: Pending

This response indicates that the execution is queued but has not started.

{
    "message": {
        "execution_status": "PENDING",
        "status_api": "/deployment/api/<organization_id>/<api_name>/?execution_id=<execution_id>",
        "error": null,
        "result": null
    }
}

400: Validation Error

A validation error occurs when an invalid parameter is passed, such as a non-integer value for timeout.

{
    "type": "validation_error",
    "errors": [
        {
            "code": "invalid",
            "detail": "A valid integer is required.",
            "attr": "timeout"
        }
    ]
}

403: Forbidden

The API key is missing or invalid, preventing the request from proceeding.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Missing API key",
            "attr": null
        }
    ]
}

500: Server Error

A 500 Internal Server Error indicates that something went wrong on the server during the processing of the request. This is a general error when the server encounters an unexpected condition that prevents it from fulfilling the request.

401: Unauthorized

A 401 Unauthorized error is returned when the request lacks proper authentication credentials, such as a missing or invalid API key. This means that the user is not authorized to access the requested resource.

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "Unauthorized",
            "attr": null
        }
    ]
}

404: Not Found

This response occurs when the API name or URL is invalid, meaning the requested resource could not be found on the server. This can happen if the API name in the URL is incorrect or does not exist. Ensure that the organization_id and api_name are correctly specified in the request URL.

invalid api name (invalid api url)

{
    "type": "client_error",
    "errors": [
        {
            "code": "error",
            "detail": "API not found",
            "attr": null
        }
    ]
}

Possible Causes:

The api_name is misspelled or does not match an existing API.
The organization_id is incorrect or does not exist in the system.
The API endpoint is not available or has been removed.

Solution:

Check the list of available APIs for the organization to confirm the correct name.

Request​

Parameters​

API Responses​

Possible HTTP Status Codes​

Response Structure.​

Descriptions of Keys​

Possible Execution status​

Completed Execution with Results​

Execution Error​

Next Steps:​

Mixed Results​

Description of each response code with sample​

422: Client Error​

400: Missing File​

200: Executing in Background​

200: Completed​

200: Pending​

400: Validation Error​

403: Forbidden​

500: Server Error​

401: Unauthorized​

404: Not Found​

Possible Causes:​

Solution:​