Plugins API

Import and compile Claude Code plugins into workflow specifications that can be executed via the Runs API.

Quick Reference

POST   /api/v1/plugins/compile    Compile a plugin from GitHub or inline files

Authentication

Plugin endpoints require:

  • Secret key (mr_sk_*): Backend use with full project access

Runtime Requirements

/api/v1/plugins/compile calls the ModelRelay Responses API under the hood to generate workflows. In practice you need:

  • A configured LLM provider key for the model you pass (or a default provider) so compilation can call /responses.
  • MODELRELAY_GITHUB_TOKEN (recommended) to avoid GitHub rate limits when fetching plugin files from GitHub.

Compile Plugin

POST /api/v1/plugins/compile

Compiles a Claude Code plugin into a workflow specification. The plugin can be fetched from a GitHub repository or provided inline. The compiled workflow can then be executed using the Runs API.

Request Body

Field Type Required Description
source string One of source/files GitHub source reference (see Source Format)
files object One of source/files Map of file paths to content for inline plugins
model string No LLM model to use for workflow generation
mode string No Compile mode. Currently only intent is supported (default)
max_attempts integer No Maximum attempts to regenerate on validation errors (default: 3, max: 5)

Response

Field Type Description
workflow object Compiled workflow specification
plugin object Plugin metadata
compiled_at datetime Timestamp of compilation
source_ref string Canonical source reference with resolved commit SHA (or inline)

Plugin Object

Field Type Description
name string Plugin name from plugin.json
description string Plugin description
agents array List of agent objects in the plugin

Agent Object

Field Type Description
name string Agent name
system_prompt string Agent system prompt

Example (GitHub Source)

curl -X POST https://api.modelrelay.ai/api/v1/plugins/compile \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "github:anthropics/plugins/unslopify@main"
  }'

Example (Inline Files)

curl -X POST https://api.modelrelay.ai/api/v1/plugins/compile \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "files": {
      ".claude-plugin/plugin.json": "{\"name\": \"my-plugin\", \"description\": \"Analyzes code\"}",
      "agents/analyzer.md": "---\nname: analyzer\ndescription: Analyzes code for issues\n---\nYou are a code analyzer..."
    },
    "model": "claude-sonnet-4-5"
  }'

Response

{
  "workflow": {
    "kind": "workflow",
    "name": "unslopify",
    "model": "claude-sonnet-4-5",
    "nodes": [
      {
        "id": "type-strictness",
        "type": "llm",
        "user": "Analyze type strictness for {{task}}"
      },
      {
        "id": "aggregate",
        "type": "llm",
        "user": "Aggregate findings from {{type-strictness}}"
      }
    ],
    "outputs": [
      {"name": "report", "from": "aggregate"}
    ]
  },
  "plugin": {
    "name": "unslopify",
    "description": "Tactical code cleanup focusing on type strictness, SRP, fail-fast, and DRY",
    "agents": [
      {"name": "type-strictness-analyzer", "system_prompt": "You are a type system expert..."}
    ]
  },
  "compiled_at": "2026-01-06T12:34:56Z",
  "source_ref": "github:anthropics/plugins/unslopify@abc123def456"
}

Source Format

The source field specifies where to fetch the plugin from. Currently, GitHub repositories are supported.

GitHub Source

github:owner/repo/path@ref
Component Required Description
owner Yes GitHub repository owner
repo Yes Repository name
path No Path to plugin directory within repo (defaults to root)
ref No Git ref (branch, tag, or commit SHA; defaults to main)

Examples

Source Description
github:anthropics/plugins/unslopify Plugin at /unslopify in repo, main branch
github:anthropics/plugins/unslopify@v1.0.0 Specific tag
github:anthropics/plugins/unslopify@abc123 Specific commit
github:acme/my-plugin Plugin at repo root

Plugin Structure

A Claude Code plugin must contain:

plugin-name/
  .claude-plugin/
    plugin.json      # Plugin manifest (required)
  agents/            # Agent definitions (required, at least one)
    analyzer.md
    reviewer.md
  reference/         # Reference documentation (optional)
    guidelines.md

plugin.json

The plugin manifest:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0"
}

Agent Files

Each agent is a markdown file with YAML frontmatter:

---
name: analyzer
description: Analyzes code for issues. Use when reviewing code quality.
tools:
  - Read
  - Grep
  - Glob
---

You are a code analyzer. Your job is to...

The agent’s description field is used by the LLM to decide how to orchestrate agents in the generated workflow.

Error Responses

Status Code Description
400 invalid_source Source format is invalid
400 source_or_files_required Either source or files must be provided
404 plugin_not_found Plugin repository or path not found
422 parse_failed Plugin files could not be parsed
422 generation_failed Workflow generation failed
429 rate_limited GitHub API rate limit exceeded

Error Response Format

{
  "error": "api_error",
  "code": "plugin_not_found",
  "message": "Plugin not found at github:owner/repo/path"
}

Caching

Compiled workflows are deterministic for a given commit SHA. When you specify a branch or tag, the API resolves it to a commit SHA and includes it in source_ref. You can cache compiled workflows keyed by source_ref to avoid recompilation.

Next Steps