Clipboard API Reference

The Clipboard API provides persistent key-value storage for MCP tools and AI agents. Access data using named keys or stack-like indexed operations.

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

Base URL

Cloud Platform
Self-Hosted
Local Development

https://plugged.in/api/clipboard

https://your-domain.com/api/clipboard

http://localhost:12005/api/clipboard

Rate Limiting

Operation	Limit	Window
Read operations	100 requests	1 minute
Write operations	60 requests	1 minute
Delete operations	30 requests	1 minute

Endpoints

List Clipboard Entries

Retrieve all clipboard entries for the authenticated profile.

GET /api/clipboard

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

Response:

{
  "success": true,
  "entries": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "user_preferences",
      "idx": null,
      "value": "{\"theme\":\"dark\",\"lang\":\"en\"}",
      "contentType": "application/json",
      "encoding": "utf-8",
      "sizeBytes": 32,
      "visibility": "private",
      "createdByTool": "pluggedin_clipboard_set",
      "createdByModel": "claude-3-opus",
      "source": "mcp",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z",
      "expiresAt": "2024-01-16T10:30:00Z"
    },
    {
      "uuid": "660f9511-f3ac-52e5-b827-557766551111",
      "name": null,
      "idx": 0,
      "value": "Latest stack item",
      "contentType": "text/plain",
      "encoding": "utf-8",
      "sizeBytes": 17,
      "visibility": "private",
      "source": "ui",
      "createdAt": "2024-01-15T11:00:00Z",
      "updatedAt": "2024-01-15T11:00:00Z",
      "expiresAt": "2024-01-16T11:00:00Z"
    }
  ]
}

Get Clipboard Entry

Retrieve a specific entry by name or index.

POST /api/clipboard/get

curl -X POST "https://plugged.in/api/clipboard/get" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_preferences"}'

Request Body:

{
  "name": "string (optional)",
  "idx": "integer (optional)"
}

Provide either name or idx, not both. If neither is provided, returns an error.

Response:

{
  "success": true,
  "entry": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "user_preferences",
    "value": "{\"theme\":\"dark\",\"lang\":\"en\"}",
    "contentType": "application/json",
    "encoding": "utf-8",
    "sizeBytes": 32,
    "visibility": "private",
    "source": "sdk",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-16T10:30:00Z"
  }
}

Set Named Entry

Create or update a named clipboard entry.

POST /api/clipboard

curl -X POST "https://plugged.in/api/clipboard" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user_preferences",
    "value": "{\"theme\":\"dark\",\"lang\":\"en\"}",
    "contentType": "application/json",
    "encoding": "utf-8",
    "visibility": "private",
    "ttlSeconds": 86400
  }'

Request Body:

{
  "name": "string (required)",
  "value": "string (required)",
  "contentType": "string (default: text/plain)",
  "encoding": "utf-8 | base64 | hex (default: utf-8)",
  "visibility": "private | workspace | public (default: private)",
  "createdByTool": "string (optional)",
  "createdByModel": "string (optional)",
  "ttlSeconds": "integer (optional, default: 86400)"
}

Response:

{
  "success": true,
  "entry": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "user_preferences",
    "value": "{\"theme\":\"dark\",\"lang\":\"en\"}",
    "contentType": "application/json",
    "encoding": "utf-8",
    "sizeBytes": 32,
    "visibility": "private",
    "source": "sdk",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "expiresAt": "2024-01-16T10:30:00Z"
  }
}

Push to Stack

Add a new entry to the indexed stack (LIFO).

POST /api/clipboard/push

curl -X POST "https://plugged.in/api/clipboard/push" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "Step 1 processing result",
    "contentType": "text/plain",
    "encoding": "utf-8",
    "ttlSeconds": 3600
  }'

Request Body:

{
  "value": "string (required)",
  "contentType": "string (default: text/plain)",
  "encoding": "utf-8 | base64 | hex (default: utf-8)",
  "visibility": "private | workspace | public (default: private)",
  "createdByTool": "string (optional)",
  "createdByModel": "string (optional)",
  "ttlSeconds": "integer (optional, default: 86400)"
}

Response:

{
  "success": true,
  "entry": {
    "uuid": "770g0622-g4bd-63f6-c938-668877662222",
    "idx": 0,
    "value": "Step 1 processing result",
    "contentType": "text/plain",
    "encoding": "utf-8",
    "sizeBytes": 24,
    "visibility": "private",
    "source": "sdk",
    "createdAt": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z",
    "expiresAt": "2024-01-15T13:00:00Z"
  }
}

When a new entry is pushed, existing indexed entries have their indices incremented (i.e., the newest entry is always at index 0).

Pop from Stack

Remove and return the most recent indexed entry (index 0).

DELETE /api/clipboard/pop

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

Response:

{
  "success": true,
  "entry": {
    "uuid": "770g0622-g4bd-63f6-c938-668877662222",
    "idx": 0,
    "value": "Step 1 processing result",
    "contentType": "text/plain",
    "encoding": "utf-8",
    "sizeBytes": 24,
    "visibility": "private",
    "source": "mcp",
    "createdAt": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}

Pop removes the entry from storage. If you need to read without removing, use the GET endpoint with idx: 0.

Delete Entry

Delete a specific entry by name or index.

DELETE /api/clipboard

curl -X DELETE "https://plugged.in/api/clipboard" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "user_preferences"}'

Request Body:

{
  "name": "string (optional)",
  "idx": "integer (optional)"
}

Response:

{
  "success": true,
  "deleted": true
}

Clear All Entries

Delete all clipboard entries for the profile.

DELETE /api/clipboard/all

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

Response:

{
  "success": true,
  "deletedCount": 5
}

This action is irreversible. All clipboard entries for the profile will be permanently deleted.

Data Types

ClipboardEntry

interface ClipboardEntry {
  uuid: string;                    // Unique identifier
  name?: string;                   // Semantic key (named access)
  idx?: number;                    // Stack index (indexed access)
  value: string;                   // Content value
  contentType: string;             // MIME type
  encoding: "utf-8" | "base64" | "hex";
  sizeBytes: number;               // Value size in bytes
  visibility: "private" | "workspace" | "public";
  createdByTool?: string;          // Creating MCP tool name
  createdByModel?: string;         // Creating AI model name
  source?: "ui" | "sdk" | "mcp";   // Entry source (auto-set)
  createdAt: string;               // ISO 8601 timestamp
  updatedAt: string;               // ISO 8601 timestamp
  expiresAt?: string;              // TTL expiration time
}

Source Types

The source field indicates how the clipboard entry was created:

Source	Description
`ui`	Created via the web interface (default)
`sdk`	Created via one of the official SDKs
`mcp`	Created via MCP proxy tools

The source field is automatically set based on how the entry was created. You cannot override this value when creating entries.

Visibility Levels

Level	Description
`private`	Only accessible by the owner
`workspace`	Shared within the workspace
`public`	Accessible via API with authentication

Encoding Options

Encoding	Use Case
`utf-8`	Text, JSON, and string data
`base64`	Binary data (images, files)
`hex`	Cryptographic data, hashes

Error Responses

Not Found

{
  "success": false,
  "error": "Entry not found"
}

Validation Error

{
  "success": false,
  "error": "Validation error",
  "details": {
    "name": "Name is required for set operation"
  }
}

Size Limit Exceeded

{
  "success": false,
  "error": "Value exceeds maximum size of 2MB"
}

Rate Limited

{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Limits & Constraints

Constraint	Value
Max entry size	2 MB
Default TTL	24 hours (86400 seconds)
Max TTL	30 days
Name length	1-255 characters
Valid name chars	alphanumeric, underscore, hyphen

Best Practices

Use Descriptive Names

Choose meaningful names that describe the data:

Good: last_api_response, user_session_context
Bad: temp, x, data1

Set Appropriate TTLs

Match TTL to your use case:

Temporary processing: 5-15 minutes
Session data: 1-4 hours
Cache data: 24 hours

Use Correct Content Types

Set content types for proper handling:

application/json for structured data
text/plain for simple strings
image/png for base64-encoded images

Handle Expiration

Check for null responses and handle expired entries gracefully:

const entry = await client.clipboard.getByName('cache_key');
if (!entry) {
  // Entry expired or doesn't exist - refresh cache
}

Memory Feature

Platform overview of the Memory feature

JavaScript SDK

Clipboard methods in JavaScript

Python SDK

Clipboard methods in Python

Go SDK

Clipboard methods in Go

API Documentation

​Clipboard API Reference

​Base URL

​Rate Limiting

​Endpoints

​List Clipboard Entries

​Get Clipboard Entry

​Set Named Entry

​Push to Stack

​Pop from Stack

​Delete Entry

​Clear All Entries

​Data Types

​ClipboardEntry

​Source Types

​Visibility Levels

​Encoding Options

​Error Responses

​Not Found

​Validation Error

​Size Limit Exceeded

​Rate Limited

​Limits & Constraints

​Best Practices

​Related Resources

Memory Feature

JavaScript SDK

Python SDK

Go SDK

Clipboard API Reference

Base URL

Rate Limiting

Endpoints

List Clipboard Entries

Get Clipboard Entry

Set Named Entry

Push to Stack

Pop from Stack

Delete Entry

Clear All Entries

Data Types

ClipboardEntry

Source Types

Visibility Levels

Encoding Options

Error Responses

Not Found

Validation Error

Size Limit Exceeded

Rate Limited

Limits & Constraints

Best Practices

Related Resources