Headless API

Documentation Index

Fetch the complete documentation index at: https://docs.mightynetworks.com/llms.txt

Use this file to discover all available pages before exploring further.

​

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 — settings, branding, billing plan, enabled features, available space features and templates, payment currencies, Stripe connection state
• Spaces — spaces, spaces collections, and space templates; create, update, and list
• Posts — posts and post content (including embedded links, assets, and post tags); create, update, delete, fetch by id or slug, list per network or per space
• Comments — threaded comments on posts; create, update, delete, list
• Reactions — reactions and reaction groups on supported targets; create and delete
• Events — events, event instances, and RSVPs; create, update, delete, and list across the network or a space
• Polls — poll and poll choice types surfaced through post content
• Notifications — list and mark-as-read for the viewer’s notifications
• Search — cross-entity search with typed result filtering
• Assets — images attached to posts

​

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 } }"
  }'

​

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, shown once.

​

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.
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:posts 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/public/graphiql

​

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

​

Rate Limits

​

Errors

​

Headless API vs. Admin API

​

Support