Deelz
    Developer API

    Deelz API docs.

    Build integrations with the Deelz platform. Access alerts, manage searches, and more.

    Quick Start

    Base URL

    https://deelz.co/api/v1

    Authentication

    Include your Deelz API key (generate one in Settings → API Keys) in the Authorization header:

    Authorization: Bearer YOUR_API_KEY

    Secure

    All endpoints require authentication with JWT tokens

    Fast

    Edge functions for low-latency responses worldwide

    RESTful

    Standard REST patterns with JSON responses

    Code Examples

    // Example: Fetch alerts with JavaScript
    const response = await fetch('https://deelz.co/api/v1/alerts', {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    const { data, pagination } = await response.json();
    console.log(data); // Array of alerts

    alerts Endpoints

    GET
    /alerts
    Auth Required

    Retrieve deal alerts (listings matched to the user's saved searches), newest first. deal_score (0–100) is where the price sits in the search's price range: 100 at the bottom, 50 at the top, null when the search has no range.

    GET
    /alerts?id=:id
    Auth Required

    Retrieve a single alert by ID

    PUT
    /alerts
    Auth Required

    Update an alert (e.g., mark as read)

    DELETE
    /alerts?id=:id
    Auth Required

    Delete an alert

    Error Handling

    The API uses standard HTTP status codes and returns errors in the following format:

    {
      "error": "Error message describing what went wrong"
    }

    Common Status Codes

    • 200 — Success
    • 201 — Created
    • 400 — Bad Request
    • 401 — Unauthorized
    • 404 — Not Found
    • 429 — Rate limit exceeded (see Retry-After)
    • 500 — Server Error

    Rate Limits

    API requests are limited to 100 requests per minute per user. Exceeding this limit will return a 429 status code.

    MCP Server (Model Context Protocol)

    Connect AI agents like Claude, Cursor, or custom LLM workflows to Deelz using the MCP standard.

    MCP Endpoint

    https://deelz.co/api/mcp

    Authentication

    Every tool call needs a Deelz API key (prefixed dlz_), generated in Settings → API Keys. Send it either way:

    • As a header: Authorization: Bearer dlz_... (most MCP clients let you set this once)
    • As an auth_token argument on each tool call

    Transport

    Uses Streamable HTTP transport (JSON-RPC over HTTP POST). Compatible with any MCP client that supports the streamable HTTP transport.

    Available Tools (20)

    Alerts
    • list_alerts
    • get_alert
    • mark_alert_read
    • delete_alert
    Searches
    • list_searches
    • create_search
    • update_search
    • delete_search
    Watchlist
    • list_watchlist
    • add_to_watchlist
    • update_watchlist_item
    • delete_watchlist_item
    Bookings
    • list_bookings
    • get_booking
    Profile
    • get_profile
    • update_profile
    Stats & Groups
    • get_stats
    • list_search_groups
    • create_search_group
    • delete_search_group

    Example: List Tools

    curl -X POST "https://deelz.co/api/mcp" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -d '{
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list"
      }'

    Example: Call a Tool

    curl -X POST "https://deelz.co/api/mcp" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json, text/event-stream" \
      -H "Authorization: Bearer dlz_YOUR_API_KEY" \
      -d '{
        "jsonrpc": "2.0",
        "id": 2,
        "method": "tools/call",
        "params": {
          "name": "list_alerts",
          "arguments": { "limit": 10 }
        }
      }'

    Testing

    Use the MCP Inspector to interactively test all available tools:

    npx @modelcontextprotocol/inspector