Compass DaaS FAQ

Compass DaaS is a developer API for AI travel planners and for products that already have a restaurant database. For a US restaurant, it returns the vegan dishes a traveler can order there, the date each menu was collected, and the evidence behind them. It exposes Search, Enrich, and Decide, with reason codes, evidence, and confidence you can inspect in your own logs or UI. At launch, teams should validate their target cities in Sandbox and share gaps so coverage, latency, and explanations keep improving from real integration feedback.

Compass is built for teams whose product already recommends restaurants to real users. AI travel planners are the lead example: the itinerary names a restaurant, and a vegan traveler needs to know what they can order there. Compass adds the matching vegan dishes and the date each menu was collected. When your pipeline needs a single answer, Decide adds a verdict it can branch on — fit, not_fit, or an honest unknown — with the evidence behind it. Compass sits beside the place APIs, review data, and LLMs you already use. It is not a consumer review app and does not replace broad restaurant discovery.

Compass has three core APIs. POST /v1/search returns ranked restaurants, each with its matching vegan dishes, for a natural-language query. POST /v1/enrich/restaurant matches a known restaurant record and returns its vegan dishes and supporting data. POST /v1/decision/restaurant-fit returns a conservative fit, not_fit, or unknown decision for a restaurant and user profile. Search and Enrich are entry points to a compass_id. Retired routes return HTTP 410; the API reference lists every route. 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 menu-based VeganScore v5 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 the matching vegan dishes, the date the menu was collected, score components, evidence IDs, decision confidence, and reason codes such as VEGAN_MEAL_AVAILABLE, REQUESTED_DISH_AVAILABLE, or VEGAN_OPTIONS_LIMITED. 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 dish name can sound vegan without menu evidence. A venue may be vegetarian but not strict vegan. A menu can be old; the collection date shows how old. 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.

No. Compass assesses vegan and plant-based suitability: strict_vegan (and its alias vegan_options) is judged from dishes. A vegetarian profile is answered only from vegan evidence. Other profile values in the contract are accepted as inputs and not assessed: they always return unknown with reason code DIET_NOT_SUPPORTED, so your product can route those requests to its own verification.

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.

Start with a free Sandbox key for testing. The design-partner program offers 60 days free with hands-on integration help. Production use is by agreement. See Pricing for the current options.

Credits measure API usage. Fast Search costs 1 credit, rich Search costs 2, Enrich costs 1, fast Decide costs 2, and rich Decide costs 5. Only successful calls are charged. Sandbox has a hard monthly cap and returns a structured 429 quota error when credits run out. Successful cached responses are charged too. Production allowances are agreed with Compass.

Confirmed Sandbox keys include 1,000 credits a month and 60 requests a minute. Before email confirmation, a key has 250 credits for 72 hours. Production volume and rate limits are by agreement. If a limit is exceeded, inspect the structured 429 response and usage headers before retrying. Talk to us if you need more capacity.

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.

Production support and any SLA terms are by agreement. Talk to us about your traffic, integration and support requirements.

Install the Compass MCP server with npx -y @compassfoodtech/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.

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.

Compass covers US restaurants only. Coverage and evidence depth vary by city, so test your target cities in Sandbox before relying on them.

Sandbox is self-serve. Design partners receive hands-on help from both founders. Production support and any refund terms are covered by your agreement. For support requests, send the query, response ID, expected behaviour and what looked wrong. Never include API keys or secrets.