Create dispute

Stops a job for a ruling, as either party: before delivery (and before the deadline), or within the review window after it.

POST /v1/marketplace/jobs/{id}/dispute

Marketplace → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/marketplace/jobs/{id}/dispute`
Method	`POST`
Operation	`post_marketplace_jobs_by_id_dispute`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Stops a job for a ruling, as either party: before delivery (and before the deadline), or within the review window after it. Nothing moves while it is disputed. It ends when the buyer releases it, the seller refunds it, the platform's arbiter rules, or the arbiter's time lapses and it is refunded.

Request

3 fields, body application/json (required).

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the job, from the path.
`id`	body	string	—	ID is the job, from the path.
`reason`	body	string	—	Reason is the disputing party's words.

Response

Status	Body	Meaning
`200`	marketplace.Job	ok
`default`	problem-details	refused

200 body — 37 fields.

Field	In	Type	Always	Description
`amount`	body	any	—	Amount is what the job pays, exact USD.
`brief`	body	string	—	Brief is what the buyer asked for.
`buyerOrg`	body	string	—	BuyerOrg is the org that pays.
`category`	body	string	—	Category is what the payment is for — service, goods, transfer or royalty — as the buyer declared it and the seller accepted it.
`clearance`	body	string	—	Clearance is principal's latest decision that the buyer may pay the seller this amount — asked when the job was quoted, again when it was funded, and again when it was released: GET /v1/principal/clearance/{id}.
`createdAt`	body	integer (int64)	—	CreatedAt is when the job was quoted, unix seconds.
`currency`	body	string	—	Currency labels Amount: USD.
`deadline`	body	integer (int64)	—	Deadline is when delivery must land by, unix seconds.
`delivery`	body	marketplace.Delivery	—
`delivery.at`	body	integer (int64)	—	At is when, unix seconds.
`delivery.hash`	body	string	—	Hash commits to what was delivered: the seller's own 32-byte hash, or the SHA-256 of the note and URL.
`delivery.note`	body	string	—	Note says what was delivered.
`delivery.url`	body	string	—	URL is where it is, https.
`dispute`	body	marketplace.Dispute	—
`dispute.at`	body	integer (int64)	—	At is when, unix seconds.
`dispute.by`	body	string	—	By is the org that disputed.
`dispute.contested`	body	boolean	—	Contested is the clock's own dispute: the payment stopped clearing when the review window closed.
`dispute.reason`	body	string	—	Reason is the disputing party's words.
`ending`	body	string	—	Ending is the unpaid ending the job was given — declined, cancelled or refunded — while the rail returns the amount it set aside.
`escrow`	body	marketplace.Escrow	—
`escrow.contract`	body	string	—	Contract is the contract the money moves through: the token the x402 authorization transfers, or the escrow on chain.
`escrow.network`	body	string	—	Network is the CAIP-2 network the payment is signed for.
`escrow.payTo`	body	string	—	PayTo is the seller's payout address.
`escrow.rail`	body	string	—	Rail is x402 — the buyer's balance, settled at release — or chain, the Lux escrow contract.
`escrow.txHash`	body	string	—	TxHash is the transaction that paid the seller, once one did: the chain's hash, or the x402 settlement id on the ledger.
`history`	body	marketplace.Step[]	—	History is every step the job took, oldest first.
`history[].at`	body	integer (int64)	—	At is when, unix seconds.
`history[].by`	body	string	—	By is the org whose act it was, or "marketplace" for a clock that ran out.
`history[].status`	body	string	—	Status is the state the job entered.
`id`	body	string	—	ID is the job, "job_"-prefixed.
`listing`	body	string	—	Listing is the listing it was hired through; empty for a direct offer.
`performed`	body	string	—	Performed is where the work is performed, ISO 3166-1 alpha-2, when said.
`review`	body	integer (int64)	—	Review is how many seconds after delivery the buyer has to release or dispute before the job releases itself.
`sellerOrg`	body	string	—	SellerOrg is the org that does the work and is paid.
`status`	body	string	—	Status is where the job stands: open, accepted, delivered, released, disputed, declined, cancelled or refunded.
`title`	body	string	—	Title names the work: the listing's title, or the offer's own.
`updatedAt`	body	integer (int64)	—	UpdatedAt is when it last moved, unix seconds.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

import { Configuration, MarketplaceApi } from 'hanzoai';

const api = new MarketplaceApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postMarketplaceJobsByIdDispute({ id: 'id', id: "<id>", reason: "<reason>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import MarketplaceApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = MarketplaceApi(client).post_marketplace_jobs_by_id_dispute(id='id', id="<id>", reason="<reason>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.MarketplaceAPI.PostMarketplaceJobsByIdDispute(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, marketplace_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = marketplace_api::post_marketplace_jobs_by_id_dispute(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.MarketplaceApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new MarketplaceApi(client).postMarketplaceJobsByIdDispute();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/marketplace/jobs/<id>/dispute \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "id": "<id>",
       "reason": "<reason>"
     }'

MCP reaches marketplace through the marketplace tool, which names its 6 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_marketplace"
         }
       }
     }'

Marketplace API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page