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
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
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
Header Injection: Headers defined in input.headers are injected by Truebit into the outgoing request to the target API endpoint.
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.
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.
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).
