Back to Learn

Aptabit Platformv3.7

API

Flows API

Endpoint for each published flow, its own token, allowed origins, and errors.

On this page

A flow published with API exposure gets its own endpoint, protected by a token exclusive to that flow. It is the Aptabit Platform's documented external API for connecting your organization's systems to flows.

Endpoint

HTTP
POST /api/v1/flow-inputs/{trigger_slug}
Authorization: Bearer {trigger_token}
Content-Type: application/json

Request body:

JSON
{
  "input": {
    "message": "Summarize the contract attached to ticket 4821."
  }
}

The input object must follow the input schema of the flow's contract. A new flow expects message (required) and query (optional) and returns response.

Example with curl:

Shell
curl -X POST "https://platform.example.com/api/v1/flow-inputs/<trigger_slug>" \
  -H "Authorization: Bearer $APTABIT_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Summarize the contract attached to ticket 4821."}}'

Response

The call is synchronous: the response arrives when the run ends, with the run record.

JSON
{
  "id": "run uuid",
  "flow_id": "flow uuid",
  "source": "api",
  "status": "succeeded",
  "input": { "message": "Summarize the contract attached to ticket 4821." },
  "output": { "response": "..." },
  "error_message": null,
  "created_at": "2026-10-08T12:00:00Z",
  "completed_at": "2026-10-08T12:00:04Z"
}
Field Description
status succeeded or failed.
output The output block's result, following the contract's output schema.
error_message The reason for the failure, when status is failed.

A run that fails during its blocks responds with HTTP 200, status set to failed, and error_message filled in. Input that breaks the contract also fails and creates an irregularity in the data-quality register. The trace of every block is stored with the run and can be reviewed in Settings > Logs.

Per-flow token

Each flow has its own token, with the flw_ prefix. The value appears only once, when the flow is created or the token is rotated, and the platform stores only its hash. The contract shows only the metadata:

JSON
{
  "api_auth": {
    "type": "bearer_token",
    "header": "Authorization",
    "scheme": "Bearer",
    "token_prefix": "flw_",
    "token_hint": "flw_...b51365",
    "method": "POST",
    "endpoint": "/api/v1/flow-inputs/my-flow"
  }
}

To rotate the token, use the rotation option on the flow or the call below, with an authenticated platform session:

HTTP
PATCH /api/v1/flows/{id}
Content-Type: application/json

{ "rotate_trigger_token": true }

The response carries the new trigger_token only once. Store it in the secrets vault of the system that will call the flow.

Allowed origins

Server-to-server calls, without an Origin header, are not checked for origin. For browser applications hosted outside the platform, set the origins in the flow's contract:

JSON
{
  "exposure": "api",
  "allowed_origins": ["https://app.example.com", "https://admin.example.com"]
}

The default is ["*"], which accepts any origin. The endpoint answers the OPTIONS preflight request with the POST and OPTIONS methods and the Authorization, Content-Type, and Accept headers.

Errors

Errors follow the Problem Details format:

JSON
{
  "type": "…/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid flow bearer token.",
  "code": "unauthorized"
}
Status Code Cause
400 bad_request The flow is not published, or the Origin header is invalid.
401 unauthorized Missing or invalid token.
403 forbidden Browser origin outside the allowed list.
404 not_found No flow exists with that trigger_slug, or it was archived.

Every response carries the x-request-id header, with the value sent by the client or one generated by the API. Quote it to support to locate the call in the logs.

Postman

Aptabit provides a Postman collection for the external endpoint, with the origin preflight and the flow call. Before running it, set baseUrl, flowEndpoint, flowApiToken, requestOrigin, and message.

API scope

The flow endpoint is the documented external API. Creating, publishing, editing contracts, and rotating tokens are done in the platform. The OpenAPI specification published by the API covers only the health and version endpoints.

Documentationv3.7