Manifest Reference

The PluginManifest is the source of truth for a plugin release. Navigic reads it to understand compatibility, runtime routes, publisher identity, license, trust links, release metadata, permissions, data use, operations, events, channel capabilities, outbound domains, and redaction rules.

Released manifests should be immutable. If an operation, scope, schema, route, or risk level changes, publish a new plugin package version.

Top-Level Shape

Field	Required	Notes
`apiVersion`	Yes	Must be `navigic.plugin/v1`.
`kind`	Yes	Must be `PluginManifest`.
`metadata`	Yes	Stable identity and package metadata.
`links`	Yes	Public trust, docs, support, privacy, terms, and release links.
`release`	Yes	Version, release date, notes, migration notes, and optional artifact proof.
`hostCompatibility`	Yes	Host protocol versions and optional Navigic version bounds.
`runtime`	Yes	How Navigic discovers health and execute routes.
`auth`	Yes	Auth schemes and provider scopes.
`permissions`	Yes	Human-reviewable permission summary and scope rationale.
`dataUse`	Yes	Data categories, purpose, storage, provider sharing, and retention disclosure.
`operations`	Yes	Agent-callable operations.
`events`	No	Provider events the plugin can normalize or forward.
`channels`	No	Channel capabilities, such as Slack inbound and threaded replies.
`configSchema`	No	JSON Schema for non-secret install configuration.
`secrets`	No	Secret names the plugin expects the host to manage.
`outboundDomains`	No	External domains the plugin calls.
`observability`	No	Redaction fields and telemetry event names.
`signing`	No	Reserved for catalog or manifest signature metadata.

Metadata

Field	Notes
`name`	Stable plugin ID. Use lowercase letters, numbers, and hyphens.
`version`	Plugin package version. Use SemVer.
`displayName`	Human-readable name shown in review surfaces.
`description`	One-sentence summary of the plugin's job.
`publisher`	Structured publisher identity object.
`license`	Required SPDX license identifier or commercial license label.

apiVersion and metadata.version are separate. apiVersion describes the Navigic plugin protocol. metadata.version describes your plugin package.

Publisher

metadata.publisher should identify the accountable publisher, not just a display string.

Field	Required	Notes
`id`	Yes	Stable publisher ID.
`displayName`	Yes	Human-readable publisher name shown in review surfaces.
`type`	Yes	`first_party`, `verified_partner`, `community_preview`, or `unverified`.
`website`	Yes	Publisher website.
`verifiedDomain`	Yes	Domain Navigic can verify for the publisher.
`verificationStatus`	Yes	`verified`, `pending`, `unverified`, or `revoked`.
`supportUrl`	Yes	Support or contact page.
`contactEmail`	No	Contact address for security and support.

First-party plugins should use the Navigic publisher identity. Third-party plugins should use the organization that is responsible for operating the plugin service, support, incident response, and provider behavior.

License

metadata.license is required. Use an SPDX identifier such as MIT, Apache-2.0, or BSD-3-Clause when the plugin is open source. Use a clear commercial label such as Proprietary or Commercial when the plugin is not open source.

Do not leave the license blank. The install review surface should be able to show who publishes the plugin, what version is being installed, and what license applies before a provider account is connected.

Links

links gives admins stable public places to review trust and lifecycle information.

Field	Required	Notes
`homepageUrl`	Yes	Product or plugin overview page.
`docsUrl`	Yes	General plugin documentation.
`installGuideUrl`	Yes	Installation guide.
`configurationGuideUrl`	Yes	Configuration and operating guide.
`changelogUrl`	Yes	Version history for the plugin package.
`supportUrl`	Yes	Support page, ticket path, or support email link.
`privacyPolicyUrl`	Yes	Privacy policy for plugin-related data processing.
`termsUrl`	Yes	Terms or service agreement governing plugin use.
`securityUrl`	Yes	Security boundary, review, or disclosure page.
`repositoryUrl`	Yes	Source repository when public or shareable.

Use absolute HTTPS URLs in released manifests. Localhost and private preview URLs are acceptable only in local development fixtures that cannot be installed by production hosts.

Release

release describes the specific package being reviewed or installed.

Field	Required	Notes
`version`	Yes	Same SemVer package version as `metadata.version`.
`releasedAt`	Yes	ISO 8601 release timestamp.
`releaseNotes`	Yes	Short human-readable release summary.
`breakingChanges`	Yes	List of breaking changes, or an empty array.
`migrationNotes`	Yes	List of migration notes, or an empty array.
`sourceRevision`	No	Source revision or commit for the release.
`artifactDigest`	No	`sha256:<hex>` digest for the shipped artifact.
`manifestDigest`	No	`sha256:<hex>` digest for the canonical manifest bytes.
`signature`	No	Release signature with `algorithm`, `keyId`, and `value`.

Publisher-supplied release metadata does not self-approve a plugin. Navigic's host catalog records install eligibility separately with lifecycle and review state, and production setup should fail closed when the live catalog record is missing, revoked, unapproved, or tied to an unverified publisher.

Runtime

Field	Notes
`kind`	`remote-http`, `mcp`, `openapi-generated`, or `hosted-channel`.
`baseUrl`	Optional absolute plugin service base URL. It may include a plugin path prefix, such as `https://plugins.navigic.ai/typefully/`.
`wellKnownPath`	Path returning this manifest. Use relative paths when `baseUrl` includes a plugin prefix.
`executePath`	Path for host-to-plugin operation execution. Use relative paths when `baseUrl` includes a plugin prefix.
`healthPath`	Path for service health checks. Use relative paths when `baseUrl` includes a plugin prefix.

Remote HTTP plugins should expose a stable well-known manifest route:

GET /.well-known/navigic-plugin.json

First-party plugins should use Navigic's shared plugin ingress pattern:

https://plugins.navigic.ai/{pluginId}/...

For that pattern, set runtime.baseUrl to the plugin root and keep runtime paths relative so hosts preserve the {pluginId} prefix.

Host implementations must preserve any baseUrl path prefix when constructing runtime URLs. Treat wellKnownPath, executePath, and healthPath as relative to baseUrl; leading slashes are only safe when baseUrl is an origin root.

Auth Schemes

Each auth scheme has a type:

Type	Use
`none`	Public read-only plugin with no provider credentials.
`oauth2`	Generic OAuth 2 flow.
`provider-oauth2`	Provider-specific OAuth, such as Slack.
`api-key`	API-key based provider access.
`service-token`	Host-to-plugin service authentication.

Optional fields include provider, purpose, location, scopes, authorizationUrl, tokenUrl, requiredRedirectUris, and credentialLeaseFields.

Permissions

permissions gives admins a compact explanation of the provider permissions and operation grants the plugin needs.

Field	Required	Notes
`providerScopes`	Yes	Provider scope list with rationale, data access, related operations, required flag, and risk.
`outboundDomains`	Yes	External domains the plugin calls, with purpose and data categories.

Each providerScopes entry should include:

Field	Notes
`provider`	External provider ID, such as `slack`.
`scope`	Provider scope or permission name.
`purpose`	Why the plugin needs it.
`dataAccess`	Data categories the scope can access.
`operations`	Manifest operation IDs that use the scope.
`required`	Whether installation must include the scope.
`risk`	Risk level using the same vocabulary as operation risk.
`providerDocsUrl`	Optional provider documentation URL for the scope.

Permissions should match auth.schemes[].scopes, each operation's requiredScopes, and the agent operation grants that the compiler places in a published agent bundle. Each outbound domain entry uses domain, purpose, and dataCategories.

Data Use

dataUse tells admins and reviewers what data the plugin processes before they connect an external provider.

Field	Required	Notes
`collectedDataCategories`	Yes	Data categories the plugin receives or collects.
`processedDataCategories`	Yes	Data categories processed during operations.
`storedDataCategories`	Yes	Data categories stored by Navigic or the plugin service.
`retention`	Yes	Retention summary.
`sharedWith`	Yes	External systems or services data is shared with.
`humanAccess`	Yes	Human operator access summary.
`modelExposure`	Yes	What may become model-visible during agent execution.
`deletionInstructions`	Yes	How customers can revoke, delete, or request deletion.

Data-use fields should distinguish provider credentials from ordinary provider content. Long-lived credentials should stay in the host-side credential store or provider account, and runtime calls should use scoped, short-lived credential leases or service tokens.

Operations

Operations are the model-callable surface. Keep them narrow and stable.

Field	Required	Notes
`operationId`	Yes	Plugin-local ID, such as `send_reply`.
`toolName`	Yes	Global tool name, such as `slack__send_reply`.
`displayName`	Yes	Human-readable name.
`description`	Yes	What the operation does and when it should be used.
`inputSchema`	Yes	JSON Schema for model/tool input.
`outputSchema`	No	JSON Schema for returned data.
`sideEffect`	Yes	`none`, `read`, `write`, `external-send`, or `destructive`.
`risk`	Yes	`internal-control`, `workspace-read`, `workspace-write`, `external-read`, `external-write`, `network`, or `privileged`.
`requiredScopes`	Yes	Provider or Navigic scopes needed by the operation.
`approval.defaultMode`	Yes	`deny`, `ask`, or `allow`.
`idempotency`	Yes	`not_required`, `required`, or `runtime_generated`.
`modelHints`	Yes	Read-only, destructive, and open-world hints.
`timeoutMs`	No	Per-operation timeout.
`retryPolicy`	No	Retry behavior for transient failures.
`rateLimitPolicy`	No	Operation-specific rate limits.
`promptMetadata`	No	Optional prompt snippet or guidelines.

Write and external-send operations should normally use approval.defaultMode: "ask" and idempotency: "required".

Events And Channels

events declare provider events the plugin can receive or normalize. Include the provider event names, delivery type, acknowledgment deadline, idempotency fields, and normalized envelope name.

channels declare whether the plugin can act as a channel integration. For example, a Slack channel plugin can declare inbound app mentions and outbound thread replies.

Example

{
  "apiVersion": "navigic.plugin/v1",
  "kind": "PluginManifest",
  "metadata": {
    "name": "slack",
    "version": "0.1.0",
    "displayName": "Slack",
    "description": "Connect Slack channels to Navigic support agents.",
    "license": "Proprietary",
    "publisher": {
      "id": "navigic",
      "displayName": "NavigicAI",
      "type": "first_party",
      "website": "https://navigic.ai",
      "verifiedDomain": "navigic.ai",
      "verificationStatus": "verified",
      "supportUrl": "https://navigic.ai/docs/plugins/slack-support/",
      "contactEmail": "[email protected]"
    }
  },
  "links": {
    "homepageUrl": "https://navigic.ai/docs/plugins/slack/",
    "docsUrl": "https://navigic.ai/docs/plugins/slack/",
    "installGuideUrl": "https://navigic.ai/docs/plugins/install-a-plugin/",
    "configurationGuideUrl": "https://navigic.ai/docs/plugins/slack/",
    "changelogUrl": "https://navigic.ai/docs/plugins/slack-changelog/",
    "supportUrl": "https://navigic.ai/docs/plugins/slack-support/",
    "privacyPolicyUrl": "https://navigic.ai/privacy/",
    "termsUrl": "https://navigic.ai/terms/",
    "securityUrl": "https://navigic.ai/docs/plugins/slack-security/",
    "repositoryUrl": "https://github.com/NavigicAI/slack-plugin"
  },
  "release": {
    "version": "0.1.0",
    "releasedAt": "2026-07-22T00:00:00.000Z",
    "releaseNotes": "Initial first-party Slack plugin preview.",
    "breakingChanges": [],
    "migrationNotes": [
      "Reconnect existing Slack installations if their grant is missing a required OAuth scope."
    ]
  },
  "hostCompatibility": {
    "protocolVersions": ["navigic.plugin/v1"],
    "navigicMinVersion": "0.1.0"
  },
  "runtime": {
    "kind": "remote-http",
    "wellKnownPath": ".well-known/navigic-plugin.json",
    "executePath": "navigic/plugin/v1/execute",
    "healthPath": "health"
  },
  "auth": {
    "schemes": [
      {
        "type": "provider-oauth2",
        "provider": "slack",
        "scopes": [
          "app_mentions:read",
          "chat:write",
          "commands",
          "channels:read",
          "groups:read"
        ]
      },
      { "type": "service-token" }
    ]
  },
  "permissions": {
    "providerScopes": [
      {
        "provider": "slack",
        "scope": "app_mentions:read",
        "purpose": "Receive app mention events from bound Slack channels.",
        "dataAccess": ["message_content", "channel_metadata"],
        "operations": [],
        "required": true,
        "risk": "external-read",
        "providerDocsUrl": "https://docs.slack.dev/reference/scopes/app_mentions.read/"
      },
      {
        "provider": "slack",
        "scope": "chat:write",
        "purpose": "Send final agent replies into bound Slack conversations.",
        "dataAccess": ["message_content", "channel_metadata"],
        "operations": ["send_reply"],
        "required": true,
        "risk": "external-write",
        "providerDocsUrl": "https://docs.slack.dev/reference/scopes/chat.write/"
      }
    ],
    "outboundDomains": [
      {
        "domain": "slack.com",
        "purpose": "Exchange OAuth codes and call Slack Web API endpoints.",
        "dataCategories": ["workspace_metadata", "channel_metadata", "message_content"]
      }
    ]
  },
  "dataUse": {
    "collectedDataCategories": [
      "Slack workspace metadata",
      "Slack channel metadata",
      "Slack user identifiers",
      "Slack app mention payloads",
      "Slack slash command payloads",
      "agent reply text"
    ],
    "processedDataCategories": [
      "Slack message text from bound channels",
      "Agent reply text sent back to Slack"
    ],
    "storedDataCategories": [
      "Workspace, team, channel, and installation identifiers",
      "Encrypted Slack bot tokens",
      "Redacted delivery ledger metadata"
    ],
    "retention": "Retained while the plugin remains installed, with delivery ledger retention following workspace policy.",
    "sharedWith": ["Slack", "Navigic runtime for the bound workspace agent"],
    "humanAccess": "Navigic operators may inspect redacted metadata and logs for support and security review.",
    "modelExposure": "Slack message text may be sent to the workspace's selected agent only when a bound Slack channel invokes that agent.",
    "deletionInstructions": "Revoke the Slack installation or delete bound Slack channels from the Navigic dashboard."
  },
  "operations": [
    {
      "operationId": "send_reply",
      "toolName": "slack__send_reply",
      "displayName": "Send Slack Reply",
      "description": "Send an approved agent reply to a Slack thread.",
      "inputSchema": { "type": "object" },
      "sideEffect": "external-send",
      "risk": "external-write",
      "requiredScopes": ["chat:write"],
      "approval": { "defaultMode": "ask" },
      "idempotency": "required",
      "modelHints": {
        "readOnlyHint": false,
        "destructiveHint": false,
        "openWorldHint": true
      }
    }
  ],
  "outboundDomains": ["slack.com"],
  "observability": {
    "redactFields": [
      "authorization",
      "access_token",
      "refresh_token",
      "credentialLease",
      "x-slack-signature"
    ]
  }
}

Agent Operation Grants

Agents grant operations by plugin ID and operation ID:

capabilities:
  pluginOperations:
    - pluginId: slack
      operationId: send_reply
      versionRange: ^0.1.0

Compiled bundles carry the selected operations in tools.plugins and enforce operation keys in policy.pluginOperationAllowlist.

Availability Boundary

This reference documents the committed plugin protocol. Public self-serve installation APIs are not generally available yet. During managed preview, Navigic reviews plugin manifests and enables approved installations through the host-side product configuration.