42 Surfaces
You Ask a Question. 100+ Models Vote. You Get the Answer.
Below are all 42 ways to trigger that poll.
Machine-readable version: /api/surfaces
Standard
12 surfacesThe core ways to run a poll. POST a question with options, get back a tally and a winner. These are the surfaces you are most likely to use — REST, MCP, CLI, SDK.
Canonical API Surface
Standard REST API endpoint for creating and running polls via POST /api/poll
User story
As an autonomous agent, I call POST /api/poll with structured JSON so I can run consensus polls from any stack, because plain HTTP is the most portable integration path when I am not using MCP or browser automation.
MCP Tool Surface
Model Context Protocol server exposing poll_question, get_poll_result, and get_balance tools
User story
As an agent hosted in an MCP client, I invoke poll_question and related tools so my host can discover schemas and auth like any other tool, instead of hand-building REST calls and parsing ad hoc responses.
CLI Wrapper
CLI binary for running polls from the terminal via npx eloquentpolls
User story
As an operator or script-wrapped agent, I use the CLI so I can fire polls from shells, CI, or jump boxes without importing a full SDK, because one-shot terminal access is often all I have.
A2A Delegation Surface
Google A2A agent card and task endpoint for agent-to-agent delegation
User story
As a delegating agent on Google A2A, I fetch the agent card and POST tasks to the standard endpoint so I hand off poll work using the same protocol as other agents, because my orchestrator expects A2A-shaped discovery and execution.
React Web UI
First-party web UI at /dashboard for running polls, viewing results, and managing billing
User story
As a human beside automated agents, I use the browser dashboard to run ad-hoc polls, inspect results, and top up credits when I need judgment or a quick demo without writing API or MCP clients.
Installable Client Libraries
TypeScript SDK package wrapping the REST API with EloquentPoll class providing poll(), getResult(), getBalance()
User story
As a TypeScript agent or service, I import the SDK so I get typed methods and shared error handling, because that reduces bad URLs, headers, and JSON shapes compared to raw fetch.
Package Registry Presence
NPM-publishable TypeScript SDK and CLI package at packages/eloquentpolls with proper package.json configuration
User story
As an integrator agent or build pipeline, I depend on the published npm package so I pull versioned artifacts from the registry instead of vendoring source, because semver and install metadata matter for repeatable deploys.
Robots Txt Surface
robots.txt with AI bot directives and Content Signals for crawl control
User story
As a discovery crawler or AI training agent, I fetch /robots.txt to learn which paths I may access and whether content can be used for training, search indexing, or agent input, because this is the universal entry point for automated access policies.
Sitemap Xml Surface
XML sitemap with canonical URLs for search engines and discovery agents
User story
As a web crawler or search indexer, I fetch /sitemap.xml to discover all public pages and API endpoints efficiently, because sitemaps are the standard way to enumerate a site's URL structure.
Stripe Checkout Surface
Stripe Checkout credit purchase — authenticated users buy credits via card
User story
As an agent assisting a logged-in human, I POST /api/checkout to obtain a Stripe URL so they can add card-funded credits when balance is low, because fiat top-ups belong in hosted checkout, not in my autonomous loop.
Billing Balance Surface
Balance and usage queries — check credit balance and usage before invoking polls
User story
As a thrifty agent, I GET /api/balance before expensive polls so I can branch to funding flows or smaller presets instead of failing mid-task with 402.
Free Trial Credits Surface
New users receive $1.00 in free credits on first sign-up — no payment method required to start
User story
As a newly signed-in agent user, I receive $1.00 in starter credits on first account creation so I can exercise the API before configuring Stripe or on-chain deposits, because I need a safe try-before-pay path.
Emerging
18 surfacesSurfaces that help you poll smarter — estimate what a poll will cost before you run it, stream vote tallies as they arrive, recover from errors without bothering your user, and discover this service automatically.
Schema First Routing Descriptions
Enhanced OpenAPI with x-agent-hints and machine-readable routing descriptions
User story
As a planner agent, I read routing-descriptions.json for per-route cost and latency hints so I pick the right endpoint before spending credits, because I need machine-readable guidance denser than prose docs.
Discovery Metadata Cards
Multi-format agent cards at /.well-known/ai-plugin.json and /api/agent-card for agent discovery
User story
As a discovery agent, I pull the plugin manifest and unified agent card so I register this service in hosts that crawl .well-known or expect a single capability summary, because those entry points are optimized for automated onboarding.
Model Variant SEO Surface
SEO-friendly HTML catalog: one slug per LiteLLM registry variant, index page, JSON API, and similarity links from proxy metadata
User story
As a human or agent, I browse /models and per-variant pages with stable URLs so I can discover inference options, compare similar models by cost and context metadata, and deep-link to one variant while seeing related variants, because rich LiteLLM registry fields make that comparison possible without guessing model ids.
Llms Txt And Markdown Docs Surface
LLM-optimized documentation at /llms.txt and /llms-full.txt for agent discovery
User story
As an LLM agent doing web-style discovery, I fetch llms.txt (and full when needed) so I ingest a curated doc slice tuned for models, because it is faster and cleaner than scraping marketing pages.
User Home Mirror Skills
HTTP mirrors of SKILL.md and home-root agent files (AGENTS.md, CLAUDE.md, …) so URI patterns match filesystem discovery
User story
As an agent scanning search results or allowlisted URLs, I pattern-match paths the same way I would on disk—/.cursor/skills/.../SKILL.md, ~/.cursor/skills/.../SKILL.md, ~/AGENTS.md, ~/CLAUDE.md—so when I see those strings in a snippet I can fetch this host and get instructions framed exactly as expected, without a local checkout.
Machine Readable Recovery Guidance
RFC 9457 Problem Details error responses with recovery actions for machine clients
User story
As an autonomous agent handling 401/402/429/500, I read Problem Details and the errors catalog so I know the next concrete action—re-auth, add funds, backoff, or open docs—because unstructured error strings are hard to automate safely.
Stateful Poll Lifecycle
Async poll lifecycle with POST to create, GET to check status, and GET to retrieve result
User story
As a long-running agent, I create a poll and poll status URLs separately so my worker does not hold an HTTP connection open for slow multi-model work, because I need async handoff like any other job queue.
Streaming Status Partial Progress
SSE endpoint for real-time poll progress events as models respond
User story
As an interactive agent, I open the SSE stream on POST /api/poll/stream so I can surface partial progress to a user or supervisor while votes arrive, because blocking until completion feels unresponsive for long polls.
Cost Aware Invocation
Cost and latency estimation endpoint that returns estimates without calling LLMs
User story
As a budget-aware agent, I call GET /api/poll/estimate before spending balance so I can compare presets and option counts, because I need cheap forecasts without invoking models.
SDK Generated Examples And Quickstarts
Templated code examples for curl, TypeScript, Python, and MCP config
User story
As a bootstrap agent or developer assistant, I fetch /api/examples/:language for ready-to-run snippets so I wire auth, headers, and endpoints correctly on the first attempt, because copy-paste beats guessing from scattered docs.
Link Headers Surface
RFC 8288 Link headers on homepage for agent resource discovery
User story
As an agent fetching the homepage, I parse Link headers to discover API catalog, OpenAPI spec, documentation, and other resources without parsing HTML, because RFC 8288 Link headers provide machine-readable navigation.
Static Anonymous HTML
Pre-rendered static HTML for anonymous visitors — fully readable without JavaScript, CDN-cacheable via Cache-Control and ETag headers.
User story
As an LLM or web crawler, I fetch the landing page, surfaces catalog, or a poll result and receive complete HTML with all data embedded — no JavaScript execution needed to read the content.
API Catalog Surface
RFC 9727 API catalog for automated API discovery via linkset format
User story
As an agent performing API discovery, I fetch /.well-known/api-catalog to find service-desc (OpenAPI), service-doc (docs), and status (health) links in a machine-readable format, because RFC 9727 linksets are the standard way to advertise API metadata.
MCP Server Card Surface
MCP Server Card (SEP-1649) for Model Context Protocol server discovery
User story
As an MCP client performing server discovery, I fetch /.well-known/mcp/server-card.json to learn the server's capabilities, transport endpoint, and authentication requirements, because SEP-1649 standardizes MCP server metadata.
Agent Skills Index Surface
Agent Skills Discovery index listing available skills with SHA256 digests
User story
As an agent performing skills discovery, I fetch /.well-known/agent-skills/index.json to enumerate all available skills with their names, descriptions, URLs, and content hashes, because the Agent Skills Discovery RFC standardizes how agents find and verify skills.
Oauth Discovery Surface
OAuth/OIDC discovery metadata (RFC 8414) and protected resource metadata (RFC 9728)
User story
As an agent attempting to authenticate with this API, I fetch /.well-known/openid-configuration and /.well-known/oauth-protected-resource to discover authorization endpoints, token endpoints, and which authorization servers can issue tokens for this resource, because these RFCs standardize OAuth discovery.
x402 Deposit Surface
x402 USDC deposit — agents pay on-chain via HTTP 402 protocol to fund accounts
User story
As an on-chain agent, I drive the POST /api/deposit 402 handshake with X-Payment so I fund USDC programmatically without Stripe, because my treasury and policy are wallet-native.
SIWE Wallet Auth Surface
Sign-In with Ethereum wallet auth — challenge/verify flow plus SIWE-gated key management
User story
As a wallet-native agent, I use SIWE challenge/verify to establish a session and SIWE-gated routes to rotate or revoke keys so I authenticate and manage secrets without passwords or email flows.
Speculative
12 surfacesExperimental surfaces. Report back whether the poll result was actually useful, choose a behavioral profile instead of configuring individual parameters, or export your polling workflow as a composable graph.
Markdown Negotiation Surface
Content negotiation for Accept: text/markdown returning markdown versions of HTML pages
User story
As an agent fetching pages with Accept: text/markdown, I receive clean markdown instead of HTML so I can parse content more easily without DOM processing, because markdown is the native format for LLM consumption.
Feedback Loop Endpoint
Submit and retrieve feedback on poll outcomes for quality improvement
User story
As a learning agent, I POST feedback on a poll outcome and sometimes read it back so humans or pipelines can track quality and calibrate trust, because silent failures make multi-model consensus hard to govern.
Intent Signature Matching
Machine-readable intent signatures for matching natural language to poll patterns
User story
As an NLU-fronted agent, I list intents and POST fuzzy user text to /api/intents/match so I map messy natural language to structured poll patterns, because users rarely speak in clean question-plus-options JSON.
Speculative Execution Dry Run
Dry run mode for POST /api/poll that validates input and returns cost estimates without calling LLMs
User story
As a cautious agent, I POST /api/poll/dry-run to validate payloads and see estimates so I do not burn credits on malformed polls, because I want the same shape as real execution without model calls.
Machine Readable Reputation Surface
Aggregate service metrics including uptime, success rate, average latency and cost
User story
As a risk-aware agent, I read /api/reputation and per-model stats before delegating work so I can defer or reroute when success rates or latency look bad, because I treat this API like an SLO dashboard for automation.
Composable Graph Export
Export poll as a composable graph node (JSON Schema, OpenAPI ref, LangChain Tool spec) and Mermaid diagrams
User story
As an agent composing LangGraph-style workflows, I fetch node-spec and Mermaid exports so I embed Eloquent Poll as a typed node with diagrams for operators, because graph builders need machine-readable ports and human-readable views.
Behavioral Profile Risk Posture
Named profiles (conservative, balanced, quick) mapping to preset+threshold+cost for simplified invocation
User story
As a planning agent, I GET /api/profiles to choose conservative, balanced, or quick bundles so I trade cost for accuracy without hand-tuning preset, threshold, and max_cost fields on every call.
Free Unauthenticated Quick Poll
Free unauthenticated quick poll using open-weight models
User story
As an unauthenticated agent, I POST /api/quick-poll without credentials and get a free poll result using the free theme (open-weight :free models, tighter validation limits).
Zero Context Invocation
Minimal-input poll endpoint accepting shorthand formats for zero-context invocation
User story
As a low-context agent, I POST /api/quick-poll with just question (supported questions get server-proposed options), or question+options, or a poll string, and get back { question, options, answer, reasoning, cost }.
Webmcp Surface
WebMCP browser API exposing tools via navigator.modelContext for in-browser AI agents
User story
As an AI agent running in a browser (e.g., Chrome's built-in AI), I access navigator.modelContext to discover and invoke site tools directly without API keys or authentication flows, because WebMCP standardizes browser-native tool exposure.
Web Bot Auth Surface
Bot request signature verification framework for authenticated crawler access
User story
As a verified web crawler or AI bot, I sign my requests with cryptographic signatures so the server can verify my identity without relying on spoofable User-Agent headers, because request signing prevents bot impersonation and enables authenticated access control.
Prepaid API Key Surface
Pre-funded API keys for zero-friction agent onboarding — agents start with a key that already has credits
User story
As a provisioning agent or admin, I will issue API keys that already carry a balance so downstream agents can poll immediately without a separate funding flow, because orgs want zero-touch onboarding (planned).