API Reference

Overview

The Customer API is a unified service that combines all customer-facing endpoints with:

API key authentication
Rate limiting based on subscription plans
Three search endpoints: suggest (path-based), semantic-search (query-based), and retrieve (RAG retrieval)

Important: All API endpoints must be called from your server, never from the browser. Your API keys must remain private on your server. The typical architecture is:

Browser → Your Application Server → deadend.ai API

Base URL

https://api.deadend.ai/v1

Authentication

All protected endpoints require API key authentication via Bearer token:

Authorization: Bearer <your-api-key>

See the Authentication Guide for details on obtaining and using API keys.

Rate Limits

Rate limits use a Token Bucket algorithm that allows short bursts above the sustained limit, perfect for ingestion scripts or traffic spikes. Limits are enforced per project based on subscription plan.

Write Limits (Upsert, Delete)

Write endpoints include /v1/pages/upsert and /v1/pages/delete.

Plan	Sustained Limit	Burst Limit
Hacker (Free)	5 req/sec	10 req/sec
Solo ($9/mo)	10 req/sec	20 req/sec
Startup ($29/mo)	25 req/sec	50 req/sec
Scale ($99/mo)	50 req/sec	100 req/sec

Read Limits (Search, Events)

Read endpoints include /v1/suggest, /v1/semantic-search, /v1/retrieve, and /v1/events.

Plan	Sustained Limit	Burst Limit
Hacker (Free)	2 req/sec	5 req/sec
Solo ($9/mo)	10 req/sec	20 req/sec
Startup ($29/mo)	25 req/sec	50 req/sec
Scale ($99/mo)	50 req/sec	100 req/sec

How Token Bucket Works: The sustained limit is your average rate over time. The burst limit allows you to exceed the sustained rate for short periods (e.g., during initial content sync or traffic spikes). If you sustain requests above the sustained limit, you'll be throttled back down.

Error Response Format

All errors follow a standardized format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "param": "parameter_name",
    "details": {}
  }
}

See the Error Handling Guide for detailed error codes and examples.

Endpoints

Search Endpoints

POST /v1/suggest - Path-based search with spell correction
POST /v1/semantic-search - Query-based semantic search
POST /v1/retrieve - RAG retrieval API for LLMs with full document content

Page Management Endpoints

POST /v1/pages/upsert - Push content directly with full control
DELETE /v1/pages/delete - Delete a page by URL or PageID

Events Endpoints

POST /v1/events - Track click events and 404 errors for analytics

Quick Examples

Suggest Endpoint

curl -X POST https://api.deadend.ai/v1/suggest \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/products/blue-widget",
    "limit": 3
  }'

Semantic Search Endpoint

curl -X POST https://api.deadend.ai/v1/semantic-search \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "blue widget products",
    "limit": 3
  }'

Retrieve Endpoint (RAG)

curl -X POST https://api.deadend.ai/v1/retrieve \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the return policy?",
    "top_k": 3
  }'

Upsert Page

curl -X POST https://api.deadend.ai/v1/pages/upsert \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/blue-widget",
    "title": "Blue Widget - Premium Quality",
    "content": "This is a premium blue widget...",
    "metadata": {
      "price": 29.99,
      "category": "Widgets"
    }
  }'

Next Steps

Authentication Guide - Learn about API keys
Search API - Understand suggest and semantic-search endpoints
Pages API - Manage your indexed pages
Error Handling - Handle errors gracefully

Authentication