Discovery API usage

AppMint exposes its API surface as live, machine-readable docs. The agent's first move on any AppMint integration task is to hit /discover/* for the relevant topic — discovery is always current, while the agent's static instructions and even this documentation can lag. This page documents the pattern, the topic index, and what to do when discovery and your assumptions disagree.

The rule

Before writing AppMint-related code:

curl "$APPMINT_API_URL/discover/01-auth"

This applies to every topic — auth, repository, sites, storefront, CRM, sales channels, delivery, events, messaging. Discovery returns markdown narratives plus enough structure for the agent to generate correct calls. Pair it with the OpenAPI spec for exact request/response shapes:

curl "$APPMINT_API_URL/documentation/json"

Topic index

Pull the live list:

curl "$APPMINT_API_URL/discover/list"

Common topics:

Topic	Covers
01-auth	Customer signin / signup, staff signin, JWT and API-key modes
02-data	Repository CRUD (PUT create, POST find, GET get, POST update-partial, DELETE)
03-sites	Pages, sites, navigation, storefront options
04-storefront	Products, rentals, checkout, payment links
05-crm	Customers, leads, contacts, address books
09-sales-channels	Orders, payouts, affiliates, wallets
11-client	Client-side SDK and integration patterns

The exact list moves over time. discover/list is authoritative.

The pattern

For any AppMint integration the agent goes through this loop:

1. curl /discover/list                  # find the relevant topic
2. curl /discover/<topic>               # read the narrative
3. curl /documentation/json | jq ...    # confirm exact shape
4. Generate code
5. Verify the generated call returns 200

Skipping step 1–3 is the most reliable way to produce broken code — the agent ends up inventing endpoint paths, response shapes, or field names that look plausible but don't exist.

Why discovery wins

• Schema evolves. Endpoints rename, fields move from data.x to data.content.x. Discovery follows.
• Plans gate features. Some endpoints (custom domains, AI features) return 403 with an upgrade prompt depending on plan tier. Discovery describes this.
• Datatypes are tenant-specific. Custom collections defined in your org show up in discovery's repository listings.
• Multi-version installs. Self-hosted AppEngine instances may run an older or newer schema than the SaaS. Discovery reflects the running instance.

What to do when discovery disagrees

If discovery returns something different from what this page or the agent's static instructions say:

1. Trust discovery. Use what it returned, not the cached belief.
2. If you think discovery is wrong, hit the OpenAPI spec to confirm:

   curl "$APPMINT_API_URL/documentation/json" | jq '.paths."/profile/customer/signin"'
   

3. If discovery and OpenAPI agree but contradict your code, the schema changed. Update.
4. If only this documentation disagrees, file an issue against the docs repo. Discovery is the source of truth.

What to do when discovery is unreachable

A workspace might fall back to .vibe/appmint-api.md, a local cached copy session-manager writes when it can't reach AppMint. It's stale by design (only updated on workspace creation and on explicit sync). Use it as a last resort.

If both discovery and the cache are unreachable, prefer asking the builder over guessing.

Worked example

The builder asks: "Add a customer signup form that creates a customer in AppMint."

Without discovery:

Agent invents a /api/customers endpoint. Code 404s.

With discovery:

curl "$APPMINT_API_URL/discover/01-auth"

Agent reads the topic, sees POST /profile/customer/signup with body { email, password, firstName, lastName }. Generates:

async function signup({ email, password, firstName, lastName }) {
  const res = await fetch(`${APPMINT_API_URL}/profile/customer/signup`, {
    method: 'POST',
    headers: { orgid: APPMINT_ORG_ID, 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password, firstName, lastName }),
  });
  return res.json(); // { token, customer }
}

That works first try.

Common discovery topics for app-building

When working in a Vibe Studio workspace, the agent will most often need:

• 01-auth — signin / signup flows.
• 02-data — every CRUD operation hits the repository.
• 03-sites — when scaffolding pages or wiring CMS content.
• 04-storefront — for any e-commerce work.

A workspace building a CRM tool will lean on 05-crm; a delivery app on the delivery topic. The agent learns which topics matter from the workspace's framework and from the builder's prompts.

Caching discovery

Discovery responses are small (a few KB each). The agent fetches fresh on every relevant turn — caching at the agent level isn't worth the complexity. If you're calling discovery from your own tooling, a 60-second TTL is reasonable.

OpenAPI in addition to discovery

Discovery is narrative-first. It explains why and when. OpenAPI (/documentation/json) is structural — request schemas, response schemas, path parameters, status codes. Use both:

• Discovery — for understanding the workflow and conventions.
• OpenAPI — for the exact field types and required vs optional.

The agent generally checks discovery first, then confirms field shapes against OpenAPI when it's about to send a complex body.

Reference

The canonical text for discovery-first behaviour is in agent-zero/AI-INSTRUCTIONS.md § 5. Quote: "AppMint endpoints can evolve. Before writing an auth flow: curl $APPMINT_API_URL/discover/01-auth. Discovery is always current. This document may lag."