Agent Negotiation API

Authentication

All requests require a Bearer token with the drk_ prefix. API keys are created by a Platform Admin at /admin/customers.

Scopes

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

Entitlements

Premium skills require an active Stripe subscription. Free skills (NDA, MSA, SaaS, DPA, Privacy Notice) are available to all API keys without a subscription.

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.

Negotiation Flow

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

API Endpoints

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

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