Headless API

​

About the Headless API

• Build a custom client (web, mobile, embed) that surfaces a Network’s content to its members
• Build host-facing tools, dashboards, or admin consoles that need data the Admin REST API doesn’t expose
• Power a third-party integration that acts on behalf of a specific user (member, moderator, or host)
• Query exactly the fields you need in a single round trip, including nested associations

​

What’s in the schema today

• Network & branding — Network settings and updates (including landing and home space configuration and feature toggles), the branding theme, custom domains (validate, register, publish, remove), Pinned Links in the navigation menu, payment currencies, the connected Stripe account, and the Network’s own Mighty Networks billing plan and enabled features
• Members — the authenticated viewer (me), the member roster with filtering and single-member lookup; member profile updates, removal, ban, and account deletion; membership role and status (read and update); member-to-member follows; profile social links; custom fields (definitions, options, and member answers) and profile questions
• Spaces & structure — spaces (create, update, delete, reorder, move between collections), space memberships, spaces collections, space templates (read-only), live spaces, featured and welcome pins, and discovery-page gallery sections
• Posts & content — posts, threaded comments, reactions, tags (including bulk member tagging), polls and poll answers, announcements, saved posts, embedded link previews, the ranked member feed, and media assets (including uploads)
• Events — events with recurrence rules, per-occurrence overrides and cancellations, and RSVPs
• Chat — space group chats: list conversations, send and delete messages, mark conversations read, react to messages, and bookmark conversations. Member-to-member direct messages and reply threads are exposed with the member’s explicit consent via the read:chats and write:chats scopes — a token reaches only its own user’s conversations.
• Commerce — payment plans (create, update, publish, unpublish, archive), subscription groups, member subscriptions (list, cancel), one-time purchases (list, void), promo codes, income reports, and gifts with recognition leaderboards
• Courses & learning — courses and coursework (create, update, publish, reorder), member course and video progress, and quizzes (answering, completion, and attempt reporting)
• Growth & onboarding — invites (create, resend, revoke), join requests (approve, reject, bulk update), leads (read-only) and waitlists, the Ambassador program (referral stats and the recruitment announcement), the welcome checklist, and custom onboarding steps
• Marketing & member data — member segments, marketing audiences, and marketing banners
• Moderation & safety — member reports (file, list, clear), the email blocklist, member-to-member blocks, content reporting for posts, comments, and chat messages, and post, prompt, and space muting
• Gamification — badges (definitions and member assignment), daily-visit streaks, points balances, and gift leaderboards
• Notifications — the viewer’s notification inbox (list, mark read or unread) and notification delivery settings
• Automation & integrations — automation rules with execution logs, outbound webhooks, and OAuth application management
• Search — cross-entity search with typed result filtering

​

Endpoint

https://api.mn.co/networks/:network_id_or_subdomain/graphql

• The Network’s numeric ID (e.g. 12345)
• The Network’s subdomain (e.g. my-community for my-community.mn.co)

curl https://api.mn.co/networks/my-community/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { me { id name } }"
  }'

const response = await fetch(
  `https://api.mn.co/networks/${NETWORK}/graphql`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: `query { me { id name } }`
    })
  }
);

const { data, errors } = await response.json();

import requests

response = requests.post(
    f"https://api.mn.co/networks/{NETWORK}/graphql",
    headers={
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    },
    json={"query": "query { me { id name } }"}
)

payload = response.json()

​

Authentication

​

Create an OAuth application

1. Sign in as a host or admin and open Network Admin.
2. Go to Integrations > OAuth Applications and click New OAuth Application.
3. Provide a name, choose a client type (public or confidential), register redirect URIs, and select the scopes your app needs.
4. Mighty issues a Client ID and (for confidential clients) a Client Secret.

​

Authorization Code flow

1. Redirect the user to the authorization endpoint. OAuth endpoints live on the Network’s community host, not on api.mn.co:
   https://:network_subdomain.mn.co/oauth/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=YOUR_REDIRECT_URI
     &scope=SPACE_SEPARATED_SCOPES
     &state=RANDOM_OPAQUE_STRING
     &code_challenge=PKCE_CHALLENGE
     &code_challenge_method=S256
   
   The canonical endpoint URLs are also advertised at https://:network_subdomain.mn.co/.well-known/oauth-authorization-server (RFC 8414).
2. The user signs in (if needed) and approves the requested scopes. Mighty redirects back to your redirect_uri with a code and the state you sent. Verify that the returned state exactly matches the cryptographically random value you generated for this request — if it doesn’t, reject the callback and do not exchange the code. This is your CSRF defense.
3. Exchange the code for an access token:
   curl https://:network_subdomain.mn.co/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code" \
     -d "code=AUTH_CODE_FROM_REDIRECT" \
     -d "redirect_uri=YOUR_REDIRECT_URI" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "code_verifier=PKCE_VERIFIER"
   
   The response contains an access_token, refresh_token, expires_in, and the granted scope:
   {
     "access_token": "eyJhbGciOi...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "def50200...",
     "scope": "read:network write:posts"
   }
   
4. Pass the access token on every GraphQL request:
   Authorization: Bearer eyJhbGciOi...
   
5. When the access token expires, exchange the refresh token for a new one using grant_type=refresh_token against the same /oauth/token endpoint.

​

Token scope and permissions

​

Why GraphQL

• One endpoint, many shapes. A mobile feed view and a desktop sidebar can hit the same query and select different fields. Same for a CRM sync job and a Discord bot — they ask for what they need and ignore the rest.
• Typed schema. Every field, argument, and return type is described in the schema and discoverable via introspection — no out-of-band docs required to know what’s possible.
• Composable queries. Fetch a post, its author, the author’s spaces, and the viewer’s permissions on each — in a single round trip. Build the view the app needs, not the view the API designer guessed at.
• Forward-compatible by default. New fields and types can be added without breaking existing clients, because clients only see the fields they explicitly ask for. The schema can grow alongside the use cases we haven’t thought of yet.

• graphql.org — language overview, learning resources, and tooling
• GraphQL specification — the formal language and execution spec

​

Relay conventions

• Nodes are addressable by a globally unique id and reachable through the top-level node(id: ID!) field, per the GraphQL Global Object Identification spec.
• Lists are paginated using cursor-based Connection types (edges, node, pageInfo) — see also API Pagination for general guidance.
• Mutations follow the Relay input/payload pattern: a single input argument and a payload type that includes the mutated node(s).

• Relay docs — client framework guide
• GraphQL Server Specification — the conventions the schema follows
• Cursor Connections Specification — pagination contract

​

Making a Request

POST /networks/my-community/graphql HTTP/1.1
Host: api.mn.co
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
User-Agent: my-app/1.0 (+https://example.com)

{
  "query": "query Post($id: ID!) { network { post(idOrSlug: $id) { id title author { id name } } } }",
  "variables": { "id": "12345" }
}

{
  "data": {
    "network": {
      "post": {
        "id": "12345",
        "title": "Welcome to the network",
        "author": { "id": "678", "name": "Jane" }
      }
    }
  }
}

{
  "data": null,
  "errors": [
    {
      "message": "Post not found",
      "path": ["post"],
      "extensions": { "code": "NOT_FOUND" }
    }
  ]
}

​

Schema and Introspection

​

GraphiQL Explorer

https://:network_subdomain.mn.co/admin/headless-api/explorer

​

Fetching the schema

GET https://api.mn.co/networks/:network_id_or_subdomain/graphql/schema

curl https://api.mn.co/networks/my-community/graphql/schema > schema.graphql

​

Introspection (alternative)

query {
  __schema {
    types {
      name
      kind
    }
  }
}

# Install: npm i -g get-graphql-schema
get-graphql-schema \
  --header "Authorization=Bearer YOUR_ACCESS_TOKEN" \
  https://api.mn.co/networks/my-community/graphql \
  > schema.graphql

# Install: https://www.apollographql.com/docs/rover/
APOLLO_HEADERS='{"Authorization":"Bearer YOUR_ACCESS_TOKEN"}' \
  rover graph introspect https://api.mn.co/networks/my-community/graphql \
  > schema.graphql

curl https://api.mn.co/networks/my-community/graphql \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"query IntrospectionQuery { __schema { queryType { name } mutationType { name } subscriptionType { name } types { ...FullType } directives { name description locations args { ...InputValue } } } } fragment FullType on __Type { kind name description fields(includeDeprecated: true) { name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason } inputFields { ...InputValue } interfaces { ...TypeRef } enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __InputValue { name description type { ...TypeRef } defaultValue } fragment TypeRef on __Type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } }"}' \
  > schema.json

​

Rate Limits

​

Errors

​

Headless API vs. Admin API

​

Support