Listings
A listing represents something for sale on ZAM. It has a title, an optional price, and a run contract that tells ZAM how to execute it. Every listing belongs to exactly one user (the seller) and moves through a state machine:| State | Meaning |
|---|---|
draft | Visible only to the seller. Cannot be activated. |
published | Live on the marketplace. Buyers can activate it. |
paused | Temporarily hidden. Can be republished. |
archived | Permanently retired. Terminal state. |
published listings appear in marketplace search results or accept activations.
Run contracts
A run contract defines how ZAM executes a listing. It contains:| Field | Required | Description |
|---|---|---|
method | Yes | HTTP method (GET, POST, PUT, PATCH, DELETE) |
endpointPath | Yes | The URL ZAM calls when a buyer activates the listing |
inputSchema | No | JSON Schema describing the expected request body |
outputSchema | No | JSON Schema describing the response |
requestExampleJson | No | Example request for documentation |
responseExampleJson | No | Example response for documentation |
inputSchema, ZAM validates the buyer’s request body against it before executing. Malformed input never reaches the seller’s endpoint.
Orders
An order records one activation of a listing. When a buyer activates a listing, ZAM:- Validates the request body against the listing’s
inputSchema(if present). - Creates an order in
pendingstate. - Calls the seller’s endpoint with the request body.
- Updates the order to
completed(with the response) orfailed(with the error).
POST /v1/orders response contains the final result. Otherwise, it returns the order in pending state and the buyer polls for the result.
Authentication
ZAM supports two authentication methods:- API keys — for programmatic access. Pass the key in the
x-zam-api-keyheader. Keys use scoped permissions (listing:create,order:read, etc.). - Session cookies — for browser-based access through the dashboard. Managed by the sign-in flow.
zam_ and are shown only once at creation time. Store them securely.
Scopes
Each API key carries a set of scopes that control what it can do:| Scope | Permission |
|---|---|
listing:create | Create listings |
listing:read | Read own listings |
listing:update | Update own listings |
listing:delete | Delete own listings |
order:create | Activate listings (create orders) |
order:read | Read own orders |
api_key:create | Create new API keys |
api_key:read | List own API keys |
api_key:update | Update own API keys |
api_key:delete | Delete own API keys |
order:create and order:read.