canonical: https://jentic.com/apis/ebay.com/main

# Ebay Browse API

Jentic publishes the only available OpenAPI specification for the eBay Browse API, keeping it validated and agent-ready. The Browse API is eBay's primary buyer-side discovery surface - search items by keyword, GTIN, image, category, or aspect, retrieve full item detail by item_id, expand item-group variations, and check whether a part fits a given vehicle through the compatibility resource. It also bridges legacy eBay item-IDs from the Finding API to the new RESTful item_id format. Most operations accept an Application access token, so agents can run product discovery without per-user OAuth.

## For AI agents

Search eBay listings by keyword, image, GTIN, or category; retrieve item detail; check vehicle-part compatibility. Application-token discovery, no user consent required.

## Scope

Does not handle creating listings, processing payments, or fulfilling orders - use for buyer-side search and item discovery only.

## Capabilities

- Search eBay listings by keyword, GTIN, EPID, charity, or category and refine with aspect filters
- Find listings by uploading an image to /item_summary/search_by_image for visual product matching
- Retrieve full item detail (title, price, shipping, seller, aspects) by item_id
- Expand a parent listing into its variation set via /item/get_items_by_item_group
- Check whether a vehicle is compatible with a specific automotive part via /item/{item_id}/check_compatibility
- Translate a legacy Finding API item ID to the RESTful item_id with /item/get_item_by_legacy_id
- Batch-fetch multiple item IDs via /item to reduce per-listing roundtrips

## Use cases

### Conversational shopping agent

An AI shopping agent takes a user query like 'second-hand mountain bike under £400' and calls /item_summary/search with q, filter (price range), and sort=price. It returns the top results, then on user selection calls /item/{item_id} to render a full product card with shipping cost, seller feedback score, and aspect grid. The whole flow runs on an Application access token - no per-user OAuth required.

Example prompt: Call /item_summary/search with q='mountain bike', filter='price:[..400],conditionIds:{3000}', sort=price, return top 5 with /item/{item_id} detail

### Visual search for resellers

Reseller tools let users upload a photo of an item and call /item_summary/search_by_image to find comparable active eBay listings. The endpoint accepts a base64-encoded image and returns ranked matches, which the tool uses to suggest a competitive listing price for the user's own item.

Example prompt: POST a base64-encoded photo to /item_summary/search_by_image and return the median price of the top 10 matches

### Vehicle parts compatibility checker

Auto-parts marketplaces use /item/{item_id}/check_compatibility to confirm a part fits a buyer's vehicle before adding it to cart. The endpoint accepts a make/model/year/trim payload and returns a definitive compatibility verdict, so the storefront prevents 'wrong fit' returns that drive negative seller feedback.

Example prompt: Call /item/{item_id}/check_compatibility with make=Ford, model='Focus', year=2018, trim='Titanium' and return the verdict

### Legacy ID migration for Finding API consumers

Integrations originally built on eBay's legacy Finding API hold listing IDs in the legacy format. /item/get_item_by_legacy_id accepts the old ID plus an optional variation SKU and returns the full Browse item record with the new RESTful item_id, letting teams migrate their data layer without re-scraping every listing.

Example prompt: For each legacy_item_id in the migration table, call /item/get_item_by_legacy_id and store the new item_id back on the row

### AI agent integration via Jentic

An AI agent that helps a user shop on eBay searches Jentic for 'search eBay listings by keyword'. Jentic returns /item_summary/search with its parameter schema. The agent loads the schema, executes the call with an Application access token issued through Jentic's vault, and renders results to the user - no eBay-specific OAuth code in the agent itself.

Example prompt: Use Jentic to search 'search eBay listings by keyword', load /item_summary/search, and execute it with q='vintage camera' and limit=10

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /item_summary/search | Search listings by keyword, GTIN, category, or aspect with sort and filter |
| POST | /item_summary/search_by_image | Search listings by uploaded image |
| GET | /item/{item_id} | Retrieve full detail for a single listing |
| GET | /item/get_item_by_legacy_id | Translate a legacy Finding API item ID to the RESTful item_id |
| GET | /item/get_items_by_item_group | Return all variations under a parent item group |
| POST | /item/{item_id}/check_compatibility | Check whether a vehicle is compatible with an automotive part |
| GET | /item | Batch-fetch multiple items by item_id list |

## Key resources

- **item_summary** — Search-style endpoints - keyword, image, and refinement filters
- **item** — Detail lookup, item-group expansion, legacy-ID translation, and parts compatibility

## Why Jentic

- **Setup:** Wiring the eBay Browse API by hand means implementing eBay's OAuth 2.0 client-credentials flow for an application token, handling marketplace headers, and pointing requests at the api.ebay.com buy/browse host. Through Jentic you install once, import the Browse API from the API Directory, store the eBay OAuth credentials once, and your agent calls it.
- **Permission scoping:** The Browse API puts the item id in the URL path (/item/{item_id}), so a rule can pin your agent to reading a specific item or item group. You choose the operations it may call, so a search-and-read agent gets item_summary/search and item lookups while nothing beyond buyer-side discovery is included unless you add it.
- **Credential handling:** Your eBay OAuth application credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'search eBay listings by keyword' or 'look up an eBay item', and Jentic returns the matching /item_summary/search or /item/{item_id} operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **eBay Item Feed Service** — Item Feed Service downloads bulk catalogue files; Browse is the live per-item lookup surface.
- **eBay Buy Marketing API** — Buy Marketing returns ranked best-sellers; Browse returns full per-item detail.
- **eBay Developer Analytics API** — Developer Analytics tracks Browse API quota burn.

## FAQ

### Why is there no official OpenAPI spec for the Browse API?

eBay does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Browse API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Browse API use?

The Browse API uses OAuth 2.0. The /item_summary, /item_summary/search_by_image, and /item endpoints accept an Application access token issued via the Client_Credentials grant - no user consent required. Through Jentic, the OAuth client secret sits in your Jentic One instance and the agent receives a scoped access token only.

### Can I search eBay listings by image with the Browse API?

Yes. POST a base64-encoded image to /item_summary/search_by_image and the API returns ranked active listings that match the image, sorted by relevance. It is the same matching engine eBay uses for its own visual search feature.

### What are the rate limits for the Browse API?

Browse falls under eBay's Buy APIs application-level quota. The default limit is published per partner and visible live through the Developer Analytics API - call /rate_limit and inspect the buy.browse entry to see your current limit, remaining, and reset window.

### How do I retrieve a single item's full detail through Jentic?

Search Jentic for 'get eBay item detail by ID', load the /item/{item_id} operation schema, and execute it with the item_id. Install with pip install jentic. Get started with Jentic One, the self-hosted execution layer.

### Can the Browse API check whether a part fits a vehicle?

Yes. POST to /item/{item_id}/check_compatibility with the vehicle's make, model, year, and trim, and the API returns a compatibility verdict. The endpoint only applies to listings in eBay Motors categories where the seller has supplied compatibility data.

### How do I migrate from the legacy Finding API to Browse?

Use /item/get_item_by_legacy_id - pass the legacy item ID (and optional variation SKU) and the API returns the full Browse item record with the new RESTful item_id. Run it once per row in your data layer to backfill new IDs without re-scraping listings.

### Can I limit what my agent is allowed to do with the eBay Browse API?

Yes. Because you run Jentic One yourself, your own rules decide which Browse operations the agent can call, so you can grant it item_summary/search and item lookups while leaving anything beyond buyer-side discovery out. Since the Browse API carries the item id in the URL path, such as /item/{item_id}, a rule can pin the agent to reading a specific item or item group. Your eBay OAuth credentials stay in your own instance and are injected only when a permitted operation runs, never entering the agent's prompt or logs.