# Stak Multivendor Core API (`stakmv/v1`)

Base URL:

```txt
https://your-site.com/wp-json/stakmv/v1
```

Auth model:

- Cookie auth (same as logged-in WP session) works for web.
- For mobile apps, authenticate with WordPress Application Passwords or another site-approved authentication provider, then call these endpoints.
- This plugin does not implement its own username/password login endpoint.

## Core Endpoints

### Auth

- `POST /auth/refresh`
- `POST /auth/logout`
- `GET /auth/me`

### Metadata

- `GET /meta/config`
- `GET /meta/categories`
- `GET /meta/conditions`
- `GET /meta/shipping-options`
- `GET /meta/countries`

### Media

- `POST /media/upload` (multipart, field name: `file`)
- `DELETE /media/{id}`
- `POST /media/reorder` (scaffold, `501`)

### Vendor Listings

- `GET /vendor/listings`
- `POST /vendor/listings` (scaffold, `501`)
- `GET /vendor/listings/{id}`
- `PUT/PATCH /vendor/listings/{id}` (scaffold, `501`)
- `DELETE /vendor/listings/{id}` (scaffold, `501`)
- `POST /vendor/listings/{id}/relist` (scaffold, `501`)
- `POST /vendor/listings/{id}/duplicate` (scaffold, `501`)
- `POST /vendor/listings/{id}/publish` (scaffold, `501`)
- `POST /vendor/listings/{id}/unpublish` (scaffold, `501`)

### Public Listings

- `GET /listings`
- `GET /listings/{id}`
- `GET /listings/{id}/shipping-preview`
- `GET /listings/{id}/similar`

### Auction Actions

- `POST /auctions/{id}/bid`
- `POST /auctions/{id}/buy-now` (scaffold, `501`)
- `POST /auctions/{id}/watch`
- `DELETE /auctions/{id}/watch`
- `GET /auctions/{id}/history`

Bid request:

```json
{
  "amount": 120.5
}
```

### Vendor Public Profile

- `GET /vendors/{id}/profile`
- `GET /vendors/{id}/shop`
- `GET /vendors/{id}/sold`

### Vendor Profile Edit

- `PUT/PATCH /vendor/profile` (scaffold, `501`)
- `PUT/PATCH /vendor/profile/about` (scaffold, `501`)
- `POST /vendor/profile/banner` (scaffold, `501`)

### Notifications

- `GET /notifications`
- `POST /notifications/{id}/read`
- `POST /notifications/read-all`

### Shipping Helpers

- `GET /shipping/providers`
- `POST /shipping/rates/quote` (scaffold, `501`)
- `GET /shipping/listing/{id}/details`

## Standard Response Pattern

Success:

```json
{
  "ok": true
}
```

Not implemented:

```json
{
  "ok": false,
  "code": "not_implemented_yet",
  "message": "Endpoint scaffolded and reserved for app integration. Implementation pending."
}
```
