Skip to content
Emdash Mika Docs

Route Surfaces

Mika has separate route surfaces. Treat the word “route” as ambiguous until you know which surface is involved:

Surface Example Public browser use Owner
Copied Astro pages /cart, /wishlist, /checkout/success, /account Yes, as host pages Host after copy
Copied provider endpoints /api/mika-webhook/[provider] No; provider/service caller only with host verification Host after copy
Copied download interstitial /download/[token] Yes, as a host page; POST confirmation consumes the token Host after copy
Astro Actions actions.mika.cart.add, actions.mika.checkout.start Yes, through HTML forms Host action registry using Mika factory
EmDash plugin JSON routes /_emdash/api/plugins/mika/catalog/sellables, /_emdash/api/plugins/mika/sellables/availability Only safe public reads Mika plugin inside EmDash
Public metadata /llms.txt, /.well-known/mika-agent.json Yes, read-only descriptors Host after copy
Admin action runner /_emdash/api/plugins/mika/.well-known/actions/run No Trusted EmDash/admin flow

The only public plugin JSON reads are:

  • catalog.sellables at route key catalogSellables, path catalog/sellables, with collection, id, and optional locale search params.
  • stock.availability at route key sellableAvailability, path sellables/availability, with sellableId as the search param.

Use Astro Actions for browser mutations by default.

Wrong Versus Right

Section titled “Wrong Versus Right”

Wrong for a public browser cart button:

POST /_emdash/api/plugins/mika/cart/items

That plugin route is non-public and lacks the host browser policy by itself.

Right for the copied storefront:

<form action={actions.mika.cart.add} method="post">
  ...
</form>

The Astro Action runs behind Astro’s action runtime, host guards, and the same Mika API implementation.

Practical Rule

Section titled “Practical Rule”

If the browser is changing cart, wishlist, checkout, account, subscription, webhook, admin, export, delete, or agent-tool state, start from an Astro Action or a host-owned protected endpoint. Do not document a plugin JSON path as a public browser mutation route unless the host has added the missing auth, CSRF, confirmation, idempotency, rate-limit, and provider checks.

HTTP Public Is Not Agent Visibility

Section titled “HTTP Public Is Not Agent Visibility”

Mika operation descriptors also carry agent visibility:

Agent visibility Meaning
public Safe public read metadata such as catalog sellables and stock availability.
trusted Operations a host may project behind auth/session/confirmation policy.
admin Admin operations for EmDash or other trusted operator surfaces.
hidden Service/internal operations such as webhook ingestion.

Do not read these labels as a route publication plan. A trusted descriptor can inform a host-owned ACP, MCP, OpenAPI, or custom agent projection, but Mika does not publish those protected tools by itself.

Section titled “Related Tasks”

External References

Section titled “External References”

Source Anchors

Section titled “Source Anchors”
  • ⓐ ../emdash-mika/src/templates/astro/README.md
  • ⓟ ../emdash-mika/src/api/routes.ts
  • ⓟ ../emdash-mika/src/api/operations.ts
  • ⓟ ../emdash-mika/src/api/route-handlers.ts
  • ⓟ ../emdash-mika/src/api/operation-agent-metadata.ts