# Mentorly GraphQL API (Developer Summary)

Condensed, agent-friendly summary of the Mentorly API. The full reference with every query, mutation, and type is at https://mentorly.com/developers. The machine-readable OpenAPI description is at https://mentorly.com/openapi.json.

## Endpoint

```
POST https://api.mentorly.co/graphql
Content-Type: application/json
```

Body: `{"query": "...", "operationName": "...", "variables": {...}}` (only `query` is required).

This is the same API the Mentorly web application runs on: anything a user can do in the product, an authorized API consumer can do through this API.

## Authentication

```
Authorization: Bearer mk_live_<prefix>.<secret>
```

- Keys are issued by Mentorly administrators (no self-serve registration). Walkthrough: https://mentorly.com/auth.md
- A key is bound to a Mentorly user; requests behave as that user, capped by the key's scopes.
- Scopes: `read:users`, `write:users`, `read:bookings`, `write:bookings`, `read:matches`, `write:matches`, `read:analytics`, `read:conversations`, `admin`.
- Program context: pass `X-Group-Id: <id>` when the user belongs to more than one program; otherwise the key's configured group is used.

## Rate limits

| Tier | Limit |
|------|-------|
| Standard | 120 requests / minute / key |
| Enterprise | 600 requests / minute / key |

Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. Exceeding the quota returns HTTP 429 with `Retry-After`; back off until the reset time.

## Errors

Top-level GraphQL errors carry a machine-readable `extensions.code`:

| Code | Meaning |
|------|---------|
| `VALIDATION_ERROR` | Input failed model validation; `extensions.details` lists messages |
| `unauthorized` | The authenticated identity may not perform this operation |
| `forbidden` | The API key's scopes do not allow this operation |
| `NOT_FOUND_ERROR` | The referenced resource does not exist |

Every mutation payload also exposes `errors: [String]` and `errorDetails: JSON` for handled business-rule failures. HTTP 200 with content in those fields is a failure, not success.

## Pagination

List fields accept `page` and `per` arguments (1-indexed). Default and maximum page size is 20. Request successive pages until a page returns fewer than `per` items.

## Query constraints

| Constraint | Value |
|------------|-------|
| Maximum query depth | 15 |
| Maximum query complexity | 1000 |
| Maximum page size | 20 |

Schema introspection is disabled in production. Use https://mentorly.com/developers, which is generated from the same schema, with every operation documented.

## What the API covers

- Users and profiles: registration, onboarding, profiles, files, working hours, goals
- Matching: compatibility scoring, previews, staged and bulk matching, activation
- Bookings: session requests, booking, rescheduling, extensions, cancellation, calendar sync
- Conversations: direct and group messaging, files
- Programs (groups): configuration, cohorts, branding, onboarding config, payment settings
- Analytics: engagement, NPS surveys, review sentiment, knowledge gaps, emerging themes, goal analysis
- Content: blog, FAQs, testimonials, case studies, plans, and other CMS content

## Example

```bash
curl -X POST https://api.mentorly.co/graphql \
  -H "Authorization: Bearer $MENTORLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { viewer { id firstName lastName email } }"}'
```

## Support

support@mentorly.co