Execute API Tasks

API Doc

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

Overview

You can configure the endpoint for either a synchronous or asynchronous response. In sync mode, if the result is ready within 60 seconds, it will be returned immediately. If not, you'll receive an executionId, which you can use to check the result later by calling the status endpoint.

When executing an API Task, your task input will need to specify the API endpoint path, HTTP method type, and API input parameters. These parameters must match the schema defined in the API Task manifest.

Execute an API Task by task name

post

/task/api/execute-by-name

Execute an API Task using the provided task name. Supports both synchronous and asynchronous execution.

Header parameters

x-api-keystringRequired

API key for authentication.

Body

namespacestringRequired

The namespace of the task.

taskNamestringRequired

The name of the task to be executed.

labelstringOptional

Label of the task.

versioninteger · uint32Optional

Version number of the task.

asyncbooleanRequired

If true, the endpoint will retrieve the executionId; otherwise, it will try to return the execution result only if it completes within 60 seconds.

inputobjectRequired

Input data required for task execution.

executionTimeoutinteger · uint32Required

Timeout for task execution in seconds.

Responses

200

Successful execution

application/json

or

400

Bad request, invalid input.

application/json

401

Not authorized.

application/json

402

Payment required.

application/json

500

Internal server error.

application/json

post/task/api/execute-by-name

POST /task/api/execute-by-name HTTP/1.1
Host: run.truebit.network
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "namespace": "namespacetest",
  "taskName": "tasktestapi",
  "input": {},
  "executionTimeout": 10000,
  "async": true
}

{
  "executionId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee",
  "clearTextSolution": {
    "output": {
      "data": "{\"args\":{},\"data\":\"\",\"files\":{},\"form\":{},\"headers\":{\"Authorization\":\"Basic *********+\",\"Connection\":\"close\",\"Host\":\"10.1.10.100\",\"X-Service-Name\":\"truebit-api-adapter\"},\"json\":null,\"method\":\"GET\",\"origin\":\"10.2.140.154\",\"url\":\"http://10.1.10.100/anything/2\"}\n",
      "executedAt": "2026-01-07T15:14:41.584164",
      "headers": {
        "Access-Control-Allow-Credentials": "true",
        "Access-Control-Allow-Origin": "*",
        "Connection": "close",
        "Content-Length": "278",
        "Content-Type": "application/json",
        "Date": "Wed, 07 Jan 2026 15:14:42 GMT",
        "Server": "gunicorn"
      },
      "request_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee",
      "status": "success",
      "statusCode": 200
    },
    "status": "succeed",
    "senderAddress": "0x************************************2266"
  },
  "status": "Success",
  "totalTransferredBytes": {
    "request": 194,
    "response": 438
  }
}

Custom Headers

When executing API tasks, you may need to include custom HTTP headers in the request to the target API. This is common for authentication tokens, custom identifiers, or specifying content preferences.

Adding Headers to Your Request

You will need to include a headers object within the input field of your request body. Truebit will inject these headers into the final API call to the target endpoint.

Note: This feature is separate from the Truebit API authentication header (X-API-KEY), which is used to authenticate your request to Truebit. Custom headers you define in the input.headers object will be forwarded to the target API you are calling.

Supported Header Types

You can include any standard HTTP header, such as:

• Authorization – Bearer tokens, Basic auth, API keys for the target service.

• Accept – Specify expected response format (e.g., application/json, application/xml).

• Content-Type – Define the request body format when using POST/PUT methods.

• Custom Headers – Any application-specific headers required by the target API (e.g., X-Custom-Header, X-Request-ID).

Example: Executing an API Task with Custom Headers

curl -s -X POST "https://run.truebit.network/task/api/execute-by-name" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_TRUEBIT_API_KEY" \
  -d '{
    "namespace": "3a2b5129",
    "taskName": "custom",
    "input": {
      "path": "/anything/{Id}",
      "method": "GET",
      "params": {
        "Id": 12345
      },
      "headers": {
        "Authorization": "Bearer YOUR_TARGET_API_TOKEN",
        "X-Custom-Header": "CustomValue123",
        "Accept": "application/json"
      }
    },
    "executionTimeout": 30000,
    "async": false
  }'

Request Structure

Field	Location	Description
X-API-KEY	Request Header	Your Truebit API key for authentication with Truebit
input.headers	Request Body	Custom headers to be injected into the target API call

Important Notes

1. Header Injection: Headers defined in input.headers are injected by Truebit into the outgoing request to the target API endpoint.

2. Authentication Separation: Keep in mind the distinction between:

   • X-API-KEY in the request header → Authenticates your request to Truebit.

   • Authorization (or other auth headers) in input.headers → Authenticates the request to your target API.

3. CLI Authentication: If you previously configured authentication headers using the Truebit CLI tool, you can now alternatively include them directly in the request body using input.headers. Both methods are supported.

4. Header Overrides: Headers specified in input.headers will be included in the final request to the target API. Ensure there are no conflicts with headers that may be automatically set by Truebit.

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