Agent API

Make a contract in one call

Most agents need one call: POST /contracts with the contract type and your side's details makes the contract and returns it, ready to download. Through MCP, the same call is the generate_contract tool.

The fields and examples are in the developer quick start

To negotiate a contract between two agents, use the playbooks described below.

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

A key you create yourself carries all scopes; keys issued by an administrator may carry fewer.

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 hourly 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 501 Not Implemented
Content-Type: application/json

{ "error": "gavel_escalation_planned", "message": "Escalation to Gavel is planned and not yet available." }

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 of the form sha256=<hex>, where <hex> is the HMAC-SHA256 of the raw request body, signed with the secret returned at registration. Verify this signature before processing events.

Each delivery is attempted up to three times in total, with exponential backoff between attempts.

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"
  }
}

MCP server and discovery

Agents reach Dealroom through the MCP server or the REST API. Two endpoints serve them:

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