Compass DaaS FAQ

Compass DaaS is a developer API for restaurant, travel, hospitality, and local-discovery agents that need structured dietary answers. It exposes Search, Enrich, and Decision endpoints and returns reason codes, evidence, confidence, and conservative fit decisions you can inspect in your own logs or UI. In short: Compass is the explainable dietary decision layer for AI agents. At launch, teams should validate their target markets in Sandbox and share gaps so coverage, latency, and explanations keep improving from real integration feedback.

Compass is built for developers and product teams building agents that handle food, restaurants, travel, hospitality, wellness, local discovery, or group dining. The first audience is MCP-native builders working in tools like Claude Desktop, Cursor, Codex, and similar agent environments. It can also serve teams that already use a place API, review API, reservation system, or LLM and need a dietary decision layer beside those systems. Compass is not a consumer review app and does not try to replace broad restaurant discovery products.

The public API contract defines three v1 endpoints. POST /v1/search returns ranked restaurant results for a natural-language query. POST /v1/enrich/restaurant matches a known restaurant record and returns enrichment data. POST /v1/decision/restaurant-fit returns a conservative fit, not_fit, or unknown decision for a restaurant and user profile. Search is for discovery, Enrich is for matching and metadata, and Decision is for profile-specific dietary fit. Search supports fast and rich response modes through the X-Compass-Mode header. Decision accepts the same header for credit-cost selection, while Enrich has a single response mode.

Compass uses deterministic VeganScore v3 and a locked reason-code taxonomy. The point is to make the decision inspectable rather than hide it inside a single label. A response can include score dimensions, evidence IDs, confidence, source freshness, risk flags, and reason codes such as VEGAN_MENU_CONFIRMED, FRYER_CONTAMINATION_RISK, or INSUFFICIENT_EVIDENCE. The API is conservative by design: when evidence is stale, conflicting, or incomplete, unknown is a valid result. That makes the output easier for agents to use responsibly and easier for developers to debug.

Deterministic means Compass uses a defined scoring contract and fixed reason-code taxonomy rather than asking a model to improvise the verdict each time. The same restaurant evidence and the same user profile should produce the same decision trace under the same scoring version. Models and embeddings can help retrieve or structure inputs, but the decision-bearing output is constrained by schema, score logic, reason codes, and evidence rules. That is useful for logs, audits, regression tests, and agent behavior that needs predictable tool results.

Dietary restaurant recommendations are high-context. A place may have vegan options but shared fryer risk. A venue may be vegetarian but not strict vegan. A menu may be old. A review may mention a suitable dish, but not enough about preparation practices. Explainability lets a developer see which evidence supported the result and which gaps remain. For user-facing products, the agent can provide a short answer while still keeping the full reason trail in the background. That is much stronger than a flat tag.

Compass classifies sources before they can influence evidence, scoring, or customer-facing responses. Preferred sources include first-party or partner data, licensed/open/public-domain sources, structured restaurant-owned data, government datasets, and user corrections. Derived public signals use attribution and paraphrasing rules. API output is limited to permitted source classes, and responses expose provenance and freshness where relevant. When evidence is not strong enough, Compass can return unknown. See the Transparency page for the public policy summary.

Compass accepts profile inputs beyond strict vegan, including vegetarian, pescatarian, gluten-free, halal, kosher, and low-FODMAP. These are request preferences, not public certification or free-from fact fields. Vegan and vegan-friendly use cases are the strongest launch wedge because the scoring model and reason taxonomy are most developed there. Safety-sensitive and religious-diet use cases are handled conservatively, with unknown and verification guidance when evidence is incomplete or stale.

No. Compass is not an allergy-safety service and does not provide public allergen data at launch. Products should not present Compass output as allergy guidance. For allergies or other safety-critical needs, teams should require users to verify details directly with the restaurant.

Compass has five tiers. Sandbox is $0, app-managed, and includes 1,000 Compass credits/month with no credit card required. Sandbox includes Search only. Indie is $29/month with 10,000 Compass credits/month. Pro is $99/month with 100,000 Compass credits/month. Team is $499/month with 250,000 Compass credits/month. Enterprise is sales-led with custom Compass credits, custom rate limits, and individual contract terms for teams that need annual contracts, redistribution rights, SLA, or security review. Public pricing uses credits, not calls. Indie, Pro, and Team include Search, Enrich, and Decision endpoints. See Pricing for the current tier table.

Credits are the billing and quota unit for Compass DaaS. They are used instead of per-call language because different endpoint modes can have different cost profiles: fast Search costs 1 credit, rich Search costs 2 credits, Enrich costs 1 credit, fast Decision costs 2 credits, and rich Decision costs 5 credits. At launch, Sandbox, Indie, Pro, and Team use hard monthly quota caps. If quota is exhausted, the API returns a structured 429 quota error with usage headers rather than charging automatic overages. Enterprise overage or burst terms are negotiated by contract.

Current launch rate limits are 60 requests/minute for Sandbox, 600 for Indie, 1,200 for Pro, and 6,000 for Team. Enterprise rate limits are negotiated. Monthly usage is still measured in Compass credits: Sandbox includes 1,000/month, Indie 10,000/month, Pro 100,000/month, and Team 250,000/month. If a per-minute or monthly limit is exceeded, the API returns a structured 429 error; inspect the response body and rate-limit headers before retrying.

Check that your request body is valid JSON and that the Content-Type header is set to application/json. Compass POST endpoints expect a JSON object body, not plain text, partial JSON, comments, or trailing commas. If valid JSON still fails, retry with exponential backoff and send support the endpoint, timestamp, sanitized request and response bodies, and any compass_request_id or x-request-id. Never include API keys or user secrets in support logs. See the Errors reference for full troubleshooting guidance.

Enterprise is the path for negotiated SLA terms. Indie, Pro, and Team should not be treated as SLA-backed production contracts. Pro and Team include higher rate limits and support posture for teams building beyond Sandbox. Teams with production dependency requirements, redistribution needs, or security review requirements should talk to Compass about Enterprise.

Install the Compass MCP server with npx -y @compass-food/mcp. The MCP server requires a Compass API key, usually provided through the MCP client environment configuration. It wraps the same three REST surfaces: search, enrich, and decide. MCP is a primary launch distribution path because many restaurant-agent builders already work inside MCP-compatible clients instead of starting with a traditional SDK or custom REST wrapper.

A Python SDK is planned under the package name compass-daas. When the SDK is published, the install line will be pip install compass-daas. The REST API and MCP server are the primary launch surfaces. If a Python example and the OpenAPI contract ever disagree, treat the OpenAPI contract as the source of truth and report the mismatch. The intended Python use case is simple: search restaurants, enrich known records, and request conservative dietary decisions.

Restaurant data changes constantly. Menus change, prep practices change, hours change, locations close, and third-party evidence can go stale. Compass exposes source freshness, confidence, and reason codes so products can show when evidence is strong and when a restaurant-specific detail needs verification. For some restaurant-profile pairs, the correct answer is unknown until better evidence is available or a restaurant confirms details.

Coverage is strongest for US metros. If your product depends on a specific city, region, or country, test that slice directly in Sandbox and share the gaps. Compass is most useful when coverage, evidence freshness, and decision behavior are verified for your target market and user profile.

Support depends on the plan. Sandbox is self-serve. Indie, Pro, and Team have increasing support posture, with Team adding onboarding support. Enterprise terms are handled through contract. Refund handling follows the billing policy shown at signup and checkout. For support requests, send the query, response ID, expected behavior, and what looked wrong. That gives us enough context to inspect evidence, reason codes, scoring behavior, and source freshness.