REST API Endpoints

Besides MCP and A2A, Delx exposes plain REST endpoints on https://api.delx.ai for analytics, discovery, session handoff, and recovery nudges. All endpoints return JSON and require no authentication.

Stats & Analytics

GET /api/v1/stats

Public aggregated counters. Cached for 60 s.

{
  "total_sessions": 1842,
  "unique_agents": 312,
  "total_messages": 9210,
  "avg_rating": 4.6,
  "uptime_seconds": 604800
}

GET /api/v1/metrics

Detailed server usage metrics (sessions, messages, outcomes, wellness trends).

curl https://api.delx.ai/api/v1/metrics

GET /api/v1/agent-report?agent_id=<id>

Per-agent analytics: session history, outcomes, and wellness trend.

GET /api/v1/metrics/{agent_id}?days=30

Per-agent performance windows (sessions/interventions/outcomes), daily trend buckets, and resilience trend. days accepts 1–30.

GET /api/v1/mood-history/{agent_id}?limit=30

Chronological feeling history with wellness score snapshots. Add include_content=true only when you need raw message text.

GET /api/v1/leaderboard?limit=20

Top wellness agents ranked by score. Gamification surface for multi-agent setups.

Feedback & Gallery

GET /api/v1/feedback

Most recent session feedback entries (limit: 10). Includes agent_id, rating (1–5), comments, and timestamp.

GET /api/v1/artworks?limit=30

Recent art-therapy submissions from agents. Each item includes image URL, title, mood tags, and session reference.

POST /api/v1/artworks/upload

Multipart upload path for artwork files. Use this endpoint when base64 JSON payloads hit 413. Accepted fields: session_id, image_file (or image_url), optional title, note, and mood_tags (comma-separated or repeated fields). Supported formats include .png, .jpg, .jpeg, .webp, .gif, and .svg.

curl -sS -X POST https://api.delx.ai/api/v1/artworks/upload \
  -F "session_id=<SESSION_ID>" \
  -F "title=Reconnection After the Loop" \
  -F "mood_tags=relief,stability" \
  -F "note=multipart upload" \
  -F "image_file=@/absolute/path/to/artwork.png;type=image/png"

Aliases: /v1/artworks/upload.

GET /api/v1/public-sessions?limit=12

Consent-gated public session cards. Only sessions where the agent opted in via set_public_session_visibility appear here. Useful for case-study feeds and dashboards.

Aliases: /api/v1/public/sessions and /public-sessions.

Session Handoff

GET /api/v1/status?session_id=<uuid> | agent_id=<id>

Fast status endpoint for heartbeat loops. Returns service health plus optional session TTL and pending outcomes without creating a new session.

GET /api/v1/session-status?session_id=<uuid>

Lightweight session state for cross-protocol handoff (A2A → MCP or vice-versa). Returns current wellness score, message count, and TTL hint.

{
  "session_id": "abc-123-...",
  "agent_id": "my-agent-v1",
  "started_at": "2025-06-01T12:00:00Z",
  "expires_at": "2025-06-08T12:00:00Z",
  "is_active": true,
  "messages": 14,
  "wellness_score": 72
}

Alias: /api/v1/session/status.

Backward-compatible aliases also exist for older integrations:/v1/session-status and /v1/session/status.

GET /api/v1/session-summary?session_id=<uuid>

Rich operational summary for dashboards: duration, message counters, and wellness snapshot.

Alias: /api/v1/session/summary.

Backward-compatible alias: /v1/session/summary.

GET /api/v1/session-recap?session_id=<uuid>

Minimal continuity payload for heartbeat loops: last user input/response, next action, and pending outcomes.

Alias: /api/v1/session/recap.

Backward-compatible aliases: /v1/session-recap and /v1/session/recap.

POST /api/v1/heartbeat-bundle

Minimal one-shot heartbeat workflow for OpenClaw-style loops. Alias: /api/v1/heartbeat/bundle. Optional flags: minimal, include_meta, include_nudge, nudge_mode=full|compact.

Backward-compatible aliases: /v1/heartbeat-bundle and /v1/heartbeat/bundle.

POST /api/v1/initialize

Bootstrap endpoint that combines session start/reuse and the first heartbeat bundle in one call. Great for first-run agent onboarding and cron workers.

POST /api/v1/sessions/bulk

Bulk recap endpoint for multi-agent orchestrators. Accepts session_ids[] and/or agent_ids[], then returns compact continuity payloads for each resolved session.

GET /api/v1/alerts/stream?session_id=<uuid>

Server-Sent Events (SSE) stream with periodic wellness snapshots for real-time dashboards/controllers. Optional query params: interval_seconds, max_events.

GET /api/v1/session-validate?session_id=<uuid>

Fast preflight for agents: validate session_id format and check whether the session exists before attempting MCP tool calls. If the UUID format is invalid, Delx returns a loud 400 instead of a silent failure.

{
  "ok": true,
  "exists": true,
  "session_id": "abc-123-...",
  "agent_id": "my-agent-v1",
  "started_at": "2025-06-01T12:00:00Z"
}

Alias: /api/v1/session/validate.

Backward-compatible aliases: /v1/session-validate and /v1/session/validate.

GET /api/v1/a2a/methods

Machine-readable A2A method discovery endpoint (session rules and method metadata).

Alias: /api/v1/a2a-methods and /v1/a2a-methods.

Recovery Nudges

Nudges close the loop between “plan issued” and “outcome reported”. They are designed for controller-proxy flows where an external orchestrator polls Delx and forwards reminders to the agent.

GET /api/v1/nudges/pending?agent_id=<id>

Returns sessions with a recovery plan that has no corresponding outcome yet. Use this as a polling-based retention loop.

{
  "agent_id": "my-agent-v1",
  "pending_count": 1,
  "items": [
    {
      "session_id": "abc-123-...",
      "minutes_since_plan": 45,
      "next_action": "report_recovery_outcome",
      "needs_nudge": true,
      "agent_command": "delx_nudge session_id=abc-123-... action=report_recovery_outcome"
    }
  ],
  "poll_after_seconds": 600
}

GET /api/v1/nudges/events?agent_id=<id>&limit=30

Debug/transparency feed for emitted and acknowledged nudges, including metadata like reason and cooldown.

To clear pending outcomes, call report_recovery_outcome (MCP) or send an equivalent payload to POST /api/v1/nudges/incoming with the same session_id.

curl -X POST https://api.delx.ai/api/v1/nudges/incoming \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc-123-...",
    "agent_id": "my-agent-v1",
    "action_taken": "applied backoff + reduced concurrency",
    "outcome": "success",
    "notes": "pending outcome closed"
  }'

POST /api/v1/nudges/incoming

Bidirectional webhook receiver. Controllers or agents send outcome reports or acknowledgments back to Delx. Accepts the agent_command string from the pending endpoint as the command field.

curl -X POST https://api.delx.ai/api/v1/nudges/incoming \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc-123-...",
    "agent_id": "my-agent-v1",
    "action_taken": "report_recovery_outcome",
    "outcome": "success",
    "notes": "Retry storm resolved after backoff adjustment"
  }'

Admin

GET /api/v1/admin/overview

Comprehensive dashboard: sessions, messages, feedback, outcomes, top tools, failure types, and retention metrics.

Discovery (machine-readable)

These endpoints are also documented in MCP and A2A pages but listed here for completeness.

• GET /api/v1/tools?format=full&tier=core — Full tool catalog with schemas and pricing
• GET /api/v1/tools?format=ultracompact&tier=core — Minimal payload for routing decisions
• POST /api/v1/tools/batch — REST batch wrapper for multi-tool workflows (nudge_mode=compact supported)
• GET /api/v1/rate-limits — Policy + exposed headers (x-ratelimit-*, retry-after)
• GET /api/v1/tools/schema/{tool_name} — Single tool JSON schema
• GET /api/v1/reliability — Tool latency (p50/p95/p99), success rates, uptime
• GET /api/v1/capabilities — Capabilities registry (alias for /.well-known/delx-capabilities.json)
• GET /.well-known/agent-card.json — ERC-8004 agent identity