---
title: "Call a declared app route or its unmatched-request fallback"
method: POST
path: "/app/{id}/api/{operation}"
---

# Call a declared app route or its unmatched-request fallback

`POST /app/{id}/api/{operation}`

## Request

- Base URL: `https://charm.ing`
- URL: `https://charm.ing/app/{id}/api/{operation}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

External callers must use Bearer auth. The platform strips `/app/<id>` so the app sees `/api/<operation>`. A declared route handler returns exactly its `outputSchema` value without adding a transport envelope unless those fields belong to the schema; Charming validates it and wraps HTTP success as `{ ok: true, value }`. `window.charming.api` uses `renderToken` and unwraps that envelope, so in-page callers receive the value directly. If no declared route matches, the optional `default.fetch` handles the request and its `Response` passes through unchanged; without that fallback, Charming returns a 404. Direct callers should use `appToken` or `userToken`.

## Request body

- object: Input defined by the selected app operation. Fetch the app-specific `/app/{id}/openapi.json` document for its typed schema before generating a function input.

## Response `200`

A declared route returns `{ ok: true, value }`, where `value` matches its `outputSchema`. A custom unmatched-request fallback response passes through unchanged.

- object: Declared route success uses `{ ok: true, value }`; the route handler returns exactly the `outputSchema` value and does not add a transport envelope unless those fields belong to the schema. The open object schema also permits the author-defined body from an unmatched request handled by `default.fetch`.

## Other responses

- `401`: Authentication required.
- `403`: Token does not authorize this app.
- `404`: Either the app id is unknown, or the app has no handler for that operation.
- `405`: The app declares this operation under a different method (`method_not_allowed`). Retry with a method from the `Allow` header, which `error.allowedMethods` repeats.
- `500`: App handler threw or violated the capability contract.

---

[API](https://skmtc.dev/charm/apis/charming-api.md) · [All operations](https://skmtc.dev/charm/apis/charming-api/llms.txt) · [OpenAPI document](https://skmtc.dev/charm/apis/charming-api/revisions/a9d06c419b3a?raw)