// api reference

Listings

GETList listings, newest first
POSTCreate a listing, as a draft
POSTCreate up to 100 listings at once, all or none
GETRetrieve a listing
PATCHUpdate a listing
POSTPublish a listing
POSTReturn a published listing to draft
POSTTake a listing down, with a reason
GETA listing's media, pending uploads included
POSTStart a media upload
POSTComplete a media upload
DELETEDelete media and its file

GET /v1/listings

List listings, newest first

With a publishable key, only published listings are listed.

secret key, or a publishable key from a browser

GET /v1/listingsrequest

curl https://api.marketsdk.com/v1/listings \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, listing list

{
  "object": "list",
  "data": [
    {
      "object": "listing",
      "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
      "seller": "string",
      "category": null,
      "title": "string",
      "description": null,
      "price": {
        "amount": 4900,
        "currency": "USD"
      },
      "quantity": 0,
      "quantity_available": 0,
      "status": "draft",
      "attributes": {},
      "media": [
        {
          "object": null,
          "id": null,
          "listing": null,
          "status": null,
          "content_type": null,
          "size_bytes": null,
          "position": null,
          "url": null,
          "url_expires_at": null,
          "created_at": null
        }
      ],
      "metadata": {},
      "published_at": null,
      "expires_at": null,
      "removed_reason": null,
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
limit	integer, in query	min 1, max 100, default 20
starting_after	string, in query	The `next_cursor` of the previous page.
seller	string, in query
category	string, in query
status	one of: draft, published, sold, expired, removed, in query

returns 200, listing list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of listing
data[].objectrequired	one of: listing
data[].idrequired	string
data[].sellerrequired	string
data[].categoryrequired	string or null
data[].titlerequired	string
data[].descriptionrequired	string or null
data[].pricerequired	money
data[].price.amountrequired	integer	Integer minor units.
data[].price.currencyrequired	string
data[].quantityrequired	integer
data[].quantity_availablerequired	integer	Not reserved by an open order.
data[].statusrequired	one of: draft, published, sold, expired, removed
data[].attributesrequired	object of strings
data[].mediarequired	array of media
data[].media[].objectrequired	one of: media
data[].media[].idrequired	string
data[].media[].listingrequired	string
data[].media[].statusrequired	one of: pending, ready
data[].media[].content_typerequired	string
data[].media[].size_bytesrequired	integer
data[].media[].positionrequired	integer
data[].media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
data[].media[].url_expires_atrequired	timestamp or null
data[].media[].created_atrequired	timestamp
data[].metadatarequired	object of strings
data[].published_atrequired	timestamp or null
data[].expires_atrequired	timestamp or null
data[].removed_reasonrequired	string or null
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
429Rate limited. See Retry-After.

POST /v1/listings

Create a listing, as a draft

secret key only

POST /v1/listingsrequest

curl -X POST https://api.marketsdk.com/v1/listings \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"seller":"sel_034XtPDs7UJ0TXzTsdaHZa","title":"string","price":{"amount":4900,"currency":"USD"}}'

201 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

body, create listing

Request body
field	type	about
sellerrequired	string
category	string or null
titlerequired	string	up to 200 characters
description	string or null	up to 20000 characters
pricerequired	money
price.amountrequired	integer	Integer minor units, such as cents.
price.currencyrequired	string	ISO 4217 code. Must be the marketplace currency.
quantity	integer	min 1, max 100000, default 1
attributes	object of strings	Validated against the category's attribute schema.
metadata	object of strings
expires_at	timestamp or null	When a published listing expires.

returns 201, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/listings/bulk

Create up to 100 listings at once, all or none

secret key only

POST /v1/listings/bulkrequest

curl -X POST https://api.marketsdk.com/v1/listings/bulk \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"listings":[{"seller":"sel_034XtPDs7UJ0TXzTsdaHZa","title":"string","price":{"amount":4900,"currency":"USD"}}]}'

201 example response, bulk listings

{
  "object": "list",
  "data": [
    {
      "object": "listing",
      "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
      "seller": "string",
      "category": null,
      "title": "string",
      "description": null,
      "price": {
        "amount": 4900,
        "currency": "USD"
      },
      "quantity": 0,
      "quantity_available": 0,
      "status": "draft",
      "attributes": {},
      "media": [
        {
          "object": null,
          "id": null,
          "listing": null,
          "status": null,
          "content_type": null,
          "size_bytes": null,
          "position": null,
          "url": null,
          "url_expires_at": null,
          "created_at": null
        }
      ],
      "metadata": {},
      "published_at": null,
      "expires_at": null,
      "removed_reason": null,
      "created_at": "2026-10-01T12:00:00.000Z",
      "updated_at": "2026-10-01T12:00:00.000Z"
    }
  ]
}

body, bulk create listings

Request body
field	type	about
listingsrequired	array of create listing	All are created, or none.up to 100 items
listings[].sellerrequired	string
listings[].category	string or null
listings[].titlerequired	string	up to 200 characters
listings[].description	string or null	up to 20000 characters
listings[].pricerequired	money
listings[].price.amountrequired	integer	Integer minor units, such as cents.
listings[].price.currencyrequired	string	ISO 4217 code. Must be the marketplace currency.
listings[].quantity	integer	min 1, max 100000, default 1
listings[].attributes	object of strings	Validated against the category's attribute schema.
listings[].metadata	object of strings
listings[].expires_at	timestamp or null	When a published listing expires.

returns 201, bulk listings

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of listing
data[].objectrequired	one of: listing
data[].idrequired	string
data[].sellerrequired	string
data[].categoryrequired	string or null
data[].titlerequired	string
data[].descriptionrequired	string or null
data[].pricerequired	money
data[].price.amountrequired	integer	Integer minor units.
data[].price.currencyrequired	string
data[].quantityrequired	integer
data[].quantity_availablerequired	integer	Not reserved by an open order.
data[].statusrequired	one of: draft, published, sold, expired, removed
data[].attributesrequired	object of strings
data[].mediarequired	array of media
data[].media[].objectrequired	one of: media
data[].media[].idrequired	string
data[].media[].listingrequired	string
data[].media[].statusrequired	one of: pending, ready
data[].media[].content_typerequired	string
data[].media[].size_bytesrequired	integer
data[].media[].positionrequired	integer
data[].media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
data[].media[].url_expires_atrequired	timestamp or null
data[].media[].created_atrequired	timestamp
data[].metadatarequired	object of strings
data[].published_atrequired	timestamp or null
data[].expires_atrequired	timestamp or null
data[].removed_reasonrequired	string or null
data[].created_atrequired	timestamp
data[].updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/listings/{id}

Retrieve a listing

With a publishable key, only a published listing can be retrieved.

secret key, or a publishable key from a browser

GET /v1/listings/{id}request

curl https://api.marketsdk.com/v1/listings/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

PATCH /v1/listings/{id}

Update a listing

secret key only

PATCH /v1/listings/{id}request

curl -X PATCH https://api.marketsdk.com/v1/listings/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

200 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, update listing

Request body
field	type	about
category	string or null
title	string	up to 200 characters
description	string or null
price	money
price.amountrequired	integer	Integer minor units, such as cents.
price.currencyrequired	string	ISO 4217 code. Must be the marketplace currency.
quantity	integer	The total. Cannot go below what open orders have reserved.min 1
attributes	object of strings
metadata	object of strings
expires_at	timestamp or null

returns 200, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/listings/{id}/publish

Publish a listing

Needs an active seller, verified when seller verification is on, and a category that is not prohibited.

secret key only

POST /v1/listings/{id}/publishrequest

curl -X POST https://api.marketsdk.com/v1/listings/{id}/publish \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
403Not allowed with this key, or the marketplace is read-only.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/listings/{id}/unpublish

Return a published listing to draft

secret key only

POST /v1/listings/{id}/unpublishrequest

curl -X POST https://api.marketsdk.com/v1/listings/{id}/unpublish \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/listings/{id}/remove

Take a listing down, with a reason

secret key only

POST /v1/listings/{id}/removerequest

curl -X POST https://api.marketsdk.com/v1/listings/{id}/remove \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"reason":"string"}'

200 example response, listing

{
  "object": "listing",
  "id": "lst_034XtPDs7UJ0TXzTsdaHZa",
  "seller": "string",
  "category": null,
  "title": "string",
  "description": null,
  "price": {
    "amount": 4900,
    "currency": "USD"
  },
  "quantity": 0,
  "quantity_available": 0,
  "status": "draft",
  "attributes": {},
  "media": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "metadata": {},
  "published_at": null,
  "expires_at": null,
  "removed_reason": null,
  "created_at": "2026-10-01T12:00:00.000Z",
  "updated_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, remove listing

Request body
field	type	about
reasonrequired	string	Recorded with the removal.up to 500 characters

returns 200, listing

fields

Response fields
field	type	about
objectrequired	one of: listing
idrequired	string
sellerrequired	string
categoryrequired	string or null
titlerequired	string
descriptionrequired	string or null
pricerequired	money
price.amountrequired	integer	Integer minor units.
price.currencyrequired	string
quantityrequired	integer
quantity_availablerequired	integer	Not reserved by an open order.
statusrequired	one of: draft, published, sold, expired, removed
attributesrequired	object of strings
mediarequired	array of media
media[].objectrequired	one of: media
media[].idrequired	string
media[].listingrequired	string
media[].statusrequired	one of: pending, ready
media[].content_typerequired	string
media[].size_bytesrequired	integer
media[].positionrequired	integer
media[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media[].url_expires_atrequired	timestamp or null
media[].created_atrequired	timestamp
metadatarequired	object of strings
published_atrequired	timestamp or null
expires_atrequired	timestamp or null
removed_reasonrequired	string or null
created_atrequired	timestamp
updated_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

GET /v1/listings/{id}/media

A listing's media, pending uploads included

secret key only

GET /v1/listings/{id}/mediarequest

curl https://api.marketsdk.com/v1/listings/{id}/media \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, media list

{
  "object": "list",
  "data": [
    {
      "object": "media",
      "id": "med_034XtPDs7UJ0TXzTsdaHZa",
      "listing": "string",
      "status": "pending",
      "content_type": "image/jpeg",
      "size_bytes": 0,
      "position": 0,
      "url": null,
      "url_expires_at": null,
      "created_at": "2026-10-01T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, media list

fields

Response fields
field	type	about
objectrequired	one of: list
datarequired	array of media
data[].objectrequired	one of: media
data[].idrequired	string
data[].listingrequired	string
data[].statusrequired	one of: pending, ready
data[].content_typerequired	string
data[].size_bytesrequired	integer
data[].positionrequired	integer
data[].urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
data[].url_expires_atrequired	timestamp or null
data[].created_atrequired	timestamp
has_morerequired	boolean	Whether another page follows.
next_cursorrequired	string or null	Pass as `starting_after` (or `cursor` for search) to get the next page.

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.

POST /v1/listings/{id}/media

Start a media upload

Returns a signed URL, valid for 10 minutes. PUT the file there, then complete the upload. The file is stored under a path that begins with the marketplace id.

secret key only

POST /v1/listings/{id}/mediarequest

curl -X POST https://api.marketsdk.com/v1/listings/{id}/media \
  -H "Authorization: Bearer $MARKETSDK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"content_type":"image/jpeg","size_bytes":1}'

201 example response, media upload

{
  "media": {
    "object": "media",
    "id": "med_034XtPDs7UJ0TXzTsdaHZa",
    "listing": "string",
    "status": "pending",
    "content_type": "image/jpeg",
    "size_bytes": 0,
    "position": 0,
    "url": null,
    "url_expires_at": null,
    "created_at": "2026-10-01T12:00:00.000Z"
  },
  "upload_url": "string",
  "upload_expires_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

body, create media

Request body
field	type	about
content_typerequired	one of: image/jpeg, image/png, image/webp, image/gif, image/avif
size_bytesrequired	integer	The exact size of the file, in bytes. At most 10 MB.min 1, max 10485760
position	integer	default 0

returns 201, media upload

fields

Response fields
field	type	about
mediarequired	media
media.objectrequired	one of: media
media.idrequired	string
media.listingrequired	string
media.statusrequired	one of: pending, ready
media.content_typerequired	string
media.size_bytesrequired	integer
media.positionrequired	integer
media.urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
media.url_expires_atrequired	timestamp or null
media.created_atrequired	timestamp
upload_urlrequired	string	PUT the file here, with the same Content-Type, within 10 minutes. Then complete the upload.
upload_expires_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

POST /v1/media/{id}/complete

Complete a media upload

Checks the stored file against the declared type and size.

secret key only

POST /v1/media/{id}/completerequest

curl -X POST https://api.marketsdk.com/v1/media/{id}/complete \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, media

{
  "object": "media",
  "id": "med_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "status": "pending",
  "content_type": "image/jpeg",
  "size_bytes": 0,
  "position": 0,
  "url": null,
  "url_expires_at": null,
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, media

fields

Response fields
field	type	about
objectrequired	one of: media
idrequired	string
listingrequired	string
statusrequired	one of: pending, ready
content_typerequired	string
size_bytesrequired	integer
positionrequired	integer
urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
url_expires_atrequired	timestamp or null
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
409The object is not in a state that allows this.
429Rate limited. See Retry-After.

DELETE /v1/media/{id}

Delete media and its file

secret key only

DELETE /v1/media/{id}request

curl -X DELETE https://api.marketsdk.com/v1/media/{id} \
  -H "Authorization: Bearer $MARKETSDK_KEY"

200 example response, media

{
  "object": "media",
  "id": "med_034XtPDs7UJ0TXzTsdaHZa",
  "listing": "string",
  "status": "pending",
  "content_type": "image/jpeg",
  "size_bytes": 0,
  "position": 0,
  "url": null,
  "url_expires_at": null,
  "created_at": "2026-10-01T12:00:00.000Z"
}

parameters

Parameters
field	type	about
idrequired	string, in path

returns 200, media

fields

Response fields
field	type	about
objectrequired	one of: media
idrequired	string
listingrequired	string
statusrequired	one of: pending, ready
content_typerequired	string
size_bytesrequired	integer
positionrequired	integer
urlrequired	string or null	A signed link to the file, valid for an hour. Null until the upload completes.
url_expires_atrequired	timestamp or null
created_atrequired	timestamp

errors

400The request is not valid.
401No API key, or not a valid one.
404No object with that id in this marketplace.
429Rate limited. See Retry-After.