Call outside APIs
≈ 15 min · you will have an app that calls another system’s API (an ERP, a partner service), sits in front of an existing API and logs every request.
There are two ways. To call a few endpoints, use fetch in a repository; to replace an old system step by step, declare an upstream: any request your app has no handler for is forwarded to the real system.
1. Store the outside service’s key
A key never goes in code. The owner enters it on the Secrets page (sidebar, Connect group), or the agent sets it through MCP. The value applies at once, without a redeploy. Agents can see names but never read values.
Read it in code with env.NAME from manh/env, inside the function, so you always get the current value.
2. Call an endpoint with fetch
import { HTTPException } from "hono/http-exception";
import { fail } from "manh/errors";
import { env } from "manh/env";
export async function lookupTaxCode(taxCode: string) {
const key = env.TAX_API_KEY;
if (!key) throw new HTTPException(503, { message: "TAX_API_KEY is not set", cause: { code: "NOT_CONFIGURED" } });
const res = await fetch(`https://api.lookup.example.com/v1/company/${encodeURIComponent(taxCode)}`, {
headers: { authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(8000), // don't let the request hang
});
if (res.status === 404) fail(404, "Tax code not found", "NOT_FOUND");
if (!res.ok) throw new HTTPException(502, { message: "The lookup service is failing", cause: { code: "UPSTREAM" } });
return res.json();
}The business error (an unknown tax code) uses fail from manh/errors, because fail is for 4xx codes. A missing setting and a failing outside service are 5xx codes, so they still throw HTTPException. Both give the UI the body { error, message, code } to show message.
3. Put your app in front of an existing API
app/upstream.ts declares one or more prefixes. prefix is the path in your app (with /api); origin is the address of the real system.
import { env } from "manh/env";
export default [
{ prefix: "/api/erp", origin: "https://erp.example.com/api" }, // auth: "forward" (default)
{ prefix: "/api/pay", origin: "https://pay.partner.example", auth: "service",
headers: { authorization: `Bearer ${env.PAY_TOKEN}` } }, // token from Secrets
];- An app handler that matches the method and path always wins.
- A request under a prefix with no handler is forwarded to
origin + the rest of the path, keeping the method, query, body and headers (exceptcookieandhost). The longest prefix is checked first. - A request outside every prefix gets the normal 404.
Choose how to authenticate:
"forward"passes the user’sAuthorizationheader to the real system. Your app has no sign-in of its own."service"drops that header and sends yourheadersinstead (a service token from Secrets). Your app runs its own sign-in.
4. Change the real system’s answer
Write a handler for the exact path, call upstream(c) to get the real answer, then return what you want.
import { upstream } from "manh/upstream";
export const schema = {};
export default async function handler(c) {
const rows = await (await upstream(c)).json(); // GET /api/erp/orders on the real system
const today = new Date().toISOString();
return rows.map(({ costPrice, ...o }) => ({ ...o, overdue: o.dueDate < today })); // hide cost, add an overdue flag
}To call a different path: upstream(c, { path: "/api/erp/orders/" + id, method: "GET" }).
5. Mock an endpoint that isn’t ready
mock(c, data, { status, delay }) answers without calling the real system. Use it while the partner’s side isn’t finished, or to test the UI against errors and delays.
import { mock, upstream } from "manh/upstream";
import { SAMPLE_INVOICES } from "./sample";
export const schema = {};
export default async function handler(c) {
const mode = $mock?.["GET /api/erp/invoices"] ?? "real"; // "real" | "mock" | "error500" | "slow3s"
if (mode === "error500") return mock(c, { message: "ERP error" }, { status: 500 });
if (mode === "slow3s") return mock(c, SAMPLE_INVOICES, { delay: 3000 });
if (mode === "mock") return mock(c, SAMPLE_INVOICES);
return upstream(c);
}$mock is one of the app’s stored variables. The owner switches modes in the project’s Stored variables section, with no redeploy needed.
6. See the request log
Every /api request of the app is logged: method, path, status, source (handler, upstream, mock, error), timings and bodies up to 8 KB. The authorization, cookie and x-api-key headers and fields named like password, token, secret or otp are masked.
The owner sees it in Operations › Traffic. Agents read it through MCP to write mocks and tests from real answers. Add log: { bodies: false } to an upstream entry to stop recording bodies.
Good to know
- The workspace preview doesn’t call upstreams. Test against the deployed app.
originmust be anhttps://string to a public domain (no IP,localhost,*.localor*.internal).checkreportsupstream.origin-invalid.- Upstreams are for APIs only. Forwarding a whole website (HTML) isn’t supported.
checkrejects a token written into the code (code.hardcoded-secret).- The log keeps 7 days, up to 20,000 rows.
Next steps
- Sign-in and permissions — your own sign-in when you use
auth: "service". - API handlers — throwing errors and returning results.
- Email, AI, file storage — built-in services that need no key.