<!-- Source: https://www.wappi.dev/ai -->

# WAPPI AI Quick Reference

A compact summary of WAPPI conventions for AI coding agents (Cursor, Claude Code, Copilot and others). Each item links to its full page. For the complete docs as one markdown file, read [https://www.wappi.dev/llms-full.txt](https://www.wappi.dev/llms-full.txt). The index is at [https://www.wappi.dev/llms.txt](https://www.wappi.dev/llms.txt) and every page is available as markdown by adding `.md` to its URL.

## Endpoint naming

Endpoints are named `Namespace_EndpointName_Major_Minor_Patch`, for example `User_UpdateDetails_2_3_4`. The namespace works like a microservice (e.g. `User`), the endpoint name describes what it does, and the version has three numbers. The request Body type is named `Namespace_EndpointName_Major_Minor_Patch__Body`, e.g. `User_GetUserData_1_0_0__Body`. [Namespaces](https://www.wappi.dev/namespaces)

## Folder layout

Each endpoint lives at `API/<Namespace>/<EndpointName>/<x.y.z>/index.ts`, with an `index.spec.ts` test from the template. Shared helpers live in `API/CoreHelpers/` (e.g. `types.ts`, `logging.ts`). Always create endpoints and versions with the CLI, not by hand. [Namespaces](https://www.wappi.dev/namespaces)

```text
API/
  Core/Login/1.0.0/index.ts        // Core_Login_1_0_0
  User/GetUserData/1.0.0/index.ts  // User_GetUserData_1_0_0
  CoreHelpers/types.ts
  CoreHelpers/logging.ts
```

## Registering endpoints

Endpoints are registered in `API/index.ts` under `exports.Endpoints`, which also has `LoginRequired` and `PublicApiEndpoint` lists. A webhook goes in `exports.Endpoints` only, not in `LoginRequired` or `PublicApiEndpoint`, because the sender can't log in or send an API key. [Webhooks](https://www.wappi.dev/webhooks)

```typescript
// API/index.ts
exports.Endpoints = {
  ...
  Webhook_StripeCheckout_1_0_0: true,
  // NewEndpointGoesHere
}
```

## Webhooks

Put webhooks in the `Webhook` namespace, so names start with `Webhook_` (e.g. `API/Webhook/StripeCheckout/1.0.0/index.ts` is `Webhook_StripeCheckout_1_0_0`). The sender POSTs its own JSON to `https://<your-api-url>/Webhook_StripeCheckout_1_0_0`, with no `query`/`data` wrapper. The Body holds the parsed JSON plus the default body data, `body.headers` (request headers) and `body.raw` (the raw request body as a string). Always verify signatures against `body.raw`. The returned `statusCode` is the HTTP status the sender gets: return 200 when a retry can't help, 4xx/5xx only when a retry could succeed, and make handlers safe to run twice. [Webhooks](https://www.wappi.dev/webhooks)

## Calling an endpoint (wappi-fe)

A request names the endpoint in `query` and sends its Body in `data`. Optional `results` include or exclude fields on the server (WAPPI Query Language). [Request](https://www.wappi.dev/frontend-integration/request), [Query Language](https://www.wappi.dev/query-language)

```typescript
import { request } from 'wappi-fe'

const response = await request(WAPPI_CONFIG, {
  name: 'Get user info',                // label shown in the network tab
  query: 'NameSpace_FunctionName_1_0_0', // endpoint name
  data: {},                             // typed as NameSpace_FunctionName_1_0_0__Body
  results: { name: 'user', include: [{ name: 'userName', key: 'name' }] }, // optional
  authRequired: true,                   // optional, depends on the endpoint
})
```

## Default Body data

Every endpoint function receives a Body parameter that includes `correlationId`, `headers` and `env` (`localhost | dev | stage | prod`). Authenticated endpoints also get `auth`, the data returned by your `Core_Login` endpoint. [Body Data](https://www.wappi.dev/body-data), [Auth Keys](https://www.wappi.dev/security/auth-keys)

## Versioning

Every endpoint version is self-contained. Create a new version with `npx wappi c` and pick the endpoint; you can copy it and choose a major, minor or patch bump. Major = breaking, minor = recommended update, patch = fix. Keep old versions working until logs show they are unused. [Versioning](https://www.wappi.dev/versioning)

## CLI commands

Run with `npx wappi <command>`. [CLI Commands](https://www.wappi.dev/cli-commands)

```bash
wappi init    (i)  # initialise WAPPI, required for other commands
wappi run     (r)  # run locally on the port in wappi.json
wappi create  (c)  # new endpoint or new version from templates
wappi delete  (d)  # delete an endpoint version and namespace
wappi build   (b)  # build for running locally and testing
wappi test    (t)  # run tests, optionally for one endpoint: wappi t Core_Login_1_0_0
wappi lint    (l)  # eslint, based on .eslintrc.json
wappi watch   (w)  # watch the API folder, works with wappi run
wappi update  (u)  # update node modules to latest
wappi help    (h)  # show the commands menu
```

## Testing

Jest is set up out of the box. Every endpoint has an `index.spec.ts`; extend it when you add code. Run `npx wappi t` for everything or `npx wappi t Test_Something_1_0_0` for one endpoint. [Testing](https://www.wappi.dev/testing)

## API documentation

`wappi run` writes `<package name>-Internal-openAPI-spec.json` (all endpoints) and `<package name>-Public-openAPI-spec.json` (endpoints in `exports.PublicApiEndpoint`) to the project root, using each endpoint's `README.md`, `types.ts` and optional `docExample` in `_data/successData.ts`. [API Documentation](https://www.wappi.dev/api-documentation)

## Logging

Every endpoint runs inside a `try / catch` and errors are logged automatically, so always throw errors. Customise log output in `/API/CoreHelpers/logging.ts`. Set `SHOW_LOGS=false` in production. [Logging](https://www.wappi.dev/logging)

## Config and environment

Project settings are in `wappi.json` (apiKey, authRotation, domains, private, port, prisma, ...). Environment variables go in `.env`, kept in sync with `.env.example` (ENVIRONMENT, SHOW_LOGS, AUTH_KEY_CURRENT, AUTH_KEY_PREVIOUS, FRONTEND_PROJECT_PATHS). A health check is built in at `/healthcheck`. [Configuration](https://www.wappi.dev/configuration), [Environment Variables](https://www.wappi.dev/environment-variables), [Health Checks](https://www.wappi.dev/health-checks)

## Rules-file snippets

Copy one of these into your project so your coding agent uses the WAPPI docs.

### AGENTS.md / CLAUDE.md

```markdown
## WAPPI
This project uses the WAPPI API framework (npm: wappi).
Before writing or changing WAPPI code, read https://www.wappi.dev/llms-full.txt
(index: https://www.wappi.dev/llms.txt, quick reference: https://www.wappi.dev/ai.md).
- Endpoints: API/<Namespace>/<EndpointName>/<x.y.z>/index.ts, named Namespace_EndpointName_X_Y_Z
- Create endpoints and versions with `npx wappi c`, never by hand
- Run tests with `npx wappi t <EndpointName>`
```

### .cursor/rules/wappi.mdc

```markdown
---
description: WAPPI API framework conventions
globs: API/**/*.ts
alwaysApply: false
---
This project uses WAPPI. Read https://www.wappi.dev/llms-full.txt for the full docs
(quick reference: https://www.wappi.dev/ai.md).
Follow the Namespace_EndpointName_X_Y_Z naming and API/<Namespace>/<EndpointName>/<x.y.z>/ layout.
Use `npx wappi c` to create endpoints or versions and `npx wappi t` to test.
```

### .github/copilot-instructions.md

```markdown
This project uses the WAPPI API framework. Use https://www.wappi.dev/llms-full.txt as the reference
for endpoint naming, folder layout, CLI commands, versioning and testing.
```

URL: https://www.wappi.dev/ai