# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devs.truebit.io/integrating-truebit-tasks/function-task-execution/execute-function-tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.