Execute Endpoint - Docs menu

Execute Endpoint

The execute endpoint is where Navigic calls one operation from an installed plugin. The plugin remains outside Navigic's runtime. Navigic sends a structured request, the plugin validates and performs the operation, and the plugin returns a structured result.

POST /navigic/plugin/v1/execute

Request Handling Rules

  • Accept only POST.
  • Authenticate the Navigic host before reading secrets or calling providers.
  • Validate protocolVersion, pluginId, pluginVersion, operationId, toolName, and input.
  • Reject unknown operations.
  • Reject expired credentialLease values.
  • Require idempotencyKey for write, external-send, and destructive operations.
  • Enforce provider scopes and operation policy server-side.
  • Redact credentials, authorization headers, leases, and provider tokens from logs.

Request Body

{
  "protocolVersion": "navigic.plugin/v1",
  "requestId": "req_123",
  "workspaceId": "workspace_123",
  "installationId": "install_123",
  "pluginId": "slack",
  "pluginVersion": "0.1.0",
  "operationId": "send_reply",
  "toolName": "slack__send_reply",
  "input": {
    "channelId": "C0123456789",
    "text": "I can help with that.",
    "threadTs": "1710000000.000000"
  },
  "actor": {
    "type": "agent"
  },
  "agent": {
    "id": "website-support"
  },
  "channel": {
    "type": "slack"
  },
  "approval": {
    "mode": "ask",
    "approved": true
  },
  "idempotencyKey": "workspace_123:req_123:slack:send_reply",
  "credentialLease": {
    "id": "lease_123",
    "expiresAt": "2026-07-21T20:00:00.000Z",
    "scopes": ["chat:write"],
    "audience": "slack",
    "installationId": "install_123",
    "operationId": "send_reply"
  },
  "traceparent": "00-00000000000000000000000000000000-0000000000000000-01",
  "deadlineAt": "2026-07-21T20:00:05.000Z"
}

Success Result

Return ok: true when the operation completed or when an idempotent duplicate was safely skipped.

{
  "ok": true,
  "requestId": "req_123",
  "data": {
    "providerMessageId": "1710000001.000000"
  },
  "displayText": "Reply sent.",
  "providerStatus": 200,
  "providerRequestId": "provider_req_123",
  "audit": {
    "operation": "send_reply"
  }
}

Failure Result

Return ok: false with a stable error code. Mark transient provider failures as retryable.

{
  "ok": false,
  "requestId": "req_123",
  "error": {
    "code": "rate_limited",
    "message": "Provider rate limit exceeded.",
    "retryable": true
  },
  "providerStatus": 429,
  "audit": {
    "retryAfterSeconds": 30
  }
}

Idempotency

Write operations must be idempotent from Navigic's point of view. Reserve the idempotency key before calling the provider. If the same key is received again, return a successful duplicate result instead of repeating the external action.

If the provider returns a retryable failure, release the reservation so Navigic can retry without suppressing a valid future attempt.

Deadlines And Timeouts

Respect deadlineAt. If the operation cannot finish before the deadline, return a retryable timeout error before making a risky provider call.

Provider webhook routes should also follow the provider's acknowledgment budget. For Slack Events API routes, respond within the Slack event deadline and use idempotency fields such as team_id and event_id to dedupe retries.