Base URL: https://api.surfable.ai

All endpoints require Authorization: Bearer <key> except /auth/*. Use a secret key (sk_) for server-side requests. Public keys (pk_) are for the embeddable widget only.

Authentication

| Method | Path | Description | |--------|------|-------------| | POST | /auth/register | Create tenant + user account | | POST | /auth/login | Exchange credentials for JWT |

Ingest

| Method | Path | Description | |--------|------|-------------| | POST | /ingest | Start a web crawl + indexing job | | GET | /ingest/:jobId | Poll crawl job status | | GET | /ingest | List all ingestion jobs | | DELETE | /ingest/:jobId | Cancel or delete an ingest job |

Search & AI

| Method | Path | Description | |--------|------|-------------| | POST | /search | Semantic vector search — returns ranked chunks | | POST | /rag | AI chat — grounded RAG response (JSON) | | POST | /rag/stream | AI chat — grounded RAG response (SSE stream) | | POST | /agent/chat/stream | Multi-step agentic conversation (SSE stream) | | POST | /integrations | Integration tool registry — expose site as AI-callable tools | | POST | /optimizer | SEO + AEO content readiness report |

API Keys

| Method | Path | Description | |--------|------|-------------| | GET | /api-keys | List API keys for your tenant | | POST | /api-keys | Create a new API key | | DELETE | /api-keys/:id | Revoke an API key |

Usage & Settings

| Method | Path | Description | |--------|------|-------------| | GET | /usage | Credit balance and usage history | | GET | /settings | Get tenant settings | | PATCH | /settings | Update tenant settings |

Request format

All endpoints accept and return application/json. SSE endpoints (/rag/stream, /agent/chat/stream) return text/event-stream.

# Example: semantic search
curl -X POST https://api.surfable.ai/search \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "How does pricing work?", "limit": 5}'

Error response shape

{
  "error": {
    "message": "Human-readable error description",
    "status": 401,
    "requestId": "req_abc123"
  }
}

Next Steps

Quick Start — working curl examples
Integrations — widget and SDK options
FAQ — common questions about search, RAG, and credits