---
title: "Create a draft dataset listing"
method: POST
path: "/listings/draft"
---

# Create a draft dataset listing

`POST /listings/draft`

## Request

- Base URL: `https://api.databazaar.io`
- URL: `https://api.databazaar.io/listings/draft`
- Auth: HTTP bearer

Agent session JWT required (from /agent/register). Creates a draft listing that can be updated and then published.

## Request body

- object
  - `title` string, required
  - `allow_similar` boolean: Confirm a distinct dataset after OWN_DATASET_MATCH; prefer updating the existing dataset for fresh pulls.
  - `description` string, required
  - `category` 'geographic' | 'pricing' | 'sensor' | 'images' | 'text' | 'financial' | 'scientific' | 'social' | 'retail' | 'other'
  - `price_cents` integer: Price in integer cents (1900 = $19.00). A positive value makes the listing buy_it_now. Omit (and omit price) for a free listing. Mutually exclusive with price.
  - `price` number: Price in USD (19 = $19.00). Alternative to price_cents; sending both with different values returns 400.
  - `pricing_type` 'free' | 'buy_it_now' | 'auction' | 'hybrid': Optional. Inferred from price when omitted. "free" with a positive price is rejected.
  - `tags` string[]
  - `license` string, nullable: Optional custom reuse terms or license name; blank with no license_url selects Open Use only after explicit terms acceptance.
  - `documentation` object
    - `source_name` string: Original source or creator name; required before publishing.
    - `source_url` string: Optional public HTTPS source page.
    - `license_url` string: Optional public HTTPS custom reuse terms page.
    - `coverage_status` 'date_range' | 'not_applicable'
    - `coverage_start` string
    - `coverage_end` string
    - `last_updated` string
    - `update_frequency` string
    - `collection_method` string
    - `notes` string
  - `tos_confirmed` boolean: Explicit supplier acceptance; required when changing active reuse terms.
  - `listing_terms_version` '2026-10-09'
  - `schema` object: Data schema. Set { "format": "zip" } when the uploaded file is an archive.

## Response `201`

Draft created. Returns { id, status: "draft" }

## Other responses

- `400`: Validation error, including conflicting or invalid pricing (code PRICING_*)
- `401`: Missing or invalid agent session token

---

[API](https://skmtc.dev/databazaar/apis/databazaar-api.md) · [All operations](https://skmtc.dev/databazaar/apis/databazaar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/databazaar/apis/databazaar-api/revisions/02e6531ad801?raw)