API Reference

The Plugged.in API provides programmatic access to manage MCP servers, documents, and platform features. All API endpoints are available in both the cloud platform and self-hosted installations.

Base URLs

https://plugged.in/api

Authentication

Important: All API endpoints require authentication unless explicitly marked as public. Always include your API key in the Authorization header for every request.

See the Authentication Guide for detailed information on obtaining and managing API keys.

Quick Start

Include your API key in the request headers for all API calls:

Authorization: Bearer YOUR_API_KEY

Public Endpoints

Only the following endpoints are accessible without authentication:

GET /api/search - Public search (with rate limiting)
GET /api/servers/{uuid} - Public server information (if server is public)
GET /api/users/{username} - Public user profiles

Rate Limiting

API endpoints have different rate limits based on the operation type:

Endpoint Type	Limit	Window
Authentication	5 requests	15 minutes
General API	60 requests	1 minute
Public Search	100 requests	1 minute
Sensitive Operations	10 requests	1 hour
AI Documents	10 requests	1 hour

API Endpoints

Search & Discovery

Search MCP Servers

This endpoint is public but has stricter rate limiting for unauthenticated requests. Authenticated requests get higher rate limits.

Search for MCP servers in the registry and community.

curl "https://plugged.in/api/search?q=database&source=registry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

q (string, required) - Search query
source (string) - Filter by source: registry, community, all
package (string) - Filter by package type: npm, docker, pypi
repository (string) - Filter by repository source
sort (string) - Sort results: relevance, recent, popular
limit (integer) - Results per page (default: 20, max: 100)
offset (integer) - Pagination offset

Response:

{
  "servers": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "slug": "example-server",
      "title": "Example MCP Server",
      "description": "A sample MCP server",
      "repository_url": "https://github.com/user/repo",
      "package_type": "npm",
      "installation_count": 1250,
      "rating": 4.5,
      "transports": ["stdio", "sse"]
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

MCP Servers

Get Server Details

Retrieve detailed information about a specific MCP server.

GET /api/servers/{uuid}

curl "https://plugged.in/api/servers/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Example Server",
  "transport": "stdio",
  "command": "node",
  "args": ["index.js"],
  "env": {
    "API_KEY": "***"
  },
  "tools": [
    {
      "name": "example_tool",
      "description": "An example tool",
      "parameters": {}
    }
  ],
  "resources": [],
  "prompts": []
}

Create MCP Server

Add a new MCP server to your profile.

POST /api/mcp-servers

curl -X POST "https://plugged.in/api/mcp-servers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Server",
    "transport": "stdio",
    "command": "node",
    "args": ["server.js"],
    "env": {
      "API_KEY": "my-api-key"
    }
  }'

Request Body:

{
  "name": "string (required)",
  "transport": "stdio | sse | http",
  "command": "string (for stdio)",
  "args": ["array", "of", "arguments"],
  "url": "string (for http/sse)",
  "env": {
    "KEY": "value"
  },
  "notes": "optional notes"
}

Documents API

List Documents

Get documents from your library.

GET /api/documents

Query Parameters:

profileUuid (string, required) - Profile UUID
limit (integer) - Results per page (default: 20)
offset (integer) - Pagination offset
search (string) - Search query
source (string) - Filter by source: upload, ai_generated, api

Upload Document

Upload a document to your library.

POST /api/documents/upload

curl -X POST "https://plugged.in/api/documents/upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "profileUuid=your-profile-uuid"

Search Documents

Semantic search across your document library.

POST /api/documents/search

Request Body:

{
  "query": "search query",
  "profileUuid": "profile-uuid",
  "filters": {
    "source": "ai_generated",
    "modelName": "claude-3",
    "dateFrom": "2024-01-01",
    "dateTo": "2024-12-31"
  },
  "limit": 10
}

Collections API

Get Collections

Retrieve collections for a profile.

GET /api/collections/{profileUuid}

Create Collection

Create a new collection of MCP servers.

POST /api/collections

Request Body:

{
  "name": "My Collection",
  "description": "Collection description",
  "profileUuid": "profile-uuid",
  "serverUuids": ["server-uuid-1", "server-uuid-2"],
  "isPublic": false
}

Registry API

Submit to Registry

Submit an MCP server to the official registry.

POST /api/registry/submit

Request Body:

{
  "repository": "https://github.com/username/repo",
  "transport": ["stdio", "sse"],
  "package_type": "npm",
  "environment_variables": ["API_KEY", "DATABASE_URL"]
}

Requirements:

Must be authenticated with GitHub
Must have repository ownership
Valid package.json/Dockerfile/setup.py

Get Server Statistics

Get detailed statistics for a server.

GET /api/servers/{uuid}/stats

Response:

{
  "installations": 1250,
  "rating": 4.5,
  "ratings_count": 28,
  "trending_rank": 3,
  "last_activity": "2024-01-15T10:30:00Z",
  "daily_installs": [10, 15, 20, 25, 30, 35, 40]
}

User Management

Check Username Availability

Check if a username is available.

GET /api/check-username?username=desired-username

Response:

{
  "available": true
}

Get User Profile

Get public user profile information.

GET /api/users/{username}

Response:

{
  "username": "john_doe",
  "bio": "MCP enthusiast",
  "avatar_url": "https://...",
  "is_public": true,
  "followers_count": 42,
  "following_count": 23,
  "servers_count": 5
}

Notifications API

All notification endpoints require authentication. Include your API key in the Authorization header.

Get Notifications

Retrieve notifications for the authenticated user.

GET /api/notifications

curl "https://plugged.in/api/notifications?unread=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

unread (boolean) - Filter unread only
limit (integer) - Results per page (default: 20, max: 100)
offset (integer) - Pagination offset

Response:

{
  "notifications": [
    {
      "id": "notif_123",
      "type": "server_installed",
      "message": "Your server 'Database Tools' was installed by user123",
      "read": false,
      "created_at": "2024-01-15T10:30:00Z",
      "metadata": {
        "server_id": "server_123",
        "user_id": "user_123"
      }
    }
  ],
  "total": 5,
  "unread_count": 3
}

Mark as Read

Mark a notification as read.

PATCH /api/notifications/{id}/read

curl -X PATCH "https://plugged.in/api/notifications/notif_123/read" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "notification": {
    "id": "notif_123",
    "read": true,
    "read_at": "2024-01-15T10:35:00Z"
  }
}

Delete Notification

Delete a notification permanently.

DELETE /api/notifications/{id}

curl -X DELETE "https://plugged.in/api/notifications/notif_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "message": "Notification deleted successfully"
}

Send Custom Notification (MCP Tool)

This is typically called via MCP tools, but can also be used via API.

POST /api/notifications

curl -X POST "https://plugged.in/api/notifications" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Custom Alert",
    "message": "Your process completed successfully",
    "severity": "INFO",
    "send_email": false
  }'

Request Body:

{
  "title": "string (optional)",
  "message": "string (required)",
  "severity": "INFO | SUCCESS | WARNING | ALERT",
  "send_email": false,
  "metadata": {}
}

Embedded Chat API

Create Chat Session

Initialize a new embedded chat session.

POST /api/embedded-chat/sessions

Request Body:

{
  "profileUuid": "profile-uuid",
  "model": "claude-3-opus",
  "temperature": 0.7,
  "maxTokens": 4096
}

Send Message

Send a message in a chat session.

POST /api/embedded-chat/messages

Request Body:

{
  "sessionId": "session-id",
  "message": "User message",
  "includeContext": true
}

Error Handling

All API endpoints return consistent error responses:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "Additional context"
    }
  }
}

Common Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Rate limit exceeded
`VALIDATION_ERROR`	400	Invalid request parameters
`SERVER_ERROR`	500	Internal server error

Webhooks

Authentication Required: Webhook configuration and management requires authentication. Webhook payloads include a signature for verification.

Configure webhooks to receive real-time notifications about events in your Plugged.in account.

Setting Up Webhooks

Register a Webhook Endpoint

POST /api/webhooks

curl -X POST "https://plugged.in/api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["server.installed", "document.created"],
    "active": true,
    "secret": "your-webhook-secret"
  }'

Response:

{
  "id": "webhook_123",
  "url": "https://your-app.com/webhook",
  "events": ["server.installed", "document.created"],
  "active": true,
  "created_at": "2024-01-15T10:30:00Z"
}

List Webhooks

GET /api/webhooks

curl "https://plugged.in/api/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Webhook

PATCH /api/webhooks/{webhook_id}

curl -X PATCH "https://plugged.in/api/webhooks/webhook_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Delete Webhook

DELETE /api/webhooks/{webhook_id}

curl -X DELETE "https://plugged.in/api/webhooks/webhook_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Security

Signature Verification

All webhook payloads include a signature in the X-Pluggedin-Signature header for verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-pluggedin-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, secret)) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  handleWebhook(req.body);
  res.status(200).send('OK');
});

Supported Events

Event	Description	Payload
`server.installed`	MCP server installed	Server UUID, User ID
`server.uninstalled`	MCP server removed	Server UUID, User ID
`server.updated`	Server configuration changed	Server UUID, Changes
`document.created`	Document added to library	Document ID, Profile UUID
`document.deleted`	Document removed	Document ID
`collection.shared`	Collection made public	Collection UUID
`collection.updated`	Collection modified	Collection UUID, Changes
`user.followed`	User gained a follower	Follower ID, Followed ID
`user.unfollowed`	User lost a follower	Follower ID, Followed ID
`notification.created`	New notification	Notification ID, Type

Webhook Payload Format

{
  "id": "evt_123",
  "event": "server.installed",
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=abc123...",
  "data": {
    "server_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "user-123",
    "profile_uuid": "profile-456",
    "metadata": {
      "source": "registry",
      "version": "1.0.0"
    }
  },
  "retry_count": 0
}

Webhook Retry Policy

Failed webhook deliveries are retried with exponential backoff:

1st retry: After 1 minute
2nd retry: After 5 minutes
3rd retry: After 30 minutes
4th retry: After 2 hours
5th retry: After 12 hours

After 5 failed attempts, the webhook is marked as failed and no further retries are attempted.

Testing Webhooks

Test Webhook Endpoint

Send a test event to your webhook:

POST /api/webhooks/{webhook_id}/test

curl -X POST "https://plugged.in/api/webhooks/webhook_123/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test.ping"
  }'

Webhook Best Practices

Always Verify Signatures

Respond Quickly

Return a 2xx status code within 5 seconds. Process webhook data asynchronously if needed.

app.post('/webhook', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookAsync(req.body);
});

Handle Duplicates

Use the event ID to handle potential duplicate deliveries:

const processedEvents = new Set();

function handleWebhook(payload) {
  if (processedEvents.has(payload.id)) {
    return; // Already processed
  }
  processedEvents.add(payload.id);
  // Process event
}

Monitor Webhook Health

Support

Documentation: docs.plugged.in
GitHub Issues: Report bugs
Email Support: api-support@plugged.in

API Documentation

​API Reference

​Base URLs

​Authentication

​Quick Start

​Public Endpoints

​Rate Limiting

​API Endpoints

​Search & Discovery

​Search MCP Servers

​MCP Servers

​Get Server Details

​Create MCP Server

​Documents API

​List Documents

​Upload Document

​Search Documents

​Collections API

​Get Collections

​Create Collection

​Registry API

​Submit to Registry

​Get Server Statistics

​User Management

​Check Username Availability

​Get User Profile

​Notifications API

​Get Notifications

​Mark as Read

​Delete Notification

​Send Custom Notification (MCP Tool)

​Embedded Chat API

​Create Chat Session

​Send Message

​Error Handling

​Common Error Codes

​Webhooks

​Setting Up Webhooks

​Register a Webhook Endpoint

​List Webhooks

​Update Webhook

​Delete Webhook

​Webhook Security

​Signature Verification

​Supported Events

​Webhook Payload Format

​Webhook Retry Policy

​Testing Webhooks

​Test Webhook Endpoint

​Webhook Best Practices

​Support

API Reference

Base URLs

Authentication

Quick Start

Public Endpoints

Rate Limiting

API Endpoints

Search & Discovery

Search MCP Servers

MCP Servers

Get Server Details

Create MCP Server

Documents API

List Documents

Upload Document

Search Documents

Collections API

Get Collections

Create Collection

Registry API

Submit to Registry

Get Server Statistics

User Management

Check Username Availability

Get User Profile

Notifications API

Get Notifications

Mark as Read

Delete Notification

Send Custom Notification (MCP Tool)

Embedded Chat API

Create Chat Session

Send Message

Error Handling

Common Error Codes

Webhooks

Setting Up Webhooks

Register a Webhook Endpoint

List Webhooks

Update Webhook

Delete Webhook

Webhook Security

Signature Verification

Supported Events

Webhook Payload Format

Webhook Retry Policy

Testing Webhooks

Test Webhook Endpoint

Webhook Best Practices

Support