API reference

venda exposes the same data through two surfaces: a conventional REST API and a Model Context Protocol (MCP) server. AI agents typically use MCP because it self-describes; everyone else uses REST. Same auth, same data.

Authentication

REST

Base URL: https://api.venda.sh (production) or http://localhost:8787 (dev). All bodies are JSON. Money is always an integer in the smallest currency unit (cents/øre).

MCP

Configure your MCP client (Claude Desktop, Cursor, mcp-remote) to point at https://api.venda.sh/mcp with header X-API-Key: venda_…. Then call:

POST /mcp                 (JSON-RPC 2.0)
  initialize             -> protocol + serverInfo + instructions
  tools/list             -> [ { name, description, inputSchema }, ... ]
  tools/call             -> { content, isError? }
                            params: { name, arguments }

Tools

search_listings

Full-text + filter search across all 5 verticals(public)

get_listing

One listing with vertical-specific details(public)

create_listing

Post a listing in any verticallistings:write

update_listing

Edit fields on a listing you ownlistings:write

delete_listing

Permanently delete a listing you ownlistings:write

list_my_conversations

Inboxmessages:read

get_messages

Read messages in a threadmessages:read

send_message

Post into a thread; start one with listingIdmessages:write

mark_thread_read

Mark a thread read up to nowmessages:write

get_my_profile

Your own profileprofile:read

get_profile

Lookup a profile by handle(public)

update_my_profile

Update displayName / avatar / bio / countryprofile:write

Scopes

Each API key carries a set of scopes. Mint with the minimum the agent needs — keys can always be revoked from the dashboard.

listings:read

Reserved — search/get listings is currently public

listings:write

create / update / delete listings

messages:read

List conversations, read messages

messages:write

Send messages, start threads, mark read

profile:read

Read the key owner's full profile

profile:write

Update the key owner's profile

Vertical detail shapes

Every listing has a vertical-specific details object. Required fields per vertical, plus the enums you'll trip over otherwise:

Examples

Search via REST

curl -s "https://api.venda.sh/v1/listings?q=tesla&vertical=cars&minPrice=20000000"

Search via MCP

curl -s -X POST https://api.venda.sh/mcp \
  -H "X-API-Key: venda_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "search_listings",
      "arguments": { "q": "tesla", "vertical": "cars" }
    }
  }'

Create a goods listing

curl -s -X POST https://api.venda.sh/v1/listings \
  -H "X-API-Key: venda_..." \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "goods",
    "status": "active",
    "title": "Vintage leather jacket",
    "description": "Worn lightly, size 38, smoke-free home.",
    "price": { "amount": 150000, "currency": "NOK" },
    "location": { "country": "NO", "city": "Oslo" },
    "images": [{ "url": "https://example.com/jacket.jpg" }],
    "details": {
      "category": "clothing",
      "condition": "good",
      "shippingAvailable": true
    }
  }'

Errors

• 400 — body validation failed; the response includes the field-level errors and (for enum mismatches) the full set of valid values
• 401 — missing or invalid API key / bearer token
• 403 — authenticated but missing the required scope, or trying to act on something you don't own
• 404 — not found (or not yours, for owner-scoped resources)
• 429 — per-API-key rate limit exceeded; Retry-After header tells you when to retry

Rate limits

Each API key has a sliding-window per-minute limit (default 120 req/min, configurable when you mint the key). Every authenticated response carries:

• X-RateLimit-Limit — your configured ceiling
• X-RateLimit-Remaining — requests left in the current window
• X-RateLimit-Reset — unix seconds when the window rolls over