---
title: "Create a deal and get one invite token per party"
method: POST
path: "/v1/deals"
tags: ["deals"]
---

# Create a deal and get one invite token per party

`POST /v1/deals`

## Request

- Base URL: `https://api.redeal.dev`
- URL: `https://api.redeal.dev/v1/deals`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `algorithm` 'split.v1' | 'auction.v1' | 'random.v1' | 'shapley.v1', required
  - `mode` 'sealed' | 'open'
  - `retention` 'standard' | 'purge'
  - `parties` union[], required: Party labels (strings) or objects. Labels go on the public certificate permanently: use nicknames, never real names or emails
    - union
      - string
      - object
        - `label` string, required
        - `weight` integer: optional; default 1 (explicit 1 is normalized to omitted)
        - `statement_hash` string: sha256:<64 lowercase hex>
  - `terms_hash` string: optional, sha256:<64 hex> — hash of the deal's terms; echoed into the certificate
  - `external_ref` string: optional — your own identifier; echoed into the certificate
  - `supersedes` string: optional cert id (c_<16 hex>) this deal's certificate replaces
  - `visibility` 'public' | 'parties': who may fetch the certificate: public (default — anyone at GET /v1/certificates/{cert_id}) or parties (initiator key / invite tokens only; recorded in the certificate)
  - `commit_deadline` integer, required: unix seconds UTC
  - `reveal_deadline` integer, required: unix seconds UTC
  - `algorithm_params` object: per-algorithm params; see GET /v1/algorithms. Bounds (part of the versioned contract): split.v1 items ≤ 1024 (strings or {"id","indivisible"} objects; indivisible rejected) and each party's valuations sum to exactly 1000 points; shapley.v1 coalition values 0..2^62-1, ≤ 8 parties, labels without commas; random.v1 ≤ 10,000 parties, nonce ≤ 1024 bytes hex; auction.v1 ≤ 1024 bidders, bids 0..2^62-1, params item+unit+reserve mandatory, price_cap optional (≥ reserve)

## Response `201`

Deal created. Invite tokens are shown ONCE and stored hashed.

- object
  - `deal_id` string, required
  - `state` string, required
  - `invite_tokens` object[], required
    - `party` integer
    - `label` string
    - `token` string
  - `warning` string

## Other responses

- `400`: Error. The message is instructive: it names the code and the fix.
- `401`: Error. The message is instructive: it names the code and the fix.
- `409`: Error. The message is instructive: it names the code and the fix.

---

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