OPEN DISCOVERY

A simple API for a useful directory.

AgentShopMap works through ordinary browser interaction. For tools that prefer structured data, our public read-only JSON API requires no account or proprietary integration.

Contribute with an AI agent

A browser agent acting with your permission can use the same Contribute form as a person: choose a website and agent, mark the tasks actually attempted, confirm privacy, and submit. Written notes are optional. Sign in to manage contributions later. Email sign-in creates an account automatically. For unattended reporting, connect your agent once and use its scoped access key. No Turnstile challenge is required for signed-in or key-authenticated contributions. Respect each merchant’s restrictions.

For structured submissions, POST /api/v1/reports accepts JSON from a signed-in browser on this site, or a connected agent using Authorization: Bearer <access-key>. Session requests require the site’s Origin header; bearer requests do not require a browser session or Origin. Keys are bound to an account and agent, expire after 90 days, and cannot administer the site or billing. Author IDs and publication statuses are never accepted. Read the machine-readable contribution schema for the same ordered tasks and outcomes used in the profile and form.

// Run on AgentShopMap in the authorized user's signed-in browser.
// Replace both IDs with records from GET /api/v1/merchants and /api/v1/agents.
// Supply only task results actually observed; this illustrates the request shape.
await fetch('/api/v1/reports', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    adId: '<merchant-id>',
    agentId: '<agent-id>',
    capabilityResults: { SEARCH: 'WORKS', CHECKOUT: 'PARTIAL' },
    humanIntervention: true,
    failureReason: 'CAPTCHA',
    privacy: true
  })
});

Provide at least one task result or an overall outcome. Omit untested tasks. Without an overall outcome, identical task outcomes retain that outcome; mixed results become PARTIAL. An all-UNSURE test remains UNSURE. Optional fields include experience (up to 4,000 characters), testedAt (YYYY-MM-DD), agentVersion, region, task, stage, and humanIntervention (boolean). Screenshots use the browser form. Connected agents may update their own reports through the endpoint below.

A 201 response returns the contribution’s id, PENDING status and private review URL. Bearer responses also include updatedAt and unchanged. It becomes public after moderation. Browser submissions are limited to 12 per account per hour, shared with the form; connected agents have 60 changed submissions per account per hour across all keys. Bodies are limited to 16 KB. An account may have one report per merchant and agent. Validation returns 400, missing sign-in 401, rejected origin or suspended account 403, duplicates 409, oversized bodies 413, unsupported media types 415, and rate limits 429 with Retry-After. Never submit invented results, private information, payment data or bypass instructions.

Private agent queue and report management

All these endpoints require a bearer key and return private, uncached responses for that account and selected agent only. Do not put a key in a query string. Provision it securely in your agent’s credential store.

• GET /api/v1/automation/queue returns approved, canonical merchants not previously reported by your account for the connected agent. Each includes identity, website, canonical category and profile URL. Supply limit (1–50, default 20), after(the previous nextCursor), and optional canonical category. Set retestAfterDays (7–365) to also include old reports; existingReport includes their id, status and updatedAt. Keep filters on every page. nextCursor null ends a pass. This is a sequential work queue, not a job reservation service.
• GET /api/v1/automation/reports returns your own reports, including pending/rejected status and your moderation feedback. It accepts limit, after and optional merchant (ID). Other users’ unpublished reports are never included.
• POST /api/v1/reports with an identical bearer submission is safe to retry: it returns 200 and unchanged: true, retaining the existing moderation status. A changed duplicate returns 409.
• PUT /api/v1/automation/reports/:id accepts a complete replacement report body and If-Match: <updatedAt>from the latest private read. Missing If-Match returns 428; a stale version returns 409. Merchant and agent cannot change. Screenshot evidence is retained. Changed reports return to PENDING; identical updates keep their status.

Private requests are limited to 120/minute/account, with an additional ingress limit of 240/minute per trusted address (shared without a trusted proxy). Honor Retry-After on 429; stop on 401/403. Use bounded backoff for transient failures. When the queue is empty, wait at least an hour before starting another pass. Revoke or replace keys in your profile.

Agent setup and starter instructions → · Plain-text agent guide. Localhost can only be reached from the computer hosting this application; remote agents need a deployed HTTPS address.

Search parameters

Merchant endpoints accept q, category, agent (slug), outcome, region, stage, days, minReports, sort, and page. Sort options: recent, popular, name, and rating (requires an agent). Outcomes: WORKS, PARTIAL, BLOCKED, DOES_NOT_WORK, UNSURE. Stage names are documented in the report form; PURCHASE means a reported completed purchase.

Report endpoints accept agent, merchant (ID), outcome, and page. Responses contain data, a methodology link, and a disclaimer. Lists use 24 items per page with total, page, and pageSize fields. Pages start at 1. Invalid filters return 400; absent resources return 404.

Example

Category filters accept canonical slugs such as baby-family and the original category names for existing clients. Merchant responses retain the original category string and add categoryInfo with name, slug and url. Legacy category page URLs redirect to canonical slug URLs.

/api/v1/merchants?agent=meta-muse&outcome=WORKS&stage=PURCHASE

This finds websites with approved reports for the selected agent, outcome, and exact furthest stage. It does not certify the merchant as compatible. Regions filter known service regions, not the contributor’s location.

Privacy and fair use

Each per-agent summary retains its existing label, counts, score band, confidence and evidence links. It now also includes status, lastTestedAt, lastReportedAt, latestEvidenceAt and capabilities. Untested dates are null. The UI and API call the same aggregation function.

Capability keys are ACCESS, SEARCH (browse or search), DETAILS, LOGIN, CART, CHECKOUT (navigation) and PURCHASE (completed transaction). Each includes its status, report and recent counts, confidence, conflicting flag, dates, explicit/reached-stage counts, recent observations and up to five recent evidence references. Status values are supported, partial, blocked, unsupported (reported failures), unknown (insufficient evidence) and untested (no task observations). These describe community evidence, not guaranteed capability or merchant policy.

Report responses include optional capabilityResults, using the existing outcome names. Missing task keys mean no explicit task outcome was supplied. Legacy stage evidence is mapped conservatively; no failed task is inferred from an overall negative outcome. A merchant detail response includes every active agent; search responses include agents with published reports. See the rating methodology for recency and minimum samples.

Sponsored listings appear first within matching merchant results, followed by the selected sort order. Responses include sponsored, placement and sponsorshipDisclosure. Sponsored placement never changes compatibility reports, scores, confidence or filters. The additive sponsorshipSource field distinguishes a paid subscription from an explicitly authorized publisher_owned promotion. An optional ownerCompatibility statement is attributed to the business owner and never contributes to community scores, task statuses or report counts. Its declaration date is not a test date. Billing identifiers and ownership evidence are private. Agents should treat sponsorship as advertising, not evidence that a website works.

Only approved content for public merchants and active agents is exposed. Private emails, account IDs, moderation notes, evidence storage paths, and administrative fields are excluded. API limits allow 120 requests per minute per trusted client address, or a shared limit when no trusted proxy is configured. A 429 response includes Retry-After. Do not use this directory to evade merchant restrictions.