> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datavendor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the API

> Keys, conventions, and errors shared by the buyer API, the vendor API, and the MCP server.

DataVendor has a REST API for each side of the marketplace and one MCP server for coding agents.
All of them authenticate with the same team API key. Buying, bidding, publishing, and moving money
stay in the web app.

<Columns cols={2}>
  <Card title="Vendor API" icon="store" href="/sell/api/rest-api">
    Your listings, inventory, opportunities, estimations, and earnings.
  </Card>

  <Card title="Buyer API" icon="cart-shopping" href="/buy/api/rest-api">
    The catalog, your purchases and bids, and the opportunities you posted.
  </Card>
</Columns>

Use the API that matches your organization's [role](/overview/organizations-and-roles#marketplace-roles).
An organization with both roles uses both with one key. Both APIs read the catalog and the
taxonomy, so those endpoints appear on each page.

| API | OpenAPI document | Interactive reference |
| - | - | - |
| Vendor | [`/vendor/openapi.json`](https://api.datavendor.ai/vendor/openapi.json) | [`/vendor/docs`](https://api.datavendor.ai/vendor/docs) |
| Buyer | [`/buyer/openapi.json`](https://api.datavendor.ai/buyer/openapi.json) | [`/buyer/docs`](https://api.datavendor.ai/buyer/docs) |

## Authentication

DataVendor organizations are HUD teams, so the key is a HUD team API key. Create one in
[Settings → API Keys](https://hud.ai/settings/api-keys) and send it as a bearer token on every
request. The `hud-api-key` and `X-API-Key` headers are accepted too.

```bash theme={"dark"}
curl https://api.datavendor.ai/v2/listings/browse \
  -H "Authorization: Bearer $HUD_API_KEY"
```

Missing or invalid credentials return `401`. A valid key whose team may not touch the resource
returns `403`. Catalog reads also require a marketplace role on the team, and vendor-only teams
are subject to the [browse gate](/overview/glossary#browse-gate): behind it,
`GET /v2/listings/browse` serves only the first page of the unfiltered catalog with
`locked: true`, and refuses search, filters, sorting, and cursors with `403`.
`GET /v2/listings/browse/access` reports where your team stands.

## Conventions

| Convention | Detail |
| - | - |
| **Base URL** | `https://api.datavendor.ai`, every route under `/v2`. |
| **Format** | JSON in, JSON out. |
| **IDs** | Resources are addressed by UUID in the path. |
| **Pagination** | Catalog browse is keyset-paginated: pass `cursor` from the previous page's `next_cursor`. Team-scoped lists take `limit` and `offset`. |
| **Time** | Timestamps are UTC, ISO 8601. |
| **Mutations** | Creates return `201`, deletes return `204`, everything else returns `200`. |
| **Rate limits** | Requests can be capped per client IP and per team. Per-team budgets cover catalog, history, and sales reads, purchases, quality checks, and uploads. A request over a limit receives `429`. |

Every example on the API pages is generated from that API's OpenAPI document, so field names
match what the server sends and receives. The values are placeholders.

## Errors

Failures share one envelope, with a machine-readable code and a human-readable message. The status
tells you whether to fix the request, the credentials, or the state.

| Status | Meaning |
| - | - |
| `400` | The request is malformed. |
| `401` | Credentials are missing or invalid. |
| `403` | Authenticated, but not allowed: no marketplace role, a Mutual NDA not yet accepted, or the browse gate. |
| `404` | The resource does not exist, or is not visible to you. |
| `409` | The resource already exists, or conflicts with its current state. |
| `422` | The body or parameters failed validation. |
| `429` | Too many requests. Back off, then retry. |

## MCP

The **DataVendor MCP** is a read-only [Model Context Protocol](https://modelcontextprotocol.io/)
server for coding agents: streamable HTTP JSON-RPC at `https://api.datavendor.ai/v2/mcp/`, with the
same team API key. One server serves both sides; the tools a key can use follow its team's role.
The tools are listed per side under [Vendor MCP tools](/sell/api/mcp) and
[Buyer MCP tools](/buy/api/mcp).

<CodeGroup>
  ```json Cursor (~/.cursor/mcp.json) theme={"dark"}
  {
    "mcpServers": {
      "hud-datavendor": {
        "url": "https://api.datavendor.ai/v2/mcp/",
        "headers": {
          "Authorization": "Bearer YOUR_HUD_API_KEY"
        }
      }
    }
  }
  ```

  ```bash Claude Code theme={"dark"}
  claude mcp add --transport http hud-datavendor \
    https://api.datavendor.ai/v2/mcp/ \
    --header "Authorization: Bearer $HUD_API_KEY"
  ```

  ```json Generic MCP client theme={"dark"}
  {
    "hud-datavendor": {
      "url": "https://api.datavendor.ai/v2/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_HUD_API_KEY"
      }
    }
  }
  ```
</CodeGroup>

Every tool resolves your team from the key, as the REST routes do, and enforces the same
marketplace role, NDA, and browse gate. Missing or invalid credentials fail the call with an
`Unauthorized` error. The tools
wrap the same service methods as the REST routes, so a listing id from `browse_listings` is the id
`GET /v2/listings/browse/{listing_id}` takes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.