# EGYM AI agent instructions

Use these instructions before implementing an EGYM API integration.

Beta
AI-agent support for EGYM documentation is currently in beta and under active development. The MCP tools and recommended workflows may change as we improve the experience.

## Recommended workflow

When using an AI agent, follow this workflow:

1. Identify the integration use case from the documented API catalog. Do not invent use-case options.
2. If the request mentions MMS, gym management systems, members, memberships, RFID/NFC, check-ins, products, trainer tasks, notifications, webhooks, or is otherwise ambiguous, start with `MMS API V2` and show the MMS API V2 use cases below.
3. Find the relevant API with `list-apis` if the API is not yet known.
4. Use `get-endpoints` to get a compact endpoint overview for that API.
5. Use `get-endpoint-info` for each endpoint that is part of the implementation.
6. Use `search` with the document names in this guide to load conceptual documentation.
7. Use `get-security-schemes` to retrieve authentication requirements.
8. Use `get-full-api-description` only if the agent needs the complete OpenAPI description, for example to generate a full client.


## MMS API V2 first

For most gym management system integrations, agents should evaluate `MMS API V2` before other APIs.

When the integration use case is unclear, ask the user to choose from the MMS API V2 use cases first:

| MMS API V2 use case | Use for | Relevant endpoint areas |
|  --- | --- | --- |
| Member account management | Creating, listing, retrieving, updating, partially updating, or deleting member accounts | `/api/v2/accounts`, `/api/v2/accounts/{accountId}` |
| Member lookup and membership sync | Looking up members by membership ID, email, RFID, NFC, or syncing membership data | `/api/v2/accounts/membership/{membershipId}`, `/api/v2/accounts/email/{email}`, `/api/v2/accounts/rfid/{rfid}`, `/api/v2/accounts/nfc/{nfc}` |
| Profile picture management | Uploading or deleting member profile images | `/api/v2/accounts/{accountId}/images` |
| Product booking | Retrieving available products, activating or updating product bookings, and deactivating products | `/api/v2/products`, `/api/v2/accounts/{accountId}/products` |
| RFID assignment | Reading, replacing, adding, or removing member RFID assignments | `/api/v2/accounts/{accountId}/rfids` |
| NFC assignment | Reading, assigning, or deleting member NFC tokens | `/api/v2/accounts/{accountId}/nfc` |
| Check-in, checkout, and admission | Sending gym entry, gym exit, or admission verification events | `/api/v2/accounts/{accountId}/checkins`, `/api/v2/accounts/{accountId}/checkouts`, `/api/v2/accounts/{accountId}/admissions` |
| Trainer task management | Creating, listing, retrieving, or updating trainer tasks | `/api/v2/tasks`, `/api/v2/tasks/{taskId}` |
| Webhook subscriptions | Creating, listing, retrieving, updating, deleting, or testing webhook subscriptions | `/api/v2/webhooks`, `/api/v2/webhooks/{id}`, `/api/v2/webhooks/{id}/trigger` |
| Push notifications | Sending notifications to members by account ID or membership ID | `/api/v2/accounts/{accountId}/notifications`, `/api/v2/accounts/membership/{membershipId}/notifications` |
| Member migration from v1 | Migrating member accounts from the legacy MMS API | `/api/v2/migrate` |
| Corporate Fitness member access | Listing Corporate Fitness accounts or verifying Corporate Fitness admission | `/api/v2/accounts/corporate-fitness`, `/api/v2/accounts/{accountId}/admissions` |


If the user confirms that the integration is not related to these MMS API V2 use cases, then continue with the broader API catalog.

## API reference and endpoint details

This guide does not duplicate endpoint schemas or detailed endpoint descriptions.

For implementation work, retrieve details from the API reference:

| Need | Use |
|  --- | --- |
| API names and versions | `list-apis` |
| Endpoint paths and summaries | `get-endpoints` |
| Request body, response codes, parameters, operation description | `get-endpoint-info` |
| Authentication requirements | `get-security-schemes` |
| Complete OpenAPI description | `get-full-api-description` |
| Conceptual guides and tutorials | `search` |


Endpoint names and paths in this guide are examples of how to navigate the documentation. The API reference should be used for the actual request and response details.

## API catalog

| Partner use case | API name | Use for |
|  --- | --- | --- |
| MMS integration | `MMS API V2` | Member account CRUD, profile pictures, products, RFID/NFC, check-ins, webhooks |
| Legacy MMS integration | `MMS API v1` | Deprecated integrations only |
| Equipment server-to-server integration | `Equipment Vendor API (for server-to-server cases)` | Backend-to-backend equipment integrations |
| Equipment standalone client integration | `Equipment Vendor API (for standalone clients)` | Equipment device/client integrations |
| User Connect integration | `OpenAPI definition` | User Connect API integration |
| Data export | `DATA EXPORT API` | Exporting EGYM data |
| Data Hub | `Data Hub API` | Exporting analytics, workout, and measurement data |
| Group classes | `Canonical GroupX Classes API` | Class booking and canonical class data |


## MMS member synchronization

For MMS member data integrations, fetch endpoint details from the MMS API reference and load conceptual documentation in this order:

| Question | Use |
|  --- | --- |
| Which endpoints are needed for member account operations? | `get-endpoints` for the relevant MMS API, then `get-endpoint-info` for each selected account endpoint |
| When should full updates be used? | Search `Push member data to EGYM full update` |
| When should partial updates be used? | Search `Push member data to EGYM partial update` |
| How are profile pictures managed? | Search `Push member data to EGYM Profile picture operations`, then use `get-endpoint-info` for the selected image endpoints |
| What is the EGYM account model? | Search `EGYM Member Account Concept Gym Chain Profile` |
| What are the data privacy rules? | Search `Data privacy framework Gym Data Workout Data` |
| How are conflicts resolved? | Search `Conflict resolution` plus the specific conflict type |
| What are member push best practices? | Search `Push member data to EGYM Best practices` |
| How is authentication done? | Use `get-security-schemes`, then search `Authentication` if more explanation is needed |
| What are the rate limits? | Search `Rate Limits` |


## Endpoint retrieval examples

Use these examples to navigate toward the right documentation. The selected API reference entry provides the implementation details.

| Task | MCP tool pattern |
|  --- | --- |
| Discover account-related endpoints | `get-endpoints` for the relevant MMS API, then filter for account/member operations |
| Implement create/read/update/delete | `get-endpoint-info` for each selected account endpoint |
| Implement full vs partial update | `search("Push member data to EGYM full update")`, `search("Push member data to EGYM partial update")`, then `get-endpoint-info` for selected update endpoints |
| Implement profile picture upload/delete | `search("Push member data to EGYM Profile picture operations")`, then `get-endpoint-info` for selected image endpoints |
| Implement check-in/check-out | `search("Check-in / Check-out")`, then `get-endpoint-info` for selected gym visit endpoints |


## Documentation catalog

Use these page names with the documentation search tool. Load only the pages relevant to the current partner use case.

### General

| Page name | Path | Use for |
|  --- | --- | --- |
| General Info | `general/general-info.md` | Partner entry point and use-case overview |
| Data privacy framework | `general/data-privacy.md` | Legal/data processing model |
| Webhooks | `general/webhooks.md` | Webhook concepts |
| EGYM AI agent instructions | `general/ai-agent-instructions.md` | AI-agent workflow and documentation catalog |


### MMS API v2

| Page name | Path | Use for |
|  --- | --- | --- |
| MMS API Welcome | `mms-api-v2/index.md` | MMS documentation landing page |
| Guide | `mms-api-v2/guide.md` | General MMS integration guide |
| Authentication | `mms-api-v2/authentication.md` | API key authentication |
| Rate Limits | `mms-api-v2/rate-limits.md` | Request throttling |
| Error Codes | `mms-api-v2/errors.md` | API errors |
| Error Handling | `mms-api-v2/error-handling.md` | Error handling guidance |
| EGYM Cloud | `mms-api-v2/egym-cloud.md` | EGYM Cloud and MMS integration context |
| EGYM Member Account Concept | `mms-api-v2/member-account-concept.md` | Account, EGYM member profile, gym chain profile |
| Push member data to EGYM | `mms-api-v2/tutorials/member-account-example.md` | Member CRUD, PUT vs PATCH, picture upload, push best practices |
| Conflict resolution | `mms-api-v2/tutorials/conflicts-resolution.md` | Required 409 conflict handling |
| Membership sync | `mms-api-v2/tutorials/membership-sync.md` | Synchronizing membership data |
| Product booking | `mms-api-v2/tutorials/product-booking.md` | Product activation and booking |
| RFID assignment | `mms-api-v2/tutorials/rfid-assignment.md` | RFID management |
| NFC assignment | `mms-api-v2/tutorials/nfc-assignment.md` | NFC management |
| Check-in and checkout | `mms-api-v2/tutorials/checkin-checkout.md` | Gym entry and exit events |
| Wellpass integration | `mms-api-v2/tutorials/wellpass-integration.md` | Wellpass integration |
| Wellpass check-in | `mms-api-v2/tutorials/wellpass-checkin.md` | Wellpass check-in flow |
| Integration types | `mms-api-v2/tutorials/integration-types.md` | Choosing integration type |
| What's new in v2 | `mms-api-v2/what-new-in-v2.md` | v2 changes |
| Change log | `mms-api-v2/change-log.md` | API changes |