API Endpoint Trigger

Expose a programmable HTTP endpoint backed by a workflow — supports multiple methods, auth, and synchronous responses via the Return node.

When to Use

Use API Endpoint when:

You want to build a custom REST API without writing server code
Callers need a synchronous response from your workflow
You need to authenticate incoming requests with an API key or bearer token
You want an OpenAI-compatible chat endpoint for SDK clients

If callers do not need a synchronous response and you just want to react to events, use Webhook Trigger instead.

Output

API Endpoint creates one control output handle per HTTP method you enable in allowedMethods. For example, if you enable GET and POST, the node produces a GET handle and a POST handle. Only the branch matching the incoming request method runs.

Handle	Type	Description
`GET`, `POST`, etc.	control output	One handle per method in `allowedMethods`. Each emits an `api_request` object.

The api_request (accessed as {{ api_request.* }}) shape:

Field	Type	Description
`body`	any	Parsed request body
`headers`	object	Request headers
`query`	object	URL query parameters
`path`	string	Request path
`method`	string	HTTP method used (e.g. `GET`, `POST`)
`contentType`	string	Value of the `Content-Type` header
`rawBody`	string	Unparsed body string
`source`	string	Source identifier — `api`
`auth`	object	Authentication result — `type` and `verified` status
`request`	object	Request metadata — `requestId` and `receivedAt` timestamp

Settings

Endpoint

Setting	Type	Default	Description
`protocol`	select	`rest`	Protocol mode. `rest` is standard JSON in/out. `openai-chat` makes this endpoint compatible with any OpenAI SDK client.
`path`	string	`/api`	Route suffix for this endpoint. Example: `/users`
`allowedMethods`	multiselect	`GET`, `POST`	HTTP methods this endpoint accepts. Each selected method creates an output handle on the node.
`parseBodyAs`	select	`auto`	How to parse the request body: `auto` (try JSON, fall back to text), `json`, `text`, or `form`
`responseMode`	select	`use-workflow-response`	`use-workflow-response` holds the connection and returns what the Return node produces. `ack-immediately` responds with 200 right away.
`defaultStatusCode`	number	`200`	HTTP status code to return when `responseMode` is `ack-immediately` or the workflow produces no response.

Authentication

Setting	Type	Default	Description
`authType`	select	`none`	Authentication strategy: `none`, `api-key`, or `bearer-token`
`apiKeyLocation`	select	`header`	Where to read the API key: `header` or `query`. Shown when `authType` is `api-key`.
`apiKeyName`	string	`X-API-Key`	Header name or query parameter name for the API key. Shown when `authType` is `api-key`.
`authorizationHeaderName`	string	`Authorization`	Header name for the bearer token. Shown when `authType` is `bearer-token`.
`bearerPrefix`	string	`Bearer`	Prefix stripped from the Authorization header value. Shown when `authType` is `bearer-token`.
`secret`	secret	—	Expected API key or bearer token value. Stored securely, never exposed in the workflow payload. Shown when `authType` is `api-key` or `bearer-token`.

Testing

Setting	Type	Default	Description
`mockMethod`	select	`GET`	HTTP method to simulate when testing this workflow locally.
`mockPayload`	code editor (JSON)	`{}`	JSON body to inject when testing this workflow locally.
`mockHeaders`	code editor (JSON)	`{}`	JSON headers to inject when testing this workflow locally.
`mockQuery`	code editor (JSON)	`{}`	JSON query parameters to inject when testing this workflow locally.

Example

Canvas

Build a user lookup endpoint that returns a synchronous response:

Set path to /users/lookup
Set allowedMethods to POST
Set authType to api-key and configure secret
Connect the POST handle to an HTTP Request node — call your internal service with {{ api_request.body.userId }}
Connect the result to a Return node

Access request data in downstream nodes:

{{ api_request.body.userId }}
{{ api_request.headers["Authorization"] }}
{{ api_request.query.id }}
{{ api_request.method }}

Test with curl:

curl -X POST https://triggers.tensorify.io/your-endpoint/users/lookup \
  -H "X-API-Key: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"userId": "usr_123"}'

OpenAI Chat protocol: Set protocol to openai-chat to expose POST .../chat/completions and GET .../models under your trigger path. The OpenAI messages[] array is translated into workflow variables (user_message, system_prompt, history, model, stream). Connect the POST handle to an AI Agent message input and wire a Return node for the response.

TSL

import api from @tensorify/api-trigger:1.0.0
import http_request from @tensorify/http-request:3.0.0
import return_node from @tensorify/return:3.0.0

node trigger @tensorify/api-trigger:1.0.0 {
    path = "/users/lookup"
    allowedMethods = ["POST"]
    authType = "api-key"
    apiKeyName = "X-API-Key"
    responseMode = "use-workflow-response"
}

node fetch @tensorify/http-request:3.0.0 {
    method = "GET"
    url = "https://api.example.com/users/{{ api_request.body.userId }}"
}

node respond @tensorify/return:3.0.0 {
    returnMode = "simple"
}

trigger.POST -> fetch.body
fetch.response -> respond.input

Common Gotchas

Multiple methods: Each allowed method creates a separate output handle. Route them separately if you want different logic per method.
Return required: When responseMode is use-workflow-response, you must connect a Return node — otherwise the caller's connection hangs until timeout.
Auth secret: The secret setting is stored encrypted. It is only used for request validation, never passed through workflow variables.
OpenAI Chat mode: When protocol is openai-chat, send stream: true in the request body for SSE streaming. Use the X-Tensorify-Session-Id header for per-conversation memory with an AI Agent.
Timeout: If your workflow takes longer than the configured timeout to produce a Return value, the caller receives a timeout error.