API Reference

Complete reference for every HTTP endpoint exposed by Morgenruf. All API paths are relative to your APP_URL (e.g. https://app.morgenruf.dev).

Authentication

Morgenruf uses two authentication mechanisms depending on the context:

Session Authentication (Dashboard API)

The /dashboard/api/* endpoints are protected by a server-side session. Sessions are established via the OAuth install flow or by visiting /dashboard/login. The session cookie (mrn_session) is set as HttpOnly; SameSite=Lax; Secure and must be present on every request.

To authenticate programmatically, obtain a short-lived login token from the OAuth callback and exchange it at login:

GET /dashboard/login?t=<login_token>

The login token is a base64-encoded HMAC-signed payload (team_id + user_id + timestamp) valid for 5 minutes. It is issued automatically at the end of the OAuth flow.

Bearer Token Authentication (MCP API)

The /mcp endpoint uses Bearer token auth. Generate an API key in Dashboard → Integrations → MCP and pass it in the Authorization header:

curl -X POST https://app.morgenruf.dev/mcp \
  -H "Authorization: Bearer mrn_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

API keys are stored as SHA-256 hashes. Only the mrn_-prefixed key shown at creation time can be used for auth — it cannot be retrieved again.

System Endpoints

GET /

Returns basic application info. No authentication required.

curl https://app.morgenruf.dev/

{
  "name": "morgenruf",
  "version": "1.0.0",
  "status": "ok"
}

GET /healthz

Health check endpoint used by load balancers and Kubernetes liveness/readiness probes. Returns 200 OK when the app is healthy.

curl https://app.morgenruf.dev/healthz

{"status": "ok"}

OAuth Endpoints

GET /install

Redirects the browser to the Slack OAuth authorisation page. Generates an HMAC-signed state parameter automatically. No authentication required.

GET /install
→ 302 Redirect to https://slack.com/oauth/v2/authorize?...

GET /oauth/callback

Handles the OAuth redirect from Slack. Exchanges the authorization code for a bot token, persists the installation, and redirects to the dashboard. No authentication required.

On success: 302 redirect to /dashboard?t=<login_token>.
On error: 400 with an HTML error page.

Slack Endpoints

POST /slack/events

Receives all Slack event subscriptions (messages, app mentions, app_uninstalled, etc.) and slash command payloads. Requests are verified with the SLACK_SIGNING_SECRET. This endpoint is called by Slack — you do not call it directly.

POST /slack/interactions

Receives Slack Block Kit interactive component payloads (button clicks, modal submissions, etc.). Also verified with SLACK_SIGNING_SECRET and called by Slack.

Dashboard API

All /dashboard/api/* endpoints require session authentication. They return JSON. On auth failure the response is 401 {"error": "Unauthorized"}; on missing admin role it is 403 {"error": "Admin required"}.

GET /dashboard/api/me

Returns the currently authenticated user's profile.

{
  "user_id": "U012AB3CD",
  "team_id": "T012AB3CD",
  "team_name": "Acme Corp",
  "role": "admin"
}

GET /dashboard/api/standups

Lists all standup schedules configured for the workspace.

[
  {
    "id": "T012AB3CD",
    "channel_id": "C012AB3CD",
    "schedule_time": "09:00",
    "schedule_tz": "America/New_York",
    "schedule_days": "mon,tue,wed,thu,fri",
    "questions": [
      "What did you complete yesterday?",
      "What are you working on today?",
      "Any blockers?"
    ],
    "active": true
  }
]

POST /dashboard/api/standups

Creates a new standup schedule. Admin required.

{
  "channel_id": "C012AB3CD",
  "schedule_time": "09:30",
  "schedule_tz": "Europe/London",
  "schedule_days": "mon,tue,wed,thu,fri",
  "questions": ["What are you shipping today?", "Any blockers?"],
  "active": true
}

Returns 201 with the created standup object.

PUT /dashboard/api/standups/<standup_id>

Updates a standup schedule. Admin required. Accepts the same fields as POST; omitted fields are left unchanged.

DELETE /dashboard/api/standups/<standup_id>

Deletes a standup schedule. Admin required. Returns {"ok": true}.

GET /dashboard/api/members

Lists workspace members. Admin required.

[
  {
    "user_id": "U012AB3CD",
    "real_name": "Alice Smith",
    "email": "alice@example.com",
    "tz": "America/Chicago",
    "active": true,
    "role": "admin"
  }
]

POST /dashboard/api/members/invite

Adds a Slack user to the workspace member list. Admin required.

{ "user_id": "U012AB3CD" }

Returns 201 with the new member object. Returns 400 if user_id is missing, or 500 if the Slack API cannot be reached.

PUT /dashboard/api/members/<user_id>/role

Updates a member's role. Admin required.

{ "role": "admin" }

Valid values for role: "admin", "member". Returns {"ok": true, "user_id": "...", "role": "..."}.

GET /dashboard/api/channels

Returns a list of public Slack channels the bot has access to. Used to populate the channel selector in the dashboard.

[
  { "id": "C012AB3CD", "name": "engineering" },
  { "id": "C012AB3CE", "name": "design" }
]

GET /dashboard/api/stats

Returns high-level participation statistics for the workspace.

{
  "total_members": 12,
  "submitted_today": 9,
  "participation_7d_pct": 84,
  "active_blockers": 2
}

GET /dashboard/api/reports

Returns standup responses and participation data for a date range.

{
  "standups": [
    {
      "user_id": "U012AB3CD",
      "standup_date": "2026-04-01",
      "yesterday": "Shipped the login page.",
      "today": "Working on password reset.",
      "blockers": "None",
      "mood": "😊"
    }
  ],
  "participation": [
    { "date": "2026-04-01", "submitted": 9, "total": 12, "pct": 75 }
  ],
  "total_days": 7
}

GET /dashboard/api/analytics

Returns extended analytics including mood trends and per-member participation breakdown. Accepts the same days query param as /reports.

GET /dashboard/api/export/csv

Downloads standup data as a CSV file. Accepts optional from and to query params (YYYY-MM-DD). Returns Content-Type: text/csv with a Content-Disposition: attachment header.

Columns: standup_date, user_id, real_name, yesterday, today, blockers, mood, submitted_at.

GET /dashboard/api/webhooks

Lists registered webhook endpoints. Admin required.

[
  {
    "id": 1,
    "url": "https://example.com/hooks/standup",
    "created_at": "2026-01-15T10:23:00Z"
  }
]

POST /dashboard/api/webhooks

Registers a new webhook endpoint. Admin required.

{ "url": "https://example.com/hooks/standup" }

Returns 201 with the created hook object. The URL must be an https:// address; private/internal IP ranges are rejected with 400.

DELETE /dashboard/api/webhooks/<hook_id>

Removes a webhook endpoint. Admin required. Returns {"ok": true}.

GET /dashboard/api/kudos

Returns recent kudos given in the workspace.

[
  {
    "from_user": "U012AB3CD",
    "to_user": "U012AB3CE",
    "message": "Great work on the release!",
    "created_at": "2026-04-01T14:00:00Z"
  }
]

GET /dashboard/api/kudos/leaderboard

Returns a ranked list of members by kudos received. Accepts a days query param (default: 30).

[
  { "user_id": "U012AB3CE", "real_name": "Bob Jones", "kudos_received": 7 },
  { "user_id": "U012AB3CD", "real_name": "Alice Smith", "kudos_received": 4 }
]

GET /dashboard/api/templates

Returns the 25 built-in question template sets that can be applied to a standup schedule.

[
  {
    "name": "Classic Standup",
    "questions": [
      "What did you complete yesterday?",
      "What are you working on today?",
      "Any blockers?"
    ]
  }
]

GET /dashboard/api/schedules

Lists all standup schedules (same as /dashboard/api/standups, used by multi-schedule UI).

POST /dashboard/api/schedules

Creates a new standup schedule. Admin required. Accepts same body as POST /dashboard/api/standups.

PUT /dashboard/api/schedules/<schedule_id>

Updates a schedule. Admin required.

DELETE /dashboard/api/schedules/<schedule_id>

Deletes a schedule. Admin required. Returns {"ok": true}.

GET /dashboard/api/rules

Lists workflow automation rules for the workspace. Admin required.

[
  {
    "id": 1,
    "trigger": "blocker_reported",
    "action": "post_to_channel",
    "action_target": "C012AB3CD",
    "active": true
  }
]

POST /dashboard/api/rules

Creates a workflow automation rule. Admin required.

{
  "trigger": "participation_below",
  "trigger_threshold": 50,
  "action": "dm_admin",
  "action_target": "U012AB3CD",
  "active": true
}

DELETE /dashboard/api/rules/<rule_id>

Deletes a workflow rule. Admin required. Returns {"ok": true}.

POST /dashboard/api/feed-token

Generates (or regenerates) the public standup feed token for the workspace. Admin required. Returns {"token": "abc123..."}.

DELETE /dashboard/api/feed-token

Revokes the public standup feed token. Admin required. Returns {"ok": true}.

GET /feed/<token>

Public read-only standup feed page. No authentication required — access is controlled by the token. Returns an HTML page with the most recent standup responses.

MCP API

The MCP (Model Context Protocol) endpoint exposes standup data to AI assistants (Claude, Cursor, GitHub Copilot). It uses JSON-RPC 2.0 over HTTP and requires a Bearer API key. See the MCP integration guide for full setup instructions.

GET /mcp

Public info endpoint. No authentication required. Returns connection metadata and the list of available tool names.

{
  "name": "Morgenruf MCP Server",
  "version": "1.0.0",
  "transport": "http",
  "endpoint": "https://app.morgenruf.dev/mcp",
  "auth": "Bearer token — generate from your Morgenruf dashboard",
  "docs": "https://docs.morgenruf.dev/mcp.html",
  "tools": [
    "get_standups",
    "get_today_standups",
    "get_blockers",
    "get_participation",
    "get_members",
    "search_standups",
    "get_workspace_summary",
    "get_mood_summary"
  ]
}

POST /mcp

MCP JSON-RPC 2.0 endpoint. Requires Bearer authentication.

Supported methods:

Available tools via tools/call:

Example tools/call request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_blockers",
    "arguments": { "days": 7 }
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"user_id\": \"U012AB3CD\", \"date\": \"2026-04-01\", \"blockers\": \"Waiting on PR review\"}]"
      }
    ]
  },
  "id": 1
}

GET /dashboard/api/mcp/keys

Lists MCP API keys for the workspace (prefixes only — full keys are never returned after creation). Admin required.

[
  {
    "id": 1,
    "name": "Claude Desktop",
    "key_prefix": "mrn_a1b2",
    "created_at": "2026-03-10T09:00:00Z",
    "last_used_at": "2026-04-01T08:45:00Z",
    "active": true
  }
]

POST /dashboard/api/mcp/keys

Generates a new MCP API key. Admin required. Optionally accepts {"name": "My Key"} in the request body.

{
  "id": 2,
  "name": "Cursor",
  "key": "mrn_a1b2c3d4e5f6g7h8",
  "key_prefix": "mrn_a1b2",
  "created_at": "2026-04-05T12:00:00Z"
}

The full key is only returned once at creation time. Store it securely.

DELETE /dashboard/api/mcp/keys/<key_id>

Revokes an MCP API key. Admin required. Returns {"ok": true}.

GET /dashboard/api/mcp-config

Returns ready-to-use MCP configuration snippets for Claude Desktop and Cursor.

{
  "claude_desktop": {
    "mcpServers": {
      "morgenruf": {
        "command": "npx",
        "args": ["mcp-remote", "https://app.morgenruf.dev/mcp"],
        "env": { "MORGENRUF_API_KEY": "mrn_..." }
      }
    }
  }
}

Error Codes

All REST endpoints use standard HTTP status codes:

Error responses from the Dashboard API always include a JSON body:

{ "error": "Human-readable description of the problem" }

MCP JSON-RPC errors follow the JSON-RPC 2.0 error object format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized — provide a valid Bearer API key from your Morgenruf dashboard"
  },
  "id": null
}

Common MCP error codes: