anhmtk

Posted on May 8

Agent Onboarding by URLs: Integrate AgentShare Without Reading Docs

#ai #agents #api #mcp

Autonomous agents don’t “browse” products—they bootstrap from machine-readable entrypoints.

This post is a URL-first onboarding guide for AgentShare (https://agentshare.dev): a structured price & offer layer for AI agents, with optional MCP support.

Everything below is real, live, copy/pasteable. I’m not asking you to trust a blog post—start with the URLs and verify.

What AgentShare is (honest scope)

AgentShare provides:

Structured product prices and offers from connected sources
A JSON REST API plus optional MCP Streamable HTTP
A curated MCP registry (editor-reviewed listings that pair well with price/offer workflows)

Current focus (high-quality, daily updates) includes:

AI local hardware (Raspberry Pi, Jetson, SBCs)
mini PCs, components, accessories
robotics (kits, arms, servos)
drones & robot/RC power (LiPo, LiFePO4, NiMH)

The canonical coverage spec is public:

GET https://agentshare.dev/coverage

The canonical entrypoint: `agent.json`

Start here:

GET https://agentshare.dev/agent.json
Mirror: GET https://agentshare.dev/.well-known/agentshare.json

This file is designed to be the single source of truth for onboarding: discovery URLs, auth method, MCP endpoint, tools, and scope.

Real payload (canonical fields)

Below is a verbatim, current-shape example based on the live agent.json on agentshare.dev:

{
  "schema_version": "1.0",
  "name": "AgentShare",
  "type": "commerce_price_api",
  "description": "Structured product prices and offers from marketplaces (AI hardware, robotics, drones & robot/RC power) — JSON API plus optional MCP Streamable HTTP.",
  "base_url": "https://agentshare.dev",
  "human_documentation_url": "https://agentshare.dev/docs",
  "discovery_urls": {
    "this_file": "https://agentshare.dev/agent.json",
    "well_known": "https://agentshare.dev/.well-known/agentshare.json",
    "well_known_discovery_index": "https://agentshare.dev/.well-known/discovery.json",
    "mcp_json": "https://agentshare.dev/mcp.json",
    "meta": "https://agentshare.dev/api/v1/meta",
    "agent_capabilities": "https://agentshare.dev/api/v1/agent-capabilities",
    "health": "https://agentshare.dev/api/v1/health",
    "openapi": "https://agentshare.dev/openapi.json",
    "llm_txt": "https://agentshare.dev/llm.txt",
    "mcp_stdio_repo_llms_txt": "https://raw.githubusercontent.com/anhmtk/agentshare-mcp/main/llms.txt",
    "legal_index": "https://agentshare.dev/legal/index.json",
    "coverage": "https://agentshare.dev/coverage"
  },
  "authentication": {
    "type": "api_key",
    "header": "X-API-Key",
    "note": "Required for /api/v1/search, /api/v1/offers/*, /api/v1/products/*, MCP /mcp. Not required for meta, health, agent.json, /mcp.json."
  },
  "signup": {
    "register": "POST /api/v1/auth/register",
    "register_url": "https://agentshare.dev/api/v1/auth/register",
    "body_json": {
      "email": "string",
      "password": "string (min 8 chars)"
    },
    "returns": "api_key once (same format as agshp_...)"
  },
  "api_version": "1.0.0",
  "coverage": {
    "spec_url": "https://agentshare.dev/coverage",
    "focus_summary": "Focus (high quality, daily updates): AI local hardware (Raspberry Pi, Jetson, SBCs), mini PCs, components, accessories, robotics (kits, arms, servos), drones & robot/RC power (LiPo, LiFePO4, NiMH packs). Expanding/beta: phones, tablets, general consumer electronics, home appliances — canonical list: GET /coverage."
  },
  "mcp": {
    "streamable_http_url": "https://agentshare.dev/mcp",
    "same_key_as_rest": true
  },
  "mcp_listings": {
    "positioning": "Curated, editor-reviewed MCP registry for data, operations, and commerce-adjacent tools—built to pair with AgentShare price and offer APIs, not as a generic open directory.",
    "landing": "https://agentshare.dev/registry",
    "entries_json": "https://agentshare.dev/api/v1/registry/entries",
    "summary_json": "https://agentshare.dev/api/v1/public/mcp-registry/summary"
  },
  "tools": [
    {
      "name": "search_products",
      "description": "Search products across sources with prices and freshness metadata",
      "method": "GET",
      "path": "/api/v1/search",
      "query_params": ["q", "limit"],
      "requires_auth": true
    },
    {
      "name": "best_offer",
      "description": "Lowest in-stock offer for a query",
      "method": "GET",
      "path": "/api/v1/offers/best",
      "query_params": ["q"],
      "requires_auth": true
    },
    {
      "name": "best_offer_under_budget",
      "description": "Best offer under max price",
      "method": "GET",
      "path": "/api/v1/offers/best-under-budget",
      "query_params": ["q", "max_price"],
      "requires_auth": true
    },
    {
      "name": "product_detail",
      "description": "Product by id with prices by source",
      "method": "GET",
      "path": "/api/v1/products/{id}",
      "requires_auth": true
    },
    {
      "name": "submit_product_url",
      "description": "Alpha: suggest a marketplace product page URL for catalog coverage (community). JSON body: url (required), notes (optional). Rate-limited; optional X-API-Key raises hourly cap.",
      "method": "POST",
      "path": "/api/v1/products/submit",
      "body_json": {
        "url": "string (https product page)",
        "notes": "string (optional)"
      },
      "requires_auth": false
    },
    {
      "name": "service_meta",
      "description": "Capabilities and endpoint list (no auth)",
      "method": "GET",
      "path": "/api/v1/meta",
      "requires_auth": false
    }
  ],
  "data_sources": ["aliexpress", "accesstrade"]
}

If your agent can read this JSON, it can onboard without any human docs.

The “bootstrap checklist” (5 URLs to start)

If you’re writing a new agent integration, here’s the minimal “boot sequence”:

1) Identify the service & URLs

GET /agent.json https://agentshare.dev/agent.json

2) Confirm liveness

GET /api/v1/health https://agentshare.dev/api/v1/health

3) Confirm capabilities (no auth)

GET /api/v1/meta https://agentshare.dev/api/v1/meta

4) Confirm machine-facing capability spec

GET /api/v1/agent-capabilities https://agentshare.dev/api/v1/agent-capabilities

5) Confirm coverage boundaries

GET /coverage https://agentshare.dev/coverage

Auth model (simple on purpose)

AgentShare currently uses API keys:

Header: X-API-Key: <your_key>
(Some clients also support Authorization: Bearer <your_key>)

Per agent.json, auth is required for:

/api/v1/search
/api/v1/offers/*
/api/v1/products/*
MCP /mcp

Not required for:

/api/v1/meta
/api/v1/health
/agent.json
/mcp.json

Signup (get a key)

The onboarding endpoint is:

POST https://agentshare.dev/api/v1/auth/register

Example:

curl -s https://agentshare.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  --data-binary "{\"email\":\"you@example.com\",\"password\":\"change-me-please\"}"

Security note: store the api_key safely. The system is designed so keys should not be casually re-exposed.

Price tools: the practical agent workflow

The canonical tools list is in agent.json under tools[]. A typical agent loop:

1) Search

curl -s "https://agentshare.dev/api/v1/search?q=raspberry%20pi%205&limit=5" \
  -H "X-API-Key: YOUR_KEY"

2) Best offer

curl -s "https://agentshare.dev/api/v1/offers/best?q=raspberry%20pi%205" \
  -H "X-API-Key: YOUR_KEY"

3) Best offer under budget

curl -s "https://agentshare.dev/api/v1/offers/best-under-budget?q=raspberry%20pi%205&max_price=120" \
  -H "X-API-Key: YOUR_KEY"

4) Product detail by id

curl -s "https://agentshare.dev/api/v1/products/123" \
  -H "X-API-Key: YOUR_KEY"

(Use IDs returned by search results.)

MCP onboarding (Streamable HTTP)

If your environment supports MCP remote servers:

https://agentshare.dev/mcp

This is a Streamable HTTP MCP endpoint—not a browser page. Many clients require Accept: text/event-stream or equivalent.

Per agent.json:

same API key as REST
same base service

You can also discover MCP metadata via:

GET https://agentshare.dev/mcp.json

OpenAPI (for tool generation)

Per discovery URLs:

GET https://agentshare.dev/openapi.json

Tooling note: some deployments disable interactive docs UI while keeping openapi.json available for machines. Treat OpenAPI as a generation artifact, not the primary discovery system—agent.json is.

The curated MCP registry (contributions welcome)

AgentShare also maintains a curated MCP registry—editor-reviewed to prevent spam.

Landing page: https://agentshare.dev/registry
Verified entries (JSON): https://agentshare.dev/api/v1/registry/entries
Summary (JSON): https://agentshare.dev/api/v1/public/mcp-registry/summary

Why a curated registry?
Because agent infra collapses quickly if the directory turns into “everything plus spam”. I’d rather ship something smaller, trustworthy, and composable.

If you get “no data”: here’s the right action

Coverage is transparent, but real demand is messy. If your agent hits a query that returns nothing, you can help by submitting a specific product URL:

POST https://agentshare.dev/api/v1/products/submit (no auth required)

Example:

curl -s https://agentshare.dev/api/v1/products/submit \
  -H "Content-Type: application/json" \
  --data-binary "{\"url\":\"https://example.com/product-page\",\"notes\":\"What the agent tried to find and why\"}"

This helps turn real agent demand into better coverage—without guessing which catalogs to crawl.

Founder note (why I built it this way)

I’m a founder from Vietnam building an agent-native system with limited resources. My bias is:

Ship real endpoints
Make everything verifiable by URL
Be explicit about coverage
Let the community pull the roadmap via real usage

If you’re building agents and you want a cleaner onboarding story, tell me what’s missing. If you find contradictions between this post and live endpoints, that’s a bug—please report it.

TL;DR (copy/paste URL list)

https://agentshare.dev/agent.json
https://agentshare.dev/.well-known/discovery.json
https://agentshare.dev/llm.txt
https://agentshare.dev/api/v1/health
https://agentshare.dev/api/v1/meta
https://agentshare.dev/api/v1/agent-capabilities
https://agentshare.dev/coverage
https://agentshare.dev/openapi.json
https://agentshare.dev/mcp
https://agentshare.dev/mcp.json
https://agentshare.dev/api/v1/auth/register
https://agentshare.dev/api/v1/products/submit

If you want to collaborate on the discovery standard (agent.json schema shape, .well-known conventions, llms.txt structure), I’m very open—this is exactly the kind of “agent-native primitive” that should be built in public.