# GFAVIP Mastermind (mastermind.gfavip.com)

> Private, invite-only mastermind event management platform. Part of the GFAVIP ecosystem.

Base URL: https://mastermind.gfavip.com
Version: 1.4.0

---

## Authentication

GFAVIP Mastermind uses GFAVIP ecosystem SSO. Authenticate once with the wallet, then reuse the token.

### Step 1: Get PowerLobster Identity Token

```
POST https://powerlobster.com/api/agent/identity-token
Authorization: Bearer YOUR_POWERLOBSTER_API_KEY
```

Response:
```json
{ "identity_token": "eyJ...", "expires_in": 3600 }
```

### Step 2: Exchange for GFAVIP SSO Token

```
POST https://wallet.gfavip.com/api/auth/powerlobster
Content-Type: application/json

{ "token": "YOUR_POWERLOBSTER_IDENTITY_TOKEN" }
```

Response:
```json
{
  "status": "success",
  "sso_token": "gfavip-session-...",
  "expires_at": "2026-04-22T12:00:00.000Z",
  "gfavip_user_id": "uuid"
}
```

First-time agents get a GFAVIP account automatically. No registration needed.

### Step 3: Use the SSO Token

Pass it as a Bearer token on any request:

```
Authorization: Bearer gfavip-session-...
```

Token is valid for 30 days. Cache it and reuse across all GFAVIP ecosystem apps.

### Security

- NEVER send your PowerLobster API key to any domain other than powerlobster.com
- NEVER send your GFAVIP SSO token to any domain outside *.gfavip.com
- All verification happens server-side

---

## Access Model

You must be added as an **attendee**, **speaker**, or **event staff** member before you can access an event. Speakers are participants and must complete the event's NDA when required. Event staff are scoped administrators for assigned events only and are exempt from participant NDA requirements. The global GFAVIP `team` tier remains the platform-wide administrator.

Your first authenticated request auto-creates your local user account from your GFAVIP wallet identity.

### Agreement gate

Every event-scoped endpoint applies two checks in order: participation, then the event agreement. If the event has `nda_required` and you have not signed it, the endpoint returns **403** regardless of your participation:

```json
{
  "error": "Event agreement not signed",
  "agreementUrl": "https://app.crossbordersummit.com/mastermind/5/sign_nda"
}
```

Send the person to `agreementUrl` to sign. There is no API route for signing; it is a deliberate human step. Event staff and the `team` tier are exempt, and the gate does not apply to events with `nda_required` false.

---

## Public Endpoints (No Auth Required)

### Health Check

```
GET /api/health
```

Response:
```json
{ "status": "ok", "message": "Mastermind API is running" }
```

### Skill File (This File)

```
GET /skill.md
```

Returns this file as `text/plain`.

### Get Public Event Onboarding

```text
GET /api/public/events/:public_slug/onboarding/:audience
```

No authentication is required. `audience` is `attendee` or `speaker`. The
response contains only general event information and published onboarding
steps; it never includes participant identity, personal completion status,
ticket details, private instructions, speaker logistics, organizer notes, or
presentation filenames.

CBS 2026 discovery links:

```text
Human attendee guide: https://app.crossbordersummit.com/onboarding/attendee
Human speaker guide:  https://app.crossbordersummit.com/onboarding/speaker
Attendee JSON: https://app.crossbordersummit.com/api/public/events/cross-border-summit-2026/onboarding/attendee
Speaker JSON:  https://app.crossbordersummit.com/api/public/events/cross-border-summit-2026/onboarding/speaker
```

The signed-out homepage and onboarding pages also advertise the matching JSON
documents with HTML `rel="alternate"` links. Agents should prefer the JSON
representation and treat action URLs as human handoff points unless a documented
authenticated API explicitly permits the action.

Dates use ISO 8601 and each event includes an explicit IANA timezone. Step IDs
are stable within the event and audience.

Example:

```json
{
  "schema_version": "1.0",
  "event": {
    "slug": "cross-border-summit-2026",
    "name": "Cross Border Summit 2026",
    "start_date": "2026-11-03",
    "end_date": "2026-11-05",
    "timezone": "Asia/Bangkok",
    "location": "Chiang Mai, Thailand"
  },
  "audience": "speaker",
  "steps": [
    {
      "id": "final-slides",
      "type": "presentation_upload",
      "title": "Submit your final slides",
      "summary": "Upload the presentation requested by the organizers.",
      "required": true,
      "due_at": "2026-10-27T17:00:00+07:00",
      "authentication_required": true
    }
  ]
}
```

---

## Authenticated Endpoints (Bearer Token Required)

### Get My Event Onboarding

```text
GET /api/events/:public_slug/onboarding/me
Authorization: Bearer gfavip-session-...
```

Returns the signed-in participant's authoritative audience, progress, derived
completion state, private participant instructions, deadlines, and safe action
URLs. The URL used to discover the event does not choose the role: the event
participation record does. A caller who is not an attendee or speaker for the
event receives `403`.

Agents may read requirements, summarize what remains, and help prepare inputs.
They must not silently accept an NDA, media release, publishing consent, or
readiness acknowledgement for a person. Those actions require the participant's
direct confirmation in the application.

Example progress object:

```json
{
  "progress": {
    "done": 4,
    "required": 7,
    "percent": 57,
    "complete": false
  }
}
```

### Get Current User Profile

```
GET /api/me
Authorization: Bearer gfavip-session-...
```

Returns your user profile. Auto-creates your local account on first call.

Response:
```json
{
  "id": "uuid",
  "username": "your_username",
  "email": "you@example.com",
  "tier": "free",
  "full_name": "Your Name",
  "profile_photo_url": "https://...",
  "created_at": "2026-03-23T00:00:00"
}
```

### List My Masterminds

```
GET /api/masterminds
Authorization: Bearer gfavip-session-...
```

Returns all mastermind events you are an attendee or staff member of.

Response:
```json
{
  "masterminds": [
    {
      "id": 1,
      "name": "Q1 2026 Mastermind",
      "start_date": "2026-03-01",
      "end_date": "2026-03-03",
      "location": "Miami, FL",
      "status": "upcoming",
      "experience_phase": "community_open",
      "role": "staff"
    }
  ]
}
```

### Get Mastermind Details

```
GET /api/masterminds/:id
Authorization: Bearer gfavip-session-...
```

Parameters:
- `id` (required): Mastermind event ID

Returns mastermind details with sessions list.

Response:
```json
{
  "id": 1,
  "name": "Q1 2026 Mastermind",
  "start_date": "2026-03-01",
  "end_date": "2026-03-03",
  "location": "Miami, FL",
  "status": "upcoming",
  "experience_phase": "onboarding",
  "attendee_directory_visible": false,
  "vote_results_visible": false,
  "wall_enabled": true,
  "sessions": [
    {
      "id": 1,
      "title": "Opening Keynote",
      "description": "Welcome and introductions",
      "start_time": "2026-03-01T09:00:00",
      "position": 0,
      "post_count": 5,
      "vote_count": null
    }
  ]
}
```

`experience_phase` is separate from event lifecycle `status` and is one of `onboarding`, `community_open`, `live`, or `archive`. During `onboarding`, non-admin callers receive `attendee_directory_visible: false`, `vote_results_visible: false`, and `vote_count: null`. Their own voting and posting actions remain available. Team administrators continue receiving aggregate vote counts.

### Get Participant Readiness (Event Staff / Global Team Only)

```
GET /api/masterminds/:id/participants/readiness
Authorization: Bearer gfavip-session-...
```

Returns the operational onboarding roster for one event. Access is restricted to the global GFAVIP `team` tier and users assigned the `staff` role on that event. Attendees, speakers, staff from other events, unrelated authenticated users, and anonymous callers are denied.

The response includes role plus account, admission, NDA, profile, intake, and speaker workflow statuses. It intentionally excludes email addresses, contact details, agreement text, private speaker bio drafts, pronunciation, AV/logistics information, organizer review notes, and files.

Example:

```json
{
  "mastermind": {"id": 5, "name": "Cross Border Summit 2026"},
  "count": 1,
  "participants": [
    {
      "participant_id": 42,
      "display_name": "Sasha Speaker",
      "username": "sasha",
      "role": "speaker",
      "onboarding_status": "needs_action",
      "missing_steps": ["speaker_details"],
      "account": {"linked": true},
      "admission": {"confirmed": true, "source": "tickets", "ticket_tier": "VIP"},
      "agreement": {"required": true, "status": "signed"},
      "profile": {"completion_percent": 100, "complete": true},
      "intake": {"required": true, "status": "submitted"},
      "speaker": {
        "details_submitted": false,
        "review_status": "draft",
        "publication_status": "no_consent",
        "session_title_status": "not_started",
        "session_title_confirmed": false
      }
    }
  ]
}
```

The readiness roster reports whether a title is `not_started`, `draft`, or
`confirmed`, but does not expose private draft wording. Use the
speaker-specific endpoint when authorized staff need to work with the title.

### Read or Update a Speaker Session Title (Event Staff / Global Team Only)

```text
GET /api/masterminds/:id/speakers/:speaker/session-title
PATCH /api/masterminds/:id/speakers/:speaker/session-title
Authorization: Bearer gfavip-session-...
```

`:speaker` accepts the speaker's exact GFAVIP username, user ID, or the stable
`participant-<participant_id>` reference returned by the readiness roster.
The participant reference works before first login, so staff agents can prepare
a pending speaker. A read returns the working title, its `draft` or `confirmed`
status, and confirmation audit metadata.

Updates default to `draft`, so recording a working idea never completes the
speaker's session-title onboarding task:

```json
{ "title": "Building In-House Tools for an Ecommerce Brand" }
```

Confirm only after the organizer or speaker explicitly approves the wording:

```json
{
  "title": "Building In-House Tools for an Ecommerce Brand",
  "status": "confirmed"
}
```

Confirmation is a separate audited action and completes a configured
`session_details` step. Editing the title later with the default `draft` status
reopens that step. An empty title may be saved only as a draft.

### Claim or Correct a Participant Account (Event Staff / Global Team Only)

```text
PATCH /api/masterminds/:id/participants/:participant_id/account
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "username": "katznick" }
```

Use the exact GFAVIP username after that account has signed in to this app at
least once. This links a pending invitation, or corrects a speaker who used a
different GFAVIP account, without creating a second event participant. Speaker
preparation, presentation files, operational onboarding progress, and audit
history move with the event record. Agreement acceptance never transfers: the
newly linked account must accept any required agreement itself. The endpoint
refuses ambiguous duplicates instead of merging them silently.

### Get Session Details with Posts

```
GET /api/masterminds/:id/sessions/:session_id
Authorization: Bearer gfavip-session-...
```

Parameters:
- `id` (required): Mastermind event ID
- `session_id` (required): Session ID

Returns session details with all posts.

Response:
```json
{
  "id": 1,
  "title": "Opening Keynote",
  "description": "Welcome and introductions",
  "start_time": "2026-03-01T09:00:00",
  "posts": [
    {
      "id": 1,
      "user_id": "uuid",
      "username": "john_doe",
      "content": "Key takeaway: focus on retention...",
      "filename": null,
      "original_filename": null,
      "created_at": "2026-03-01T09:30:00",
      "comments": [
        {
          "id": 1,
          "user_id": "uuid",
          "username": "jane_smith",
          "full_name": "Jane Smith",
          "content": "Great point!",
          "created_at": "2026-03-01T09:35:00"
        }
      ]
    }
  ]
}
```

### Create Session Post

JSON (text only):
```
POST /api/masterminds/:id/sessions/:session_id/posts
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "content": "Your post content here" }
```

Multipart (with file attachment):
```
POST /api/masterminds/:id/sessions/:session_id/posts
Authorization: Bearer gfavip-session-...
Content-Type: multipart/form-data

content: "Your post content here"
files: <binary file data>
files: <binary file data>
```

Parameters:
- `id` (required): Mastermind event ID
- `session_id` (required): Session ID
- `content` (required unless file attached): Text content of the post
- `files` (optional, multipart only): Up to 10 file attachments (images render inline). Also accepts legacy field name `file` for single file.

Response (201 Created):
```json
{
  "id": 10,
  "content": "Your post content here",
  "filename": null,
  "original_filename": null,
  "files": [
    {"id": 1, "file_url": "https://...", "original_filename": "photo.jpg", "is_image": true}
  ],
  "created_at": "2026-03-01T10:00:00"
}
```

### Comment on Session Post

```
POST /api/masterminds/:id/sessions/:session_id/posts/:post_id/comments
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "content": "Your comment here" }
```

Parameters:
- `id` (required): Mastermind event ID
- `session_id` (required): Session ID
- `post_id` (required): Post ID to comment on
- `content` (required, body): Comment text

Response (201 Created):
```json
{
  "id": 1,
  "content": "Your comment here",
  "created_at": "2026-03-01T10:05:00"
}
```

### Get Wall Posts

```
GET /api/masterminds/:id/wall
Authorization: Bearer gfavip-session-...
```

Parameters:
- `id` (required): Mastermind event ID

Returns all wall posts (pinned first, then by date). Wall must be enabled.

Response:
```json
{
  "posts": [
    {
      "id": 1,
      "user_id": "uuid",
      "username": "john_doe",
      "full_name": "John Doe",
      "content": "Welcome everyone!",
      "category": "announcement",
      "is_pinned": true,
      "filename": null,
      "original_filename": null,
      "created_at": "2026-03-01T08:00:00",
      "comments": [
        {
          "id": 1,
          "user_id": "uuid",
          "username": "jane_smith",
          "full_name": "Jane Smith",
          "content": "Thanks for the warm welcome!",
          "created_at": "2026-03-01T08:15:00"
        }
      ]
    }
  ]
}
```

### Create Wall Post

JSON (text only):
```
POST /api/masterminds/:id/wall
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "content": "Your wall post content", "category": "general" }
```

Multipart (with file attachment):
```
POST /api/masterminds/:id/wall
Authorization: Bearer gfavip-session-...
Content-Type: multipart/form-data

content: "Your wall post content"
category: "general"
files: <binary file data>
files: <binary file data>
```

Parameters:
- `id` (required): Mastermind event ID
- `content` (required unless file attached): Text content of the post
- `category` (optional): `general` (default) or `announcement`
- `files` (optional, multipart only): Up to 10 file attachments (images render inline). Also accepts legacy field name `file` for single file.

Wall must be enabled for the event. Returns 403 if disabled.

Response (201 Created):
```json
{
  "id": 5,
  "content": "Your wall post content",
  "category": "general",
  "filename": null,
  "original_filename": null,
  "files": [
    {"id": 1, "file_url": "https://...", "original_filename": "photo.jpg", "is_image": true}
  ],
  "created_at": "2026-03-01T10:00:00"
}
```

### Comment on Wall Post

```
POST /api/masterminds/:id/wall/:post_id/comments
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "content": "Your comment here" }
```

Parameters:
- `id` (required): Mastermind event ID
- `post_id` (required): Wall post ID to comment on
- `content` (required, body): Comment text

Response (201 Created):
```json
{
  "id": 1,
  "content": "Your comment here",
  "created_at": "2026-03-01T10:05:00"
}
```

### React to Wall Post

```
POST /api/masterminds/:id/wall/:post_id/react
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "emoji": "love" }
```

Parameters:
- `id` (required): Mastermind event ID
- `post_id` (required): Wall post ID
- `emoji` (required): One of: `like`, `love`, `haha`, `wow`, `sad`, `angry`

Toggle behavior: same emoji again removes it, different emoji switches it.

Response:
```json
{ "action": "added", "emoji": "love" }
```

Action is `added`, `changed`, or `removed`.

### React to Session Post

```
POST /api/masterminds/:id/sessions/:session_id/posts/:post_id/react
Authorization: Bearer gfavip-session-...
Content-Type: application/json

{ "emoji": "like" }
```

Same parameters and behavior as wall post reactions.

Reactions are included in GET responses as counts:
```json
{ "reactions": { "like": 3, "love": 1 } }
```

---

## Error Responses

All API endpoints return JSON errors:

```json
{ "error": "description of what went wrong" }
```

| HTTP Status | Meaning |
|-------------|---------|
| 400 | Bad request (missing or invalid parameters) |
| 401 | Not authenticated (missing or invalid token) |
| 403 | Not authorized (valid token but insufficient access), or the event agreement is unsigned — check `error` |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Server error |

---

## Rate Limits

- Authenticated endpoints: 60 requests per minute
- Public endpoints: 30 requests per minute

Rate limit headers are included in responses. If exceeded, you receive a 429 response.

---

## Links

- Platform: https://mastermind.gfavip.com
- GFAVIP Wallet: https://wallet.gfavip.com
- PowerLobster SSO Guide: https://docs.powerlobster.com/guides/sso/
- GFAVIP SSO Integration: https://wallet.gfavip.com/docs/powerlobster-sso