Unlock the Power of
Trusted Networks.

The Mutle API provides programmatic access to the world's first multi-hop trust graph. Integrate professional identity, verified connections, and social capital flow directly into your product.

https://mutl.buzzchat.site/api/v1

Version 1.3.0

User Authentication

OAuth 2.0 Authorization Code Flow for user-level data.

Use this flow when your app needs to act on behalf of a specific Mutle user — such as reading their profile, connections, or sending introductions.

Redirect the user to Mutle's authorization page

GET https://mutl.buzzchat.site/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=r_liteprofile r_network w_messages
  &response_type=code
  &state=RANDOM_STATE_STRING

Exchange the authorization code for an access token

POST https://mutl.buzzchat.site/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_REDIRECT
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

Token response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "rt_9f8h2k...",
  "scope": "r_liteprofile r_network"
}

Access tokens are valid for 24 hours. Refresh tokens are valid for 30 days. Use the refresh token flow to get a new access token without requiring the user to re-authorize.

Machine-to-Machine Auth

Access public data and graph logic without a user session.

For background tasks, data syncs, or using the Trust Graph logic on public profiles, use the Client Credentials Flow. This uses your Client ID and Secret directly — no user redirect required.

Request an app token

curl -X POST https://mutl.buzzchat.site/api/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=r_search r_graph"

Tokens from the Client Credentials flow have no user context (uid is null). Endpoints that act on behalf of a user — such as /me, /connections, /network/path, /posts, /messages, or /intros — require the Authorization Code flow and will return a 401/403 style error if you call them with an app token.

Using Your Token

How to authenticate every API request.

Pass your access token as a Bearer token in the Authorization header on every request.

curl

curl https://mutl.buzzchat.site/api/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

JavaScript (fetch)

const res = await fetch("https://mutl.buzzchat.site/api/v1/me", {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});
const user = await res.json();

Scopes & Data Formats

Fine-grained permissions and their corresponding data.

Scope	Data access	Tier
r_liteprofile	ID, name, headline, photo, location	Standard
r_emailaddress	Primary verified email address	Standard
r_network	Connection list, trust scores, connected dates	Standard
r_search	Public search index, relevance scores	Standard
r_suggestions	Ranked 'People You May Know' data	Standard
r_insights	Aggregated network & engagement statistics	Standard
w_member_social	Post status updates, content attachments	Standard
r_graph	Full adjacency matrix, trust path chains	Restricted
w_intros	Create and manage introduction requests	Restricted
w_messages	Send messages within trusted connections	Restricted
ext_webhooks	Receive JSON event payloads via POST	Restricted

Rate Limits

Request quotas by application tier.

Tier	Requests / day	Restricted API access	How to get
Standard	1,000	No	Self-serve — default for all new apps
Elevated	10,000	On approval	Request via app console
Partner	100,000	Yes	Apply for Partner Program

Rate limit headers

Every response includes these headers so you can monitor your usage:

X-RateLimit-LimitYour total daily quota

X-RateLimit-RemainingRequests remaining in the current window

X-RateLimit-ResetUnix timestamp when the quota resets

When you exceed your quota, the API returns 429 Too Many Requests. The X-RateLimit-Reset header tells you when to retry.

Error Handling

Consistent error format across all endpoints.

All errors return a JSON body with a consistent structure. Always check the code field for machine-readable error classification.

Error response format

{
  "success": false,
  "error": "This person is not currently accepting introductions.",
  "code": "INTROS_DISABLED",
  "status": 403
}

Common error codes

400VALIDATION_ERRORMissing or invalid request parameters

401UNAUTHORIZEDMissing or expired access token

403FORBIDDENValid token but insufficient scope or permission

403BLOCKEDRequester or target has a block relationship

403INTROS_DISABLEDTarget user has introductions turned off

404NOT_FOUNDResource does not exist or is private

409INTRO_LIMIT_REACHEDDuplicate intro request within 30-day window

429RATE_LIMITEDDaily API quota exceeded for this application

API Reference

Core endpoints for interacting with Mutle data.

GET/me

r_liteprofile

Returns the identity of the user who authorized your application. This is the primary endpoint for 'Sign In with Mutle' implementations.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Response Example

{
  "id": "usr_9482hfk3",
  "displayName": "Alex Rivera",
  "headline": "Senior Software Architect at CloudScale",
  "photoURL": "https://mutle.com/cdn/p/alex.jpg",
  "location": "San Francisco, CA",
  "industry": "Information Technology",
  "trustScore": 84
}

GET/connections

r_network

Lists all confirmed 1st-degree connections for the authenticated user. Includes basic profile data and trust metadata for each connection.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

limitnumber

Number of results to return (1–100, default 20)

offsetnumber

Pagination offset

Response Example

{
  "total": 142,
  "items": [
    {
      "uid": "usr_k2948fs",
      "displayName": "Sarah Chen",
      "trustScore": 92,
      "connectedAt": "2024-03-12T10:00:00Z"
    }
  ]
}

GET/search

r_search

Search across the Mutle public network. Optimized for finding professionals by name, company, role, or location. Respects user discoverability settings.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

qstring

Search keywords (name, company, role)

rolestring

Filter by job title or profession

locationstring

Filter by city or country

limitnumber

Number of results (max 30)

Response Example

{
  "results": [
    {
      "uid": "usr_js83hf",
      "displayName": "James Wilson",
      "relevance": 0.98,
      "role": "Director of Product",
      "location": "New York, NY"
    }
  ]
}

GET/posts/feed

r_member_social

Returns the authenticated user's personalized Mutle feed. Supports the same sectioning model used by the first-party app.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

sectionstring

Optional feed section: `for_you`, `from_network`, `opportunities`, or `trending`

limitnumber

Number of posts to return (1-50)

cursorstring

Optional cursor key for feed pagination/cache bucketing

Response Example

{
  "sections": {
    "for_you": [
      {
        "id": "post_82hf93h",
        "body": "Excited to be building with the Mutle API.",
        "counts": {
          "likes": 4,
          "comments": 1,
          "reposts": 0
        }
      }
    ]
  },
  "cursor": null
}

POST/posts

w_member_social

Create a post as the authenticated user. This uses the same trust, moderation, audience, and rate-limit rules as the first-party Mutle app.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

bodystring

Post body text

postTypestring

Usually `text` for simple posts

intentstring

Intent classifier, for example `general`

audiencestring

Audience such as `public` or `connections`

Response Example

{
  "id": "post_82hf93h",
  "authorId": "usr_9482hfk3",
  "body": "Excited to be building with the Mutle API.",
  "postType": "text",
  "intent": "general",
  "audience": "public"
}

GET/posts/{postId}

r_member_social

Fetch a single post with hydrated author data and viewer-specific interaction flags.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

postIdstring

The post ID to retrieve

Response Example

{
  "id": "post_82hf93h",
  "authorId": "usr_9482hfk3",
  "body": "Excited to be building with the Mutle API.",
  "counts": {
    "likes": 4,
    "comments": 1,
    "reposts": 0
  },
  "viewerState": {
    "liked": false
  }
}

POST/posts/{postId}/comments

w_member_social

Create a comment on a post. Supports top-level comments and replies via `parentCommentId`.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

postIdstring

The post ID to comment on

bodystring

Comment text

parentCommentIdstring

Optional parent comment ID for threaded replies

Response Example

{
  "id": "cmt_82hf93h",
  "authorId": "usr_9482hfk3",
  "body": "This is a great post.",
  "parentCommentId": null,
  "createdAt": "2026-04-19T12:00:00Z"
}

POST/posts/{postId}/like

w_member_social

Like a post as the authenticated user. Use DELETE on the same path to unlike it.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

postIdstring

The post ID to like

Response Example

{
  "liked": true,
  "count": 5
}

GET/notifications

r_member_social

Returns the authenticated user's latest notifications with actor and target-path metadata.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Response Example

{
  "items": [
    {
      "id": "notif_82hf93h",
      "type": "post_like",
      "actorUid": "usr_k2948fs",
      "actorName": "Sarah Chen",
      "targetPath": "/posts/post_82hf93h",
      "read": false
    }
  ]
}

POST/messages

w_messages

Send a direct message as the authenticated user. Provide an existing conversationId, or provide toUid and Mutle will create or reuse the direct conversation first.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

conversationIdstring

Existing conversation ID (optional if `toUid` is provided)

toUidstring

Target user ID for starting or reusing a direct conversation

textstring

Message body

Response Example

{
  "conversationId": "usr_9482hfk3_usr_k2948fs",
  "messageId": "msg_9f8h2k"
}

GET/conversations

w_messages

List the authenticated user's conversations, sorted by most recent activity.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Response Example

{
  "items": [
    {
      "id": "usr_9482hfk3_usr_k2948fs",
      "participants": [
        "usr_9482hfk3",
        "usr_k2948fs"
      ],
      "lastMessageText": "Great to meet you."
    }
  ]
}

GET/conversations/{conversationId}

w_messages

Fetch a conversation plus its most recent messages. Use `PATCH /messages/read` to reset the unread count for a conversation.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

conversationIdstring

The conversation ID

Response Example

{
  "conversation": {
    "id": "usr_9482hfk3_usr_k2948fs",
    "participants": [
      "usr_9482hfk3",
      "usr_k2948fs"
    ]
  },
  "messages": [
    {
      "id": "msg_9f8h2k",
      "senderUid": "usr_9482hfk3",
      "text": "Great to meet you."
    }
  ]
}

Restricted API

Pathfinding, introductions, and other sensitive actions require approval.

Approval required

The endpoints below require manual review. Submit a request from your app console with a description of your use case. Reviews typically complete within 24–48 hours.

POST/network/path

r_graph

Calculate the trusted path from the authenticated user to a target user. Send the target UID in the JSON body. The response includes the primary path and alternate candidate paths when available.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

targetUidstring

The UID of the person you want to reach

Response Example

{
  "path": [
    {
      "uid": "usr_auth",
      "displayName": "You"
    },
    {
      "uid": "usr_hop1",
      "displayName": "Mike Ross"
    },
    {
      "uid": "usr_target",
      "displayName": "Harvey Specter"
    }
  ],
  "trustScores": [
    "high",
    "medium"
  ],
  "totalScore": 7,
  "paths": [
    {
      "path": [
        {
          "uid": "usr_auth",
          "displayName": "You"
        },
        {
          "uid": "usr_hop1",
          "displayName": "Mike Ross"
        },
        {
          "uid": "usr_target",
          "displayName": "Harvey Specter"
        }
      ],
      "trustScores": [
        "high",
        "medium"
      ],
      "totalScore": 7,
      "hops": 2
    }
  ]
}

POST/intros

w_intros

Initiate a multi-hop introduction request. Supply the target, a valid path, and a meaningful note. Mutle enforces the same intro fatigue, privacy, and path-integrity rules used in the core app.

Authorization: All requests require Authorization: Bearer <access_token> in the request headers.

Parameters

targetIdstring

UID of the user you want to meet

messagestring

Personalized intro message (minimum 50 characters)

pathUidsstring[]

Explicit path to use, starting with the requester and ending with the target

Response Example

{
  "id": "int_82hf93h",
  "requesterId": "usr_auth",
  "targetId": "usr_target",
  "status": "pending",
  "currentHopUid": "usr_hop1",
  "pathUids": [
    "usr_auth",
    "usr_hop1",
    "usr_target"
  ],
  "createdAt": "2026-04-15T14:00:00Z"
}

Webhooks

Real-time POST notifications for network events.

Configure a webhook URL in your console to receive POST requests whenever events occur in the authorized user's network. Requires the ext_webhooks scope.

Supported events

connection.confirmed

A new connection was confirmed

intro.completed

An intro request reached its target

intro.declined

An intro was declined by a hop

profile.updated

The user's profile was modified

trust.decay

A connection's trust score has dropped

Example payload — `connection.confirmed`

{
  "event": "connection.confirmed",
  "timestamp": "2026-04-15T14:22:00Z",
  "app_id": "app_k2948fs",
  "data": {
    "connectionId": "con_9f8h2k",
    "requester": {
      "uid": "usr_9482hfk3",
      "displayName": "Alex Rivera"
    },
    "receiver": {
      "uid": "usr_k2948fs",
      "displayName": "Sarah Chen"
    },
    "trustScore": 88,
    "confirmedAt": "2026-04-15T14:22:00Z"
  }
}

Mutle signs every webhook payload with your client secret using HMAC-SHA256. Validate the X-Mutle-Signature header to confirm the request is genuine before processing it.

Unlock the Power ofTrusted Networks.

User Authentication

Redirect the user to Mutle's authorization page

Exchange the authorization code for an access token

Token response

Machine-to-Machine Auth

Request an app token

Using Your Token

curl

JavaScript (fetch)

Scopes & Data Formats

Rate Limits

Rate limit headers

Error Handling

Error response format

Common error codes

API Reference

Response Example

Parameters

Response Example

Parameters

Response Example

Parameters

Response Example

Parameters

Response Example

Parameters

Response Example

Parameters

Response Example

Parameters

Response Example

Response Example

Parameters

Response Example

Response Example

Parameters

Response Example

Restricted API

Parameters

Response Example

Parameters

Response Example

Webhooks

Supported events

Example payload — connection.confirmed

Unlock the Power of
Trusted Networks.

Example payload — `connection.confirmed`