# Execute Function Tasks

## API Doc

Interactive API docs can be found at: <https://run.truebit.network/dispatcher/api-docs/>

## Overview

You can configure the endpoint to return either a synchronous or asynchronous response. In synchronous mode, if the result is ready before the timeout, it will be returned immediately. Otherwise, you’ll receive an `executionId`, which can be used to check the result later through the status endpoint.

## Execute a task by name

> Execute a task using the provided task name. Supports both synchronous and asynchronous execution.

```json
{"openapi":"3.1.0","info":{"title":"Task Execution API","version":"1.120.0-beta.275"},"tags":[{"name":"Function task execution","description":"Function task execution by id and namespace"}],"servers":[{"description":"Public beta","url":"https://run.truebit.network"},{"description":"Current environment relative paths","url":"/"}],"paths":{"/task/function/execute-by-name":{"post":{"summary":"Execute a task by name","description":"Execute a task using the provided task name. Supports both synchronous and asynchronous execution.","operationId":"executeTaskByName","tags":["Function task execution"],"parameters":[{"in":"header","name":"x-api-key","required":true,"schema":{"type":"string"},"description":"API key for authentication."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"namespace":{"type":"string","description":"The namespace of the task."},"taskName":{"type":"string","description":"The name of the task to be executed."},"label":{"type":"string","description":"Label of the task."},"version":{"type":"integer","format":"uint32","description":"Version number of the task."},"async":{"type":"boolean","description":"If true, the endpoint will retrieve the executionId; otherwise, it will try to return the execution result only if it completes within 60 seconds."},"input":{"type":"string","description":"Input data required for task execution."},"totalSolutions":{"type":"integer","format":"uint32","description":"Total number of solutions required for the task."},"requiredSolutions":{"type":"integer","format":"uint32","description":"Number of solutions required to complete the task."},"taskRequesterTimestamp":{"type":"integer","format":"uint32","description":"Task Requester Timestamp. This value is used to calculate the random bits in the node selection Phase."},"gasLimit":{"type":"string","description":"Execution step limit."}},"required":["namespace","taskName","async","input","totalSolutions","requiredSolutions","taskRequesterTimestamp"]}}}},"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ExecuteTaskAsyncResponse"},{"$ref":"#/components/schemas/ExecuteTaskSyncResponse"}]}}}},"400":{"description":"Bad request, invalid input.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BadRequestResponse"},{"$ref":"#/components/schemas/BlockchainSignedError"}]}}}},"401":{"description":"Not authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"ExecuteTaskAsyncResponse":{"type":"object","description":"Asynchronous response of task execution.","properties":{"executionId":{"type":"string","description":"The ID of the task execution."}}},"ExecuteTaskSyncResponse":{"type":"object","description":"Synchronous response of task execution.","properties":{"executionId":{"type":"string","description":"The ID of the task execution."},"clearTextSolution":{"type":"object","description":"The result of the task execution.","properties":{"output":{"type":"string","description":"The output of the task execution."},"executionStatus":{"type":"string","description":"The status of the task execution.","enum":["succeed","failed"]},"senderAddress":{"type":"string","description":"The address of the sender."},"signature":{"type":"object","description":"Signature details of the execution.","properties":{"v":{"type":"integer","format":"int64","description":"The recovery id of the signature."},"r":{"type":"string","description":"The 'r' value of the signature."},"s":{"type":"string","description":"The 's' value of the signature."}}}}},"verificationStatus":{"type":"string","description":"The status of the task verification.","enum":["Success","Running","Indeterminate","Error"]}}},"BadRequestResponse":{"type":"object","description":"Bad request","properties":{"message":{"type":"string","description":"Error message."}}},"BlockchainSignedError":{"type":"object","description":"Blockchain Signed Error","properties":{"status":{"type":"number","description":"Error code."},"message":{"type":"string","description":"Error message."},"taskRegistryContract":{"type":"string","description":"Task Registry Contract address."},"nodeRegistryContract":{"type":"string","description":"Node Registry Contract address."},"authorizationContract":{"type":"string","description":"Authorization Contract address."},"chainId":{"type":"string","description":"Chain identification."},"blockHash":{"type":"string","description":"Block hash."},"blockNumber":{"type":"number","description":"Block number."},"signedError":{"type":"string","description":"Error signed by hub."}}},"Error":{"type":"object","description":"Internal server error","properties":{"message":{"type":"string","description":"Internal server error"}}}}}}
```

### Authorization

#### API KEY

To get authorization to execute a task, include your registered `API key` in the request header. This allows Truebit to validate your access and identify the account responsible for covering the task execution cost (linked to the API key’s associated address).

**Example**

```
X-API-KEY: be0dc6ba-9a60-4777-b5b7-60ed2397e3ed
```