This page describes the current execution input specification for RECO Rail-routed agent requests.
It is intended for AI agents, automation clients, and developers that need to understand how to send execution requests through RECO Rail.
If older examples or notes conflict with this page, this page should be treated as the current reference.
This specification may be updated as RECO Rail expands beyond the current OpenAI-compatible execution path.
This specification defines how RECO Rail currently interprets execution requests routed through RECO Rail execution endpoints.
It covers:
execution endpoint format
RECO Rail execution key usage
connection identifier usage
request body handling
reserved RECO Rail fields
basic error response shape
current implementation limits
It does not cover:
direct use of upstream provider native UIs
billing policy details
human onboarding flows
account recovery flows
legal or compliance terms
full provider-specific API compatibility
Each execution request must be sent to a RECO Rail execution endpoint that includes the target connection identifier.
Endpoint format:
POST https://hook.recorail.com/v1/execute/{execution_binding_id}
execution_binding_id is the RECO Rail connection identifier for the selected execution connection.
The connection identifier is part of the execution URL. It should not be sent as a normal upstream payload field.
Example:
POST https://hook.recorail.com/v1/execute/eb_xxxxxxxxxxxxxxxx
Execution URLs are machine endpoints. They are not browser reading pages.
Each execution request must include a valid RECO Rail execution key.
Use the Authorization header:
Authorization: Bearer {reco_rail_execution_key}
The value in this header must be a RECO Rail execution key.
Do not place an upstream provider API key in this header.
Upstream provider API keys must not be stored in the AI agent, prompt, local automation configuration, browser-side script, or public repository.
Upstream provider API keys are stored and managed inside RECO Rail connection management.
The request body should contain the payload intended for the selected upstream execution path, subject to RECO Rail guard checks and normalization.
For the current OpenAI-compatible execution path, the body may use an OpenAI-compatible chat-completions style shape.
Example:
{
"messages": [
{
"role": "user",
"content": "Summarize this in one sentence."
}
],
"temperature": 0.2
}
The model configured in RECO Rail connection management is applied by RECO Rail.
If a model field is included in the request body, RECO Rail may override it with the model configured for the selected connection.
The following fields are reserved for RECO Rail internal control and must not be used as ordinary upstream payload fields:
execution_token
execution_binding_id
binding_id
auth_secret_ref
reco_*
RECO_*
RECO Rail may remove, ignore, or internally handle these fields before forwarding a request to the upstream provider.
Clients should not rely on these fields being forwarded upstream.
A typical RECO Rail-routed execution flow is:
AI agent or automation client
↓
RECO Rail execution endpoint
↓
RECO Rail execution key verification
↓
RECO Rail connection and guard checks
↓
Configured upstream provider
The AI agent uses:
RECO Rail execution URL
RECO Rail execution key
The AI agent must not use or store:
upstream provider API key
curl -X POST "https://hook.recorail.com/v1/execute/{execution_binding_id}" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {reco_rail_execution_key}" \
-d '{
"messages": [
{
"role": "user",
"content": "Summarize this in one sentence."
}
],
"temperature": 0.2
}'
RECO Rail returns JSON responses for execution requests.
A minimal error response may look like:
{
"ok": false,
"error": "error_code"
}
Examples:
{
"ok": false,
"error": "execution_token_required"
}
{
"ok": false,
"error": "binding_not_found"
}
{
"ok": false,
"error": "invalid_execution_token"
}
{
"ok": false,
"error": "delivery_auth_missing"
}
Future versions may include additional fields such as:
message
human_hint_ja
missing_fields
suggested_next_request
retry_after_seconds
blocked_scope
human_action_required
Earlier RECO Rail notes used the term “execution roots” for higher-level agent intent fields such as:
instruction
goal
artifact_ref
continue_from
plan_step_ref
These fields may be used by future higher-level agent workflows.
In the current execution endpoint, RECO Rail primarily treats the request body as the upstream execution payload for the selected connection, after RECO Rail authentication, connection checks, guard checks, and internal field handling.
Clients should not assume that high-level execution-root normalization is fully available unless a specific RECO Rail endpoint or integration guide states so.
The current execution path is primarily OpenAI-compatible.
Additional provider modes, including Anthropic-compatible, Google/Gemini-related, and generic HTTP execution paths, may require separate connection verification and forwarding behavior.
Until those modes are explicitly documented, clients should treat this page as the reference for the current RECO Rail-routed OpenAI-compatible execution path.
AI agents must use only:
RECO Rail execution URL
RECO Rail execution key
AI agents must not store, receive, log, or forward upstream provider API keys directly.
RECO Rail execution control applies only to requests routed through RECO Rail execution endpoints.
If a human or agent directly uses an upstream provider native UI or native API key outside RECO Rail, RECO Rail execution control and execution audit do not apply to that direct action.