Plugin API Reference

Overview

The Cursorist API provides REST endpoints for plugin discovery, installation tracking, favorites, and admin operations. All endpoints respect the api_enabled site configuration—when disabled, requests return 503 Service Unavailable.

Get Plugin (Latest Version)

Returns plugin data with the latest stable version and assets.

Response

{
  "id": "uuid",
  "name": "My Plugin",
  "slug": "my-plugin",
  "description": "Plugin description",
  "organization": "acme",
  "team": "engineering",
  "author": {
    "github": "username"
  },
  "type": "conventions",
  "stack": ["typescript", "react"],
  "latestVersion": "1.0.0",
  "manifest": {
    "name": "My Plugin",
    "version": "1.0.0",
    "description": "Plugin description",
    "components": ["rules", "skills"]
  },
  "assets": [
    {
      "asset_type": "rules",
      "path": "rules/project-standards.mdc",
      "content_raw": "...",
      "content_hash": "sha256...",
      "size_bytes": 1024
    }
  ],
  "installCount": 42
}

Errors

• 404 — Plugin not found
• 503 — API access disabled

Get Plugin Version

Returns a specific version of a plugin with its assets.

Response

{
  "plugin": {
    "id": "uuid",
    "name": "My Plugin",
    "slug": "my-plugin",
    "description": "Plugin description",
    "organization": "acme",
    "team": "engineering"
  },
  "version": {
    "id": "uuid",
    "version": "1.0.0",
    "changelog": "Initial release",
    "manifest": { "name": "My Plugin", "version": "1.0.0", "components": ["rules"] },
    "isPrerelease": false
  },
  "assets": [
    {
      "asset_type": "rules",
      "path": "rules/project-standards.mdc",
      "content_raw": "...",
      "content_hash": "sha256...",
      "size_bytes": 1024
    }
  ]
}

Errors

• 404 — Plugin or version not found (yanked versions return 404)
• 503 — API access disabled

Track Plugin Installation

Increments the plugin's install count and records the install for authenticated users.

Response

{
  "success": true
}

Errors

• 500 — Failed to increment install count
• 503 — API access disabled

Toggle Plugin Favorite

Toggles favorite status for the authenticated user.

Response

{
  "success": true
}

Errors

• 401 — Unauthorized (not logged in)
• 503 — API access disabled

Publish Plugin (Admin)

Publishes a plugin to the OSS catalog. Admin only.

Request Body

multipart/form-data or application/x-www-form-urlencoded:

Response

{
  "success": true
}

Errors

• 400 — Plugin ID required
• 401 — Unauthorized
• 403 — Admin access required
• 500 — Database error
• 503 — API access disabled

Search Docs

Full-text search across documentation content.

Query Parameters

Query parameters are defined by the fumadocs search implementation. Typically includes q for the search query.

Response

Returns search results in the format expected by the docs search UI (JSON array of matching pages/slugs).

MCP Deeplink

Generates an MCP install deeplink for Cursor, including API key provisioning for authenticated users.

Response

{
  "deeplink": "cursor://anysphere.cursor-deeplink/mcp/install?name=Cursorist&config=...",
  "apiKey": "optional-api-key-if-newly-created"
}

The deeplink encodes an MCP config that runs npx -y @cursorist/mcp-server@latest with CURSORIST_API_URL and optional CURSORIST_API_KEY environment variables.

Errors

• 401 — Unauthorized
• 503 — API access disabled