Skip to content
MeridFlow AiFlow v8.x • self-hosted

Console

The Console is a browser-based way to converse with a single Orchestrator directly, outside of any Agent conversation. It's useful for debugging an instruction or a tool configuration before wiring an Agent up to delegate into it. This page documents the one real API call involved in reaching it, and explains why the rest of the flow has no API or CLI equivalent.

Gated behind a deployment setting, admin session token required

See the two notes at the top of Orchestrators: the endpoint below only exists when your deployment has Orchestrators turned on, and it authenticates with an admin session token.

Minting a console handoff token

POST /api/v1/orchestrators/{orchestrator_id}/console-token

Requires: Editor and above.

This is the only step of the Console flow you call directly. It mints a short-lived, single-use token and returns a URL that embeds it.

curl -X POST https://api.your-domain.com/api/v1/orchestrators/1/console-token \
  -H "Authorization: Bearer $ADMIN_TOKEN"

import httpx

response = httpx.post(
    "https://api.your-domain.com/api/v1/orchestrators/1/console-token",
    headers={"Authorization": f"Bearer {admin_token}"},
)
response.raise_for_status()
console_url = response.json()["console_url"]

const response = await fetch(
  "https://api.your-domain.com/api/v1/orchestrators/1/console-token",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${adminToken}` },
  },
);
const { console_url } = await response.json();

The response has exactly one field:

Field Type Notes
console_url string A fully-qualified URL on your own deployment's domain, with the single-use token embedded as a query parameter. 
{
  "console_url": "https://api.your-domain.com/console-entry?token=eyJhbGciOi..."
}

A nonexistent orchestrator_id gets a 404.

Why the rest of this flow has no API equivalent

console_url is meant to be opened in a browser, not called as an API request. Everything past this point is a browser session, not an oversight:

  • The token is single-use and expires in 60 seconds. It exists purely to give a browser tab, which has no way to carry your Authorization header, a way to authenticate itself. Visiting console_url exchanges the token for a same-origin session cookie and immediately consumes the token. A second visit with the same token fails with 401, whether that's a reload, a copy-pasted link, or a deliberate replay attempt.
  • The session lives in an HTTP-only cookie, not a token you hold. It lasts 30 minutes, is scoped to the Console's own path, and needs HTTPS in production like the rest of AiFlow. Browsers exempt localhost, so local testing over plain HTTP still works. The API will not hand you this cookie's value, and it is not something you can copy into curl.
  • The Console itself is an interactive chat UI, not a JSON endpoint. You type messages, watch tool calls and any sub-Orchestrator hand-offs happen in real time, and inspect past sessions, all visually. There's no meaningful "call it programmatically" version of that experience to document.

Most importantly: the Console is a debugging and exploration convenience, never the production delegation path. A real task reaching an Orchestrator from a live conversation always goes through the delegate_to_orchestrator tool documented in Agent-to-Orchestrator delegation, never through the Console. If you're building an integration, your integration should never need to touch the Console; it's a tool for whoever configures the Orchestrator to sanity-check it by hand.

What to expect once you're in

A couple of things worth knowing if you, or whoever administers your deployment, open console_url:

  • It reflects your current configuration on every open, not a snapshot from whenever the deployment last restarted. The Orchestrator you're chatting with is built fresh from whatever is currently stored for it, its instruction, model, enabled tools, and sub-Orchestrator links, the same way a real delegated call builds it.
  • The session isn't scoped to just the one Orchestrator you minted a token for. Once the cookie exchange completes, you can switch between any Orchestrator in the deployment from inside the Console UI itself. That's consistent with the rest of AiFlow's admin permissions: any Editor role or above can already read and edit every Orchestrator through the API endpoints on this site. This is the same access, just surfaced as an interactive chat instead of JSON.
  • It's the fastest way to trigger a human approval gate for testing. Turn requires_approval on for a tool, ask the Console to do something that calls it ("email a summary to ops@acme.com"), and the reply confirms the action was queued rather than sent, no real Agent conversation or phone call needed first. See Approvals for reviewing and deciding what lands in the queue.