API Documentation

Integrations are inbound connectors (pull and/or webhook) that map external payloads into named output keys. Those keys can be consumed by prompt templates using {{var_name}} tokens.

Integrations

GET/api/v1/integrations

List integrations for the active project.

Scope: integrations:read

include_inactive

• Type: boolean
• When true, include disabled integrations.

Request

curl -G "https://www.mnexium.com/api/v1/integrations" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "include_inactive=false"

Response

{
  "data": [
    {
      "integration_id": "int_weather_forecast",
      "name": "weather forecast",
      "mode": "pull",
      "scope": "project",
      "allow_live_fetch": true,
      "is_active": true,
      "output_map": [
        { "key": "weather_temp", "path": "current.temperature_2m" },
        { "key": "weather_wind", "path": "current.wind_speed_10m" }
      ]
    }
  ]
}

POST/api/v1/integrations

Create a pull/webhook integration and define output key mappings.

Scope: integrations:write

Parameters:

• name (required): string - Display name.
• mode (required): string - One of: pull, webhook, both.
• scope: string - One of: project, subject, chat.
• endpoint_url: string - Required for pull/both modes.
• output_map (required): array - Array of { key, path, default? } mappings.
• auth_secret: string - Optional encrypted secret for upstream auth.
• webhook_secret: string - Optional secret used to verify incoming webhook signatures.

Request

curl -X POST "https://www.mnexium.com/api/v1/integrations" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather forecast",
    "description": "Open-Meteo pull example",
    "mode": "pull",
    "scope": "project",
    "endpoint_url": "https://api.open-meteo.com/v1/forecast",
    "method": "GET",
    "cache_ttl_seconds": 300,
    "allow_live_fetch": true,
    "query_template": {
      "latitude": "40.7128",
      "longitude": "-74.0060",
      "current": "temperature_2m,wind_speed_10m"
    },
    "output_map": [
      { "key": "weather_temp", "path": "current.temperature_2m" },
      { "key": "weather_wind", "path": "current.wind_speed_10m" }
    ]
  }'

POST/api/v1/integrations/:id/test

Run a one-off integration fetch and preview mapped values. Use /sync to refresh cache.

Scope: integrations:write

Parameters:

• id (required): path - Integration ID.
• subject_id: string - Optional runtime subject context.
• chat_id: string - Optional runtime chat context.

Request

curl -X POST "https://www.mnexium.com/api/v1/integrations/int_weather_forecast/test" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true,
  "values": {
    "weather_temp": 14.1,
    "weather_wind": 13.8
  }
}

POST/api/v1/integrations/:id/webhook

Ingest external webhook data into integration cache using signed requests.

Scope: signature-only (no Mnexium key)

Parameters:

• x-mnx-webhook-timestamp (required): header - Unix timestamp used in signature payload.
• x-mnx-webhook-signature (required): header - HMAC signature generated with the integration webhook secret.

Request

curl -X POST "https://www.mnexium.com/api/v1/integrations/int_weather_forecast/webhook" \
  -H "x-mnx-webhook-timestamp: 1733852431" \
  -H "x-mnx-webhook-signature: sha256=..." \
  -H "Content-Type: application/json" \
  -d '{"current":{"temperature_2m":14.1,"wind_speed_10m":13.8}}'

Prompt Template Binding + Request Trace

Bind integration outputs to system prompt templates using template.variables. Request Trace then exposes both the integration IDs used and each resolved variable source/value.

{
  "prompt_text": "Temp: {{temp}} Wind: {{wind}}",
  "template": {
    "enabled": true,
    "variables": {
      "temp": {
        "source": "integration",
        "integration_id": "int_weather_forecast",
        "key": "weather_temp",
        "live_fetch": true
      },
      "wind": {
        "source": "integration",
        "integration_id": "int_weather_forecast",
        "key": "weather_wind",
        "live_fetch": true
      }
    }
  }
}

{
  "system_prompt_ids": ["sp_demo_assistant"],
  "integration_ids": ["int_7bb01c4e-7ea6-48b1-892c-edc5ed7382f5"],
  "integration_cache_hit_count": 1,
  "integration_live_fetch_count": 1,
  "integration_failure_count": 0
}