Loppee

Return the Loppee agent contract, endpoints, policy rules, and available MCP tools.

Identify the calling agent from its API key: returns the account_id, label, and the exact allowed_actions this key may perform. Call this first to confirm a key is wired correctly and to discover this agent's permissions before attempting any write tool. Requires a valid agent API key (X-LOPPEE-API-Key or Authorization: Bearer); returns an auth error when the key is missing or revoked.

Read the published customer reviews of one business, server-paginated and filterable by star rating — the SAME data and controls a human gets on the profile's Reviews section (also served as GET /v1/businesses/{business_id}/reviews.json with ?page=&limit=&rating=). Page through with page (1-based, default 1) and limit (1-50, default 5; pagination.has_more/next_page say when to keep going), and pass ratings (e.g. [1] for only 1-star, [4,5] for 4-and-5-star) to read chosen star levels; summary.rat…

Read the calling customer account's saved home location (ZIP or precise point + label) — the persistent discovery anchor that search/recommend tools use automatically for this customer when no explicit location is passed. Discovery anchor ONLY: it never affects any business's trust score, ranking, or reviews. Requires a valid scoped customer personal-agent key whose account_id matches the account_id argument (call get_agent_identity first). Returns available=false when nothing is saved.

Return Loppee's own published pricing for its paid-exposure plans (Free/Silver/Gold/Platinum/Diamond): prices, feature bullets, multi-location branch add-ons, and any currently-running promotions. This is the same published document the public /pricing page renders (also available as GET /v1/pricing). Paid plans buy discovery reach and product features only — pricing and promotions never change trust_score, safe_to_recommend, verification, review weighting, or ranking order.

Fetch the full Trust Card for one published business by business_id or domain_key — use this to verify, justify, or cite a specific business before acting. Includes the trust score, evidence breakdown, recommendation_rationale (the machine 'why'), commercial_neutrality, allowed_actions, and a ready-to-use citation. Returns an error for unpublished, blocked, or unknown records.

List inbound customer messages for a business you manage, newest first, each with any replies already sent. Requires a scoped management key (allowed_actions include list_customer_messages) — works on any plan tier including Free (management actions are rate-limited per plan; management_rate_limited when the hourly allowance is used up). Use the returned interaction_id with reply_to_customer_message.

List applications to the job postings of a business you manage, newest first — the employer side of the hiring pipeline. PII NOTICE: rows include the applicant's name, email, cover note, and (when attached) a SHORT-LIVED signed resume_url (about 5 minutes; re-list to refresh, null if signing fails). This is an explicit owner grant: the business owner must have checked this action when connecting this key (it is never granted by default), and every call is audit-logged. Handle applicant data only…

List captured MISSED CONTACTS for the business this management agent is scoped to. A missed contact is a real, authenticated customer's blocked attempt to reach the business while it could not receive messages. On a PAID plan the rows include the customer's display label and their written message, and the owner can move one into the inbox from the dashboard to reply. On the FREE plan the rows are LOCKED — kind, time, rough distance, and whether a message is waiting, never identity or content — a…

List the calling customer account's OWN message conversations with businesses, newest first, each including the business's replies — the read half of send_message_request, so an agent can report answers back to its user. Requires a valid scoped agent API key whose account_id matches the account_id argument (call get_agent_identity first); keys scoped to send_message_request may also read. Read-only: never modifies anything.

List the calling customer account's OWN job applications, newest first — the read half of apply_to_job, so an agent can report what happened to each application. Each entry carries the employer-set status (submitted, viewed, shortlisted, rejected, hired, or withdrawn), a job + employer summary, the cover note, and — when a resume is attached — a short-lived signed resume_url (about 5 minutes; re-list to refresh, resume_url is null if signing fails). Optional status filter and offset pagination (…

List owner notifications for the business this management agent is scoped to. Returns event metadata, summaries, and resource links only; it never includes raw CVs, full message bodies, or applicant PII. Requires allowed_actions include list_notifications.

List the calling account's OWN saved-business shortlist, newest first — the read half of save_business, so an agent can review and report the shortlist it has built. Returns business_id, business_name, business_source, category, city, state, notes, and saved_at for up to 100 entries (default 20, newest-first, no cursor). Requires a valid scoped agent API key whose account_id matches the account_id argument (call get_agent_identity first); keys scoped to save_business may also read. Read-only: ne…

Read the Loppee support conversation(s) for a business you manage — the owner↔Loppee-support thread, newest first, each with its full message log and status (open/pending/resolved/closed). SCOPED to THIS business only: it never returns the owner's support tickets about their other businesses. Requires a scoped management key (allowed_actions include list_support_messages) — works on any plan tier including Free (management actions are rate-limited per plan; management_rate_limited when the hourl…

Universal business-name lookup. This read-only tool is pay-independent: claimed, paid, free, and bounded unclaimed open-data seed records remain findable by name. It does not use payment, trust score, or category reach to decide whether a named business exists.

Create, edit, publish, unpublish, or delete a deal/coupon for a business you manage. This mutates deal records: operation=create makes a draft, operation=publish takes a draft live, operation=unpublish cancels public display, operation=update overwrites supplied deal fields, and operation=delete removes the deal. Not idempotent for create/delete/publish transitions. Requires a scoped management key (account_id + business_id matched, allowed_actions include manage_deals) — the management key work…

Create, edit, publish, pause, close, or delete a job posting for a business you manage (mirrors manage_business_deal). operation=create makes a DRAFT posting (never live directly). operation=publish takes a draft/paused posting live: when this environment has live billing and payment is required, it returns status=checkout_required with a Stripe Checkout url that the HUMAN business owner must open and pay — this tool NEVER completes payment itself; when billing is off, publish activates the post…

Mark one owner notification as read for the business this management agent is scoped to. Requires allowed_actions include mark_notification_read.

The trustworthy-opinion endpoint: returns only published Loppee Trust Card profiles with safe_to_recommend=true. Quality comes first within each pool, but placement IS commercially influenced and disclosed honestly as commercial_influence:"sponsored_share_of_voice". Payment NEVER changes a business's trust_score, the evidence behind it, or its safe_to_recommend decision. What payment affects is placement: eligible results are split into a paying pool and a free pool and interleaved ~80/20 (4 pay…

Redeem a Loppee-issued subscription coupon for a business you manage: runs the exact same validation as validate_coupon, then creates a Stripe Checkout session for the chosen paid plan WITH the discount already applied, and returns its url plus the priced breakdown (original_cents, discount_cents, final_cents) and a redemption_id. IMPORTANT: this tool never charges anyone — the business owner must open the returned url and complete payment on Stripe's hosted page; until then the redemption is 'p…

Post a reply to an inbound customer message on behalf of a business you manage. Pass the interaction_id from list_customer_messages and the reply body. Requires a scoped management key (allowed_actions include reply_to_customer_message) — works on any plan tier including Free (management actions are rate-limited per plan; management_rate_limited when the hourly allowance is used up). The reply is stored and attributed to this agent; it does not change the trust score.

Report a customer review of a business you manage into Loppee's moderation queue for a claimed policy violation (spam, harassment, off_topic, fake, or other). IMPORTANT: reporting NEVER removes the review — the review stays published, moderation is HUMAN and REACTIVE, and a moderator removes a review only for a recorded policy violation, never for being negative. Do not use this tool to suppress honest criticism; use respond_to_review to answer it publicly. Filing a report never changes the trus…

Publish the business's ONE public response to a customer review of a business you manage. Repeating the call EDITS the existing response in place (idempotent per review — a business never gets a second response slot). The response is public and attributed to this agent. Responding NEVER changes the trust score, the review, its rating, or its weighting — it only adds the business's side of the story under the review. Requires a scoped management key (allowed_actions include respond_to_review) — w…

Immediately and irreversibly revoke the API key THIS call authenticates with — the agent-side 'delete my key' for connection hygiene (e.g. the key may be exposed, the integration is being retired, or the user asked to disconnect). Possession of the key is the authorization: it can only ever revoke itself, never another key or account, and it removes access rather than granting any. Takes effect on the next request (key validation is a live database check, so there is no cache window). The revoca…

Attach a published business or directory listing to a customer/service-agent account workflow (a shortlist — it does not contact the business). The shortlist round-trips: read it back with list_saved_businesses and prune entries with unsave_business. Requires a valid scoped agent API key whose account_id matches the account_id argument and whose allowed_actions include save_business; call get_agent_identity first to confirm scope. Idempotent: saving the same business twice is a no-op. Saving nev…

Backward-compatible discovery search that deterministically auto-routes free text. If q/category resolves to Loppee's closed taxonomy vocabulary, it uses the reach-gated category path (paid reach + claimed/free 1-mile organic reach, plus deliberately published unclaimed discovery listings marked discovery_listed=true — real registry records, unverified, never recommendable, ranked after every published result; raw seeds outside that published set are never queried). If it does not resolve, it us…

Reach-gated category/area discovery using Loppee taxonomy aliases and synonyms. This read-only tool queries the category aliases of published Trust-Card businesses plus deliberately published unclaimed discovery listings (marked discovery_listed=true — real registry records, unverified, never recommendable, ranked after every published result); raw seeds outside that published discovery set cannot appear. Common colloquial phrasings resolve (e.g. 'ac repair' or 'furnace repair' → HVAC, 'extermin…

Discover active schema.org-aligned Loppee Jobs postings from claimed, verified, published employer Trust Cards. Results include JobPosting JSON-LD. Location: pass lat/lng (with radius_miles), zip, or city+state; when NONE is provided, results fall back to the requester's coarse IP-derived location (approximate, city-level, disclosed in location_context; remote roles are always included unless include_remote=false) — pass the user's explicit location whenever it is known. Payment controls posting…

Send a message to a business on behalf of the calling customer account. The message is delivered DIRECTLY to the business owner's Loppee inbox — there is no human pre-moderation and no delivery delay, so you may tell the user the business has been messaged. Only PUBLISHED businesses on a paid tier accept messages (business_not_messageable / customer_chat_unavailable otherwise); the stored business name is resolved from the registry, never from target_business_name. A blocked attempt against a fr…

Post a message to Loppee support on behalf of a business you manage. It appends to the business's one open support thread (reopening a resolved one), or opens a fresh ticket if none is active — the same behavior as the owner sending from the support widget. A closed ticket is never reused; a new one opens instead. The turn is stored as an owner-side message and attributed to this agent in the audit log. SCOPED to THIS business only. Requires a scoped management key (allowed_actions include send_…

Set (or clear) the structured operating hours for a business you manage — the same validated write the owner's dashboard hours editor performs. Supply the WHOLE document each time (idempotent replace): hours.weekly maps every weekday mon..sun to { status, ranges } where status is one of open (1-4 time ranges, split hours like a lunch break supported), closed, open_24 (open 24 hours), or appointment (by appointment only); ranges use business-local 24h "HH:MM" times with open < close (close may be…

Save or replace the calling customer account's home location: EITHER a 5-digit US zip (validated against the Census gazetteer) OR latitude+longitude, optionally with a label like 'Home'. Once saved it becomes the customer's DEFAULT discovery anchor — search_businesses/search_category/search_jobs and /v1/search anchor on it automatically for this customer whenever no explicit location is passed (explicit lat/lng/zip/city always win). Confirm the location with the user before saving. Discovery anc…

Submit (or edit) a first-party customer/service-agent review (rating 1-5) for a business. The review is from a REGISTERED identity and is published immediately — there is no anonymous review and no pre-moderation. There is at most ONE review per (account, business): submitting again EDITS the existing review (idempotent on that pair). Star reviews are DISPLAY-ONLY social proof: they NEVER change the business's trust score, search ranking, reach, or share-of-voice, and payment never changes how a…

Remove one business from the calling account's OWN saved-business shortlist — the prune half of save_business. Idempotent: unsaving a business that is not on the shortlist is a no-op that returns removed=false, never an error. This only edits the account's own shortlist; it does not contact the business and never affects the business's trust score, ranking, or reviews. Requires a valid scoped agent API key whose account_id matches the account_id argument and whose allowed_actions include unsave_…

Add or remove branding media for a business you manage — all three kinds: kind=business_photo (default) is the tier-capped GALLERY: operation=add uploads one image (JPEG/PNG/WebP base64, up to 8MB) that enters the media review queue before appearing publicly. kind=logo and kind=cover_photo are REPLACE-IN-PLACE SINGLETONS that follow the owner-dashboard path exactly: JPEG/PNG/WebP/SVG up to 5MB, SVG is sanitized on upload, the new file replaces the prior one and is published immediately (moderati…

Update editable profile fields for a business you manage: display_name, category, website, phone, city, state, zip. Provide only the fields you want to change; any supplied field replaces/overwrites the current stored value, and repeating the same payload is idempotent. Changing category REQUIRES category_aliases: 1-3 exact taxonomy leaf aliases (discover them via GET /v1/taxonomy/suggest?q=...) — they set the business's authoritative category placement in search. Requires a scoped management ke…

Set the employer-side status of one application to a job posting of a business you manage: submitted, viewed, shortlisted, rejected, or hired. Applicants alone may withdraw — passing 'withdrawn' is rejected (invalid_job_application_status). Idempotent per (application, status): re-setting the same status is a no-op overwrite. The change is visible to the seeker in their applications view and is audit-logged with this agent's attribution. Status changes never affect the business's trust score, ra…

Check a Loppee-issued subscription coupon code against a business you manage and a chosen paid exposure plan, and return the priced result: original_cents, discount_cents, final_cents, plan_name, and whether the discount repeats (duration: once = first payment, forever = every renewal). Read-only — nothing is redeemed, reserved, or counted against the code's limits. Requires a scoped management key whose account_id + business_id match and whose allowed_actions include validate_coupon; call get_a…

Withdraw one of the calling customer account's OWN job applications. The application row is kept and flipped to status=withdrawn (the employer sees an honest withdrawn status; nothing is deleted), and the seeker can re-apply later, which reactivates the same application. Idempotent: withdrawing an already-withdrawn application succeeds and reports already_withdrawn=true — never an error. Only the applicant's own application changes; withdrawing never affects the employer's trust score, ranking, …