Skip to main content

Developers

Developer changelog

Every change to the REST API and the MCP server that an integration could notice. Breaking changes are marked.

Atom feed

  1. Connect Attorly to Claude, ChatGPT and other apps with OAuth

    MCP serverREST APISettings

    The MCP server speaks the 2026-07-28 protocol and is an OAuth 2.1 resource, so apps connect with a sign-in and a consent screen instead of a pasted key. The REST API accepts OAuth tokens too.

    • OAuth 2.1 authorization server: discovery (RFC 8414, RFC 9728), dynamic client registration (RFC 7591) and Client ID Metadata Documents, authorization code with PKCE (S256), refresh-token rotation with reuse detection, and revocation (RFC 7009).
    • A consent screen shows what the app may do, lets you narrow it and pick the organization, and warns about apps Attorly has not verified. Settings › Developers › Connected apps lists the apps you allowed and disconnects them.
    • Tokens are bound to the resource they were issued for (RFC 8707): ask for resource=https://attorly.ai/api/mcp for MCP or https://attorly.ai/api/v1 for REST.
    • MCP tool results follow the 2026-07-28 specification: Markdown content, structuredContent checked against each tool’s outputSchema, and isError for business failures. Initialize-era clients keep the shape they had.
    • Long-running MCP tools run as durable operations: with the Tasks extension the call returns a task; otherwise it streams progress and answers with an operation that operations_get resolves.
    • New tools and endpoints: documents_search (GET /api/v1/documents/search), analyses_get and analyses_list (GET /api/v1/analyses/{analysisId}, GET /api/v1/documents/{documentId}/analyses), due_diligence_list_projects and due_diligence_get_project, workflows_list_executions, and organization_get_context (GET /api/v1/organization).
    • documents_upload takes an https url; the download is checked against private networks, pinned to the address it resolved to and capped at 10 MB.
    • Organization keys (atly_…) work on the MCP server as well, including test-mode keys, which run every tool on test data.

    MCP setup guidesOAuth for the REST API

  2. Webhooks, test mode, versioning and new API keys

    REST APIMCP serverSettings

    Get told when work finishes instead of polling, build against test data that costs nothing, and pin the API version your integration was written for.

    • Webhooks: /api/v1/webhook-endpoints with signing-secret rolls, test events and delivery history, and /api/v1/events with redelivery. Payloads are signed per Standard Webhooks and retried for 72 hours.
    • Events: analysis.completed, analysis.failed, redlines.generated, due_diligence.report.completed, operation.succeeded and operation.failed, for calls made over REST and MCP alike.
    • Organization keys are now atly_live_… / atly_test_… (secret) or atly_rk_live_… / atly_rk_test_… (restricted), with a checksum, an optional IP allowlist and rolling with an overlap. lb_ and lbmcp_ keys keep working.
    • Test mode: test keys reach every endpoint with deterministic fixture results on separate test data — no AI, no credits. Magic inputs such as __fail_credits__ produce each failure. DELETE /api/v1/test-data clears it.
    • Versioning: send Attorly-Version, or use the version a key was created with. Every response says which version answered.
    • Rate limits are counted per key per hour, per person and per organization per minute, per endpoint group and per tool, shared by REST and MCP, and reported in RateLimit-Policy, RateLimit and X-RateLimit-* headers.
    • Every response carries Request-Id, and error bodies add type, param, requiredScopes and docUrl.
    • GET /api/v1/request-logs, /api/v1/usage and /api/v1/audit-events report the organization’s API activity over both surfaces; Settings › Developers shows the same log.

    WebhooksTest modeVersioning

  3. API version 2026-11-01

    Breaking changeREST API

    Lists return one envelope, and long-running AI operations answer 202 with an operation. Keys created from today use this version; existing keys stay on 2026-10-01 until you send Attorly-Version.

    • Lists return { object: "list", data, hasMore, nextCursor } instead of the items under a resource-named field with count.
    • Full analyses, redlines, negotiation playbooks, workflows, due diligence reports and AI drafts answer 202 Accepted with an operation to poll, unless Prefer: wait=<seconds> (up to 60) lets them finish in time. operation.succeeded tells you when they did.
    • The OpenAPI document for 2026-11-01 describes each response field exactly as the API sends it: a field that can be absent is optional.

    Versioning

  4. Settings › Developers and per-client setup guides

    SettingsMCP serverREST API

    Keys, request logs and usage now live on one page, and creating a key shows the exact configuration for the client you connect.

    • New Settings › Developers page with API keys, organization keys (Enterprise), request logs and usage. The old Security › API keys and Security › MCP connections pages redirect there.
    • Creating a key is one step: pick the client (Claude Code, Claude Desktop, Cursor, VS Code, the OpenAI API or plain REST) and an access preset. The key is shown inside a ready-to-paste configuration for that client, with one-click install links for Cursor and VS Code.
    • The page confirms when the first request with a new key arrives.
    • Request logs: every call made with your keys over MCP and REST in the last 30 days, filterable by outcome, key and tool. Owners and admins see the whole organization; members see their own keys.
    • Setup guides for each MCP client at /docs/mcp, and a REST reference generated from the OpenAPI document with curl, TypeScript and Python examples for every operation.
    • Every error code has its own entry at /docs/api/errors.

    MCP setup guidesREST API referenceError codes

  5. Documents resource, idempotency and asynchronous operations

    REST APIMCP server

    Upload, list, read and delete documents over REST, retry any write safely, and run long calls in the background.

    • GET and POST /api/v1/documents and GET and DELETE /api/v1/documents/{documentId}. Upload as multipart/form-data or as JSON with base64 content or plain text; uploads are analysed in the background unless analyze is false.
    • New MCP tools documents_list, documents_get, documents_upload and documents_delete, with the scopes DOCUMENTS_WRITE and DOCUMENTS_DELETE (documents:write and documents:delete for organization keys).
    • Idempotency-Key on POST and DELETE: a retry with the same key and request returns the first response with Idempotent-Replayed: true and is not run or billed again. Reusing a key for a different request returns 422 idempotency_key_reused; a retry while the first is still running returns 409 with a Location to poll. Keys are kept for 24 hours.
    • Prefer: respond-async returns 202 Accepted with a Location at once; Prefer: wait=N waits up to N seconds first. Poll GET /api/v1/operations/{operationId} until status is succeeded or failed.
    • Cursor pagination with hasMore and nextCursor on documents, templates and workflow templates.
    • JSON on every response: 405 with an Allow header, 404 for unknown paths, 413 and 415, and requestId in every error body.

    IdempotencyLong-running requests

  6. Public REST API

    REST APIMCP server

    A JSON-over-HTTPS API at /api/v1 that runs the same operations as the MCP server, with the same keys, scopes, rate limits and billing.

    • Operations for document analysis and comparison, clause search and risk assessment, legal research, redlines, negotiation, workflows, due diligence, templates and drafts.
    • OpenAPI 3.1 document at /api/v1/openapi.json, generated from the same schemas the API validates against.
    • One error shape for every failure: { "error": { "code", "message", "details" } } with stable codes; 401 responses carry WWW-Authenticate and 429 responses Retry-After.
    • MCP connection keys (lbmcp_) work on Pro and Enterprise; organization API keys (lb_) work on Enterprise.
    • MCP tools/call now answers with MCP content blocks and isError, so clients show results and failures correctly.

    REST API documentation

  7. documents_analyze needs edit access to a stored document

    Breaking changeMCP serverREST API

    A full analysis writes to the document, so a key that can only read a shared document can no longer start one.

    • documents_analyze on a stored document now requires edit access to it, the same as analysing it in the app. A key with read access gets an explanation and can use documents_analyze_quick, which reads without writing.
    • Analysing inline content is unchanged.

  8. Quick analysis needs the DOCUMENTS_ANALYZE scope

    Breaking changeMCP server

    documents_analyze_quick runs a model and uses AI credits, so it now needs the analysis scope as well as read access.

    • documents_analyze_quick requires DOCUMENTS_READ and DOCUMENTS_ANALYZE. Keys with only DOCUMENTS_READ no longer see it in tools/list. Text extraction and comparison stay on DOCUMENTS_READ.

  10. MCP tool names are snake_case

    Breaking changeMCP server

    Tool names changed from category/action to category_action so every MCP client accepts them.

    • All tools were renamed, for example clauses/search to clauses_search and documents/analyze to documents_analyze. Several clients rejected names with a slash and silently left those tools out.
    • Update any prompt, allowlist or code that names a tool.

  11. Claude Desktop can connect through mcp-remote

    MCP server

    The initialize response now declares capabilities as objects, as the MCP specification requires.

    • Strict clients, including Claude Desktop through mcp-remote, rejected the earlier initialize response and could not finish connecting.