← Back to siteDeveloper

API Reference

The ScrapTradeMarket REST API v1 lets your systems read and manage listings and orders programmatically. All endpoints return JSON.

Authentication

All requests (except the OpenAPI spec) require an API key. Generate one from your company dashboard. Pass the key in the X-Api-Key header:

curl https://scraptrademarket.com/api/v1/profile \
  -H "X-Api-Key: stm_YOUR_KEY_HERE"

Alternatively, send the key as a Bearer token: Authorization: Bearer stm_YOUR_KEY_HERE

Base URL

https://scraptrademarket.com/api/v1

Endpoints

Method	Path	Permission	Description
GET	/profile	none	Get your company profile
GET	/listings	listings:read	List your company's listings (paginated)
POST	/listings	listings:write	Create a new listing
GET	/listings/:id	listings:read	Get a single listing
PATCH	/listings/:id	listings:write	Update a listing
DELETE	/listings/:id	listings:write	Archive a listing
GET	/orders	orders:read	List orders (buyer, seller, or all)
GET	/orders/:id	orders:read	Get order detail
GET	/orders/:id/tracking	orders:read	Get shipment tracking events

Permissions

Each API key is granted a subset of permissions at creation time. The available permissions are:

listings:read

Read your company's listings (GET /listings, GET /listings/:id).

listings:write

Create, update, or archive your company's listings.

orders:read

Read orders your company is involved in as buyer or seller.

Pagination

List endpoints accept page (default 1) and limit (default 20, max 100) query parameters. Responses include total, page, and limit.

Errors

All error responses use standard HTTP status codes and a JSON body:

{ "error": "Human-readable message", "code": "MACHINE_CODE" }

401 — Missing or invalid API key, or key has expired.

403 — Key does not have the required permission.

404 — Resource not found or not owned by your company.

422 — Validation error; the response includes a fields object.

500 — Internal server error.

Rate limits

No hard rate limit is enforced in v1. Fair-use guidelines apply — avoid polling more frequently than once per minute for order/tracking updates. Rate limiting will be introduced in a future version.

Code examples

List active listings

curl "https://scraptrademarket.com/api/v1/listings?status=ACTIVE&page=1&limit=20" \
  -H "X-Api-Key: stm_YOUR_KEY_HERE"

Create a listing

curl -X POST "https://scraptrademarket.com/api/v1/listings" \
  -H "X-Api-Key: stm_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "SALE",
    "metal": "Fe",
    "grade": "HMS 1&2",
    "volume": 50,
    "unit": "t",
    "price": 280,
    "currency": "EUR",
    "country": "ES",
    "description": "Clean scrap, ready for collection"
  }'

Get order tracking

curl "https://scraptrademarket.com/api/v1/orders/ORDER_ID/tracking" \
  -H "X-Api-Key: stm_YOUR_KEY_HERE"

OpenAPI Spec

A machine-readable OpenAPI 3.1 specification is available at:

/api/v1/openapi.json