Skip to Content

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

app/customers/repository.ts
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.

app/upstream.ts
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 (except cookie and host). The longest prefix is checked first.
  • A request outside every prefix gets the normal 404.

Choose how to authenticate:

  • "forward" passes the user’s Authorization header to the real system. Your app has no sign-in of its own.
  • "service" drops that header and sends your headers instead (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.

app/erp/orders/get.ts
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.

app/erp/invoices/get.ts
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.
  • origin must be an https:// string to a public domain (no IP, localhost, *.local or *.internal). check reports upstream.origin-invalid.
  • Upstreams are for APIs only. Forwarding a whole website (HTML) isn’t supported.
  • check rejects a token written into the code (code.hardcoded-secret).
  • The log keeps 7 days, up to 20,000 rows.

Next steps

Last updated