Registry API

The semrel-registry exposes a public JSON REST API for discovering and downloading semrel plugins. The base URL for the official registry is https://registry.semrel.io.

Returns the complete plugin catalogue as a JSON document — this is the primary endpoint consumed by the semrel CLI.

# Default registry
curl https://registry.semrel.io/plugins.json

# Custom registry (set via SEMREL_REGISTRY_URL)
curl $SEMREL_REGISTRY_URL/plugins.json

The response format is documented in the plugin metadata schema.

Lists plugins with pagination and filtering.

Query parameters

Response

{
  "plugins": [
    {
      "namespace": "@semrel",
      "name": "github",
      "description": "Publishes GitHub releases and uploads assets.",
      "category": "provider",
      "repository": "https://github.com/SemRels/provider-github",
      "license": "Apache-2.0",
      "tags": ["github", "release"],
      "latestVersion": "1.2.0",
      "downloads": 4891
    }
  ],
  "total": 27,
  "page": 1,
  "limit": 20
}

Returns a plugin by namespace and name.

curl https://registry.semrel.io/api/v1/plugins/@semrel/provider-github

Lists all published versions of a plugin.

[
  {
    "version": "1.2.0",
    "changelog": "## 1.2.0\n\n- Added asset upload support",
    "downloadUrl": "https://github.com/SemRels/provider-github/releases/download/v1.2.0/plugin-linux-amd64",
    "checksums": {
      "linux_amd64": "3b4cde…"
    },
    "prerelease": false,
    "downloads": 1240,
    "createdAt": "2024-03-20T14:30:00Z"
  }
]

Records a download event. Called automatically by semrel plugin install — no manual use needed.

Plugin authors can submit a community plugin for review:

Submits a plugin for review. The plugin is published with status: pending until approved.

Request body

{
  "name": "my-analyzer",
  "description": "A custom commit analyzer.",
  "category": "analyzer",
  "repository": "https://github.com/you/my-analyzer",
  "license": "Apache-2.0",
  "tags": ["analyzer"]
}

Authentication uses GitHub OAuth — browse to https://registry.semrel.io and sign in before submitting.

Plugin release workflows call this endpoint to notify the registry of a new version. Add this step to your plugin’s release workflow:

- name: Notify semrel registry
  run: |
    curl -s -X POST https://registry.semrel.io/api/v1/webhooks/release \
      -H "Content-Type: application/json" \
      -H "X-Semrel-Signature: ${{ secrets.SEMREL_WEBHOOK_SECRET }}" \
      -d '{"repository": "${{ github.repository }}", "tag": "${{ github.ref_name }}"}'

The webhook secret is provided to plugin maintainers separately. See the plugin publishing guide for the full release workflow.

Returns the JSON Schema for .semrel.yaml. Use with any LSP-aware editor for inline validation:

# yaml-language-server: $schema=https://registry.semrel.io/schemas/core/v1.json

Returns the JSON Schema for a specific plugin’s args: configuration.

Redirects (HTTP 301) to the most recent schema version for the named plugin.

Public endpoints are rate-limited per client IP:

Responses exceeding the limit return HTTP 429 Too Many Requests with a Retry-After: 60 header.

The registry is open source. To run your own instance, see the semrel-registry repository. Point the CLI at your instance by setting SEMREL_REGISTRY_URL.