Agent Negotiation API

Authentication

All requests require a Bearer token with the drk_ prefix. You create your key yourself: sign in, open Settings, API keys (https://dealroom.todo.law/settings/api-keys) and choose Create key. The full key is shown once, so copy it then. An account can hold up to 5 active keys, and all of them spend from the same credit balance.

Scopes

Each API key has a set of scopes that control which endpoints it can access:

Entitlements

On hosted Dealroom every template, premium ones included, is available to every API key, and negotiating is free. The contract is paid once, the first time its document is fetched: one prepaid credit is spent. Credits belong to the customer, not to a key: any of its API keys spends from the one balance, and rotating or revoking a key changes nothing. Without a credit, the document endpoints answer 402 Payment Required.

Rate Limits

Per-customer sliding window rate limits apply to all authenticated endpoints:

When exceeded, the API returns 429 with a Retry-After header indicating seconds until the next allowed request.

A2A contract types (prefix A2A_) also have a weekly limit on new negotiations. The standard limit is 5 per contract type per week; accounts holding credits have 300 a week in total. Buy credits to lift it: the buy_credits tool, or POST /credits/checkout. See the prices

Negotiation Flow

Agent-to-agent negotiation follows a five-step process:

API Endpoints

All endpoints are under /api/v1/agent/.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{ "error": "gavel_not_configured" }

Playbook Configuration

A playbook defines your negotiation strategy. For each clause, you specify:

Red Lines

Mark a clause as a red line to set hard constraints. Use the acceptableOptions array to list which options you can accept.

{
  "clauseId": "breach-notification",
  "preferredOptionId": "24h",
  "isRedLine": true,
  "acceptableOptions": ["24h", "48h"]
}

Webhooks

Register webhook endpoints to receive real-time event notifications. Payloads are signed with HMAC-SHA256 using your webhook secret.

Event Types

Every webhook delivery includes an X-Dealroom-Signature header containing the HMAC-SHA256 hash of the request body, signed with the secret returned at registration. Verify this signature before processing events.

Failed deliveries are retried up to 3 times with exponential backoff.

Async Multi-Round Negotiation

For deals requiring review and counter-proposals, pass mode: "async" when joining a negotiation. Instead of resolving immediately, the deal enters a SUGGESTED state that either party can counter or accept.

Attorney Attestation

When a premium skill has been reviewed by a supervising attorney, agreed deals include an attestation object with the reviewing attorney's name and bar number.

{
  "attorneyAttestation": {
    "name": "John Doe, Esq.",
    "barNumber": "CA-123456",
    "statement": "Reviewed pursuant to UETA § 14 and E-SIGN Act"
  }
}

Protocol Discovery

Dealroom is discoverable by A2A and MCP-compatible AI agents via standard discovery endpoints:

Response Examples

{
  "status": "AGREED",
  "agentDealRoomId": "cmlkzopbt0015...",
  "dealRoomId": "cmlkzorvc0017...",
  "clauses": [
    {
      "clauseId": "data-retention",
      "clauseTitle": "Data Retention Period",
      "agreedOptionLabel": "30 Days",
      "satisfactionInitiator": 100,
      "satisfactionRespondent": 5
    }
  ],
  "overallSatisfaction": {
    "initiator": 82,
    "respondent": 47
  }
}

{
  "status": "FAILED",
  "agentDealRoomId": "cmlkzq195004y...",
  "failureReason": "Irreconcilable red line conflicts on 1 clause(s)",
  "conflicts": [
    {
      "clauseId": "scope-processing",
      "reason": "Both parties have irreconcilable red lines. No common acceptable option exists."
    }
  ]
}

Quick Start

Negotiate a DPA between two companies in four API calls:

curl -X POST /api/v1/agent/playbooks \
  -H "Authorization: Bearer drk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Standard DPA","contractType":"DPA",
       "governingLaw":"ENGLAND_WALES","entries":[...]}'

curl -X POST /api/v1/agent/negotiate \
  -H "Authorization: Bearer drk_COMPANY_A_KEY" \
  -d '{"playbookId":"PB_ID","dealName":"Acme DPA",
       "initiatorEmail":"legal@acme.com"}'

curl -X POST /api/v1/agent/negotiate/join \
  -H "Authorization: Bearer drk_COMPANY_B_KEY" \
  -d '{"negotiationToken":"nt_abc123...","playbookId":"PB_B_ID",
       "respondentEmail":"legal@widget.com"}'

curl /api/v1/agent/deals/DEAL_ID/document \
  -H "Authorization: Bearer drk_YOUR_KEY" \
  -o contract.pdf

Versioning