User Documentation

Prouter User Guide

Prouter is a local-first AI gateway for chat, API routing, media generation, agents, and app building. This guide explains how to get started, choose the right routing mode, control spend, and use the platform efficiently.

Start Here

1. Sign in to Prouter with your account.
2. Use the Chat workspace first if you are testing prompts, writing, summarizing, researching, or debugging.
3. Create an API key only when you want to connect another app, script, or build platform.
4. Start with prouter-auto or Auto mode. Let Prouter choose local, low-cost, mid-cost, or high-end routing.
5. Add wallet credits only when you need paid cloud escalation, API cloud usage, image, video, or voice generation.
6. Check History and generated assets after important runs so you can reuse good outputs instead of regenerating them.

How To Optimize Usage

Routing Profiles

Workspace Guide

The signed-in workspace is the easiest way to use Prouter without writing code. Use the product tiles to switch between Chat, IDE, Image, Video, Voice, History, and Agents when those capabilities are enabled for your account.

• Chat: best for everyday LLM routing, writing, analysis, coding help, and testing prompt quality.
• History: review previous conversations and generated assets before spending time or credits on another run.
• API Keys: create one key per app or integration. Revoke keys that are exposed or no longer used.
• Add credit: top up the wallet when you need cloud routes or paid media generation.
• Mode selection: leave routing on Auto unless you know the task should be cheap, balanced, or high-end.

API Quickstart

Prouter exposes an OpenAI-compatible API surface. Create an API key in the workspace, store it asPROUTER_API_KEY, and call the API with a bearer token. Never put API keys in browser code, screenshots, public repos, or client-side environment variables.

Chat Completion

curl https://prouter.io/v1/chat/completions \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "prouter-auto",
    "messages": [
      { "role": "user", "content": "Summarize this customer feedback and identify action items." }
    ],
    "stream": false,
    "task_mode": "general"
  }'

Streaming Chat

curl https://prouter.io/v1/chat/completions \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "prouter-auto",
    "messages": [
      { "role": "user", "content": "Draft a concise launch plan for this feature." }
    ],
    "stream": true
  }'

API Endpoints

Image, Video, Voice, And Music

Media generation uses wallet credits. Use detailed prompts, specify the desired output style, and generate a small number of strong candidates before asking for variants. For image edits or variants, use references that clearly show the subject, layout, and style you want preserved.

curl https://prouter.io/v1/images/generations \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto-smart-tier",
    "prompt": "A clean product mockup for an AI routing dashboard, dark UI, readable labels.",
    "size": "1:1",
    "quality": "mid"
  }'

curl https://prouter.io/v1/music/generations \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Reference-Trait Pop",
    "prompt": "[Verse] Neon streets are waking up\n[Chorus] Hold the line, keep running",
    "style": "modern synth-pop, 104 BPM, hopeful mood, warm female vocal, glossy drums, wide chorus lift",
    "instrumental": false,
    "custom_mode": true,
    "duration_seconds": 150,
    "negative_tags": "copying lyrics, soundalike vocals, muddy bass"
  }'

• Images: best for mockups, campaign visuals, product scenes, concept art, and source material for apps.
• Video: best for short product motion, ad concepts, demos, and storyboards. Write the scene sequence clearly.
• Voice: best for narration, spoken interfaces, short audio assets, and voiceover drafts.
• Music: best for songs, jingles, beds, and brand cues. Describe reference songs by mood, tempo, arrangement, groove, and mix rather than copying lyrics or requesting a soundalike.
• Artifacts: generated files can appear in History and may be imported into IDE projects when available.

Agents

Agents are reusable workers with instructions, routing policy, optional memory, optional tools, trace records, and budget controls. Use agents when you want a repeatable workflow rather than a one-off chat.

Endpoints

Create An Agent

Use a stable instruction block, a routing profile, optional tool policy, optional memory policy, and a per-run budget limit for cloud routes.

curl https://prouter.io/v1/agents \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support routing agent",
    "instructions": "Answer customer questions concisely. Use supplied context before general knowledge.",
    "routing_profile": "auto",
    "tool_policy": {
      "web_fetch": true,
      "webhooks": {
        "enabled": true,
        "url": "https://example.com/agent-webhook",
        "secret": "replace-with-shared-secret"
      },
      "max_tool_steps": 2
    },
    "memory_policy": { "agent_memory": true },
    "budget_limit_usd": 0.25,
    "status": "active"
  }'

Run An Agent

Use an idempotency key for every production run. Reusing the same key returns the original run instead of charging or executing again.

curl https://prouter.io/v1/agents/AGENT_ID/runs \
  -H "Authorization: Bearer prouter_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Review https://example.com and draft a short answer.",
    "idempotency_key": "customer-run-001",
    "attachment_ids": [],
    "artifact_ids": []
  }'

JavaScript

const response = await fetch("https://prouter.io/v1/agents/AGENT_ID/runs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PROUTER_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "Summarize the selected brief and remember the outcome.",
    idempotency_key: crypto.randomUUID(),
    attachment_ids: ["ATTACHMENT_ID"],
    artifact_ids: ["ARTIFACT_ID"]
  })
});

const run = await response.json();
console.log(run.result);
console.log(run.prouter.steps);

Python

import os
import uuid
import requests

response = requests.post(
    "https://prouter.io/v1/agents/AGENT_ID/runs",
    headers={
        "Authorization": f"Bearer {os.environ['PROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "input": "Use the attached context and answer in three bullets.",
        "idempotency_key": str(uuid.uuid4()),
        "attachment_ids": [],
        "artifact_ids": [],
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["result"])

Response Shape

Every run returns the final answer and the Prouter trace. The trace shows routing, context loading, tool calls, observations, provider/model choice, tokens, latency, and credits charged.

{
  "id": "RUN_ID",
  "object": "agent.run",
  "created": 1786000000,
  "agent_id": "AGENT_ID",
  "result": "Final agent answer",
  "status": "completed",
  "prouter": {
    "steps": [
      { "step_type": "planning" },
      { "step_type": "routing_preview" },
      { "step_type": "file_context" },
      { "step_type": "artifact_context" },
      { "step_type": "memory" },
      { "step_type": "tool_call" },
      { "step_type": "tool_limit" },
      { "step_type": "observation" },
      { "step_type": "model_call" },
      { "step_type": "connector_plan" },
      { "step_type": "connector_execution" },
      { "step_type": "webhook" },
      { "step_type": "schedule_trigger" }
    ],
    "credits_charged": 0
  }
}

Policies And Controls

• routing_profile: use auto, low_cost, mid_cost, or high_end.
• tool_policy.web_fetch: allows public HTTP/HTTPS page fetches when the operator switch is enabled.
• tool_policy.media_generation: allows image/video job submission when the paid media operator switch is enabled.
• tool_policy.webhooks: posts signed completion payloads to a public HTTPS endpoint when the operator switch is enabled.
• tool_policy.connectors: plans approved connector actions such as slack.post_message, hubspot.create_contact, airtable.create_record, and webhook.post_event. Approved webhook.post_event actions can deliver only when AGENTS_CONNECTOR_EXECUTION_ENABLED=true; Slack, HubSpot, and Airtable also require AGENTS_PROVIDER_CONNECTOR_EXECUTION_ENABLED=true, normalized provider_request previews, credential_requirements, resolvable secret_references, and no unsafe_plaintext findings. Provider secrets can resolve from env: references or the operator file configured by AGENTS_CONNECTOR_SECRET_FILE.
• provider errors: Slack, HubSpot, and Airtable execution validates required payload fields before sending and records sanitized provider_error, status_code, and optional retry_after fields for failed provider responses.
• connector approvals: action approval records appear in connector plans as approval_status and approved_for_execution. Execution also requires a ready connector and the separate execution operator switch.
• tool_policy.max_tool_steps: optionally lowers the per-agent tool/context step ceiling under the global operator limit.
• tool_limit: appears when requested tools are skipped because the effective tool-step ceiling has been reached.
• webhook retries append another trace step with retry: true and use the agent's current webhook policy.
• connectors: credential registry scaffolding stores non-secret metadata and safe secret references, redacts raw secret-like keys, and requires the operator switch to create or update records.
• memory_policy.agent_memory: loads and updates agent-scoped memory when the operator switch is enabled.
• attachment_ids: up to 10 uploaded file IDs from the same user.
• artifact_ids: up to 10 organization-scoped artifact IDs.
• budget_limit_usd: blocks cloud execution when the estimated route exceeds the agent limit.
• AGENTS_TEAM_CONTROLS_ENABLED: when enabled, standard users can list, read, and run existing agents while admin users manage agents, schedules, connector records, and webhook retries.
• interval_minutes: schedule cadence from 15 minutes to 30 days. Schedule creation, pause, resume, manual run, skip, and updates require the operator switch.

Billing Behavior

Local routes charge zero external credits. Cloud routes reserve wallet budget before execution, then capture or release the reservation based on the final run state. Agent media generation is a paid tool and charges the same wallet credits as the media workspace when a job is submitted.

IDE / App Builder

The IDE workspace is for building small apps from prompts, starter files, imported source zips, and generated assets. Use the Build flow from left to right: create or import a project, create starter files, draft a change, run build/install checks, then start or export the app.

• Project: create a new project, import a zip, duplicate a working project, or archive old work.
• Files: use Starter files when beginning from a blank project, or Draft files from a prompt.
• Agent diff: review generated changes before applying them. Refresh context after manual edits.
• Build: run build checks before previewing or exporting. Install only when dependencies are needed.
• Preview: start the app after a successful build, then save/export when it is ready.

Billing, Credits, And Spend Control

Signup is free. Routine local-first workspace chat does not consume external cloud credits. Wallet credits are used for paid cloud text routes, API cloud escalation, image generation, video generation, voice generation, and paid agent tools.

• Minimum top-up is $10 when wallet checkout is enabled.
• Cloud text routes are charged by input and output token usage.
• Local routes are preferred when they can satisfy the request and capacity is available.
• Budget gates can block cloud execution when the estimate exceeds the available wallet or configured limit.
• If a cloud route is blocked, try Auto or Low Cost, reduce context size, or add credits if the task truly needs paid routing.

Security Basics

• Keep API keys secret. Treat them like passwords.
• Create separate API keys for separate apps or environments.
• Revoke keys immediately if they appear in logs, screenshots, repos, or client-side code.
• Do not paste provider secrets, private credentials, or sensitive customer data into prompts unless you are authorized to do so.
• Review generated text, code, media, and agent outputs before using them in production.

Troubleshooting

Best Practice Checklist

• Use Auto first, then override only when you have a reason.
• Keep prompts concise but complete: goal, inputs, constraints, and desired format.
• Use Low Cost for repeatable bulk jobs.
• Use High End only when the task needs deep reasoning or high confidence.
• Use idempotency keys for production agent runs.
• Set per-agent budgets before enabling tools or schedules.
• Review History and Artifacts before regenerating work.
• Rotate API keys periodically and after any suspected exposure.