Joan eduki nagusira

Garatzaileak

Garatzaileentzako aldaketa-erregistroa

Integrazio batek nabari dezakeen REST APIaren eta MCP zerbitzariaren aldaketa guztiak. Aldaketa hausleak markatuta daude.

  1. API version 2026-12-01

    Aldaketa hausleaREST APIaSDKak

    An operation held for approval reports awaiting_approval instead of running. Keys created from today use this version; existing keys stay on their version until you send Attorly-Version.

    • GET /api/v1/operations/{id} answers status "awaiting_approval" for an MCP call held on Settings › Developers › Approvals, read with the key or connected app that made it. Before this version the same operation read "running" until the decision, and the SDKs waited for it as for any running call.
    • The SDKs are regenerated for 2026-12-01: the Operation status type gains awaiting_approval, and wait() keeps polling such an operation until the decision or its own timeout.
    • The REST API itself still never holds a call: an integration is code, not a conversation. Only operations made over MCP can be awaiting_approval.

    Versioning

  2. Held calls: a reminder, a definite lapse, and webhook events

    MCP zerbitzariaREST APIaEzarpenak

    A call held for approval now reminds its owner before it lapses, lapses into a definite failed operation the client can read, and tells webhook endpoints when it is held and when it lapses. Integrations can react instead of polling.

    • operation.approval_requested is sent when a call is held; operation.succeeded or operation.failed follows the decision as before.
    • A call nobody decided within 24 hours is settled as failed with 403 forbidden (No one approved this call in Attorly within 24 hours) and kept readable for another 24 hours, so operations_get, tasks/get and GET /api/v1/operations/{id} answer instead of reporting an unknown operation. operation.approval_lapsed is sent alongside operation.failed.
    • The owner gets an in-app reminder four hours before a held call lapses.

    Webhooks

  3. Try a connected app in test mode

    EzarpenakMCP zerbitzariaREST APIa

    A connected app can be switched to test mode on Settings › Developers. Every call it makes then runs against your organization’s sample data and fixed results — no live documents, no AI, no credits — like a test key’s, so you can see what an assistant does before handing it real work.

    • Each connected app has a Test mode switch and shows a Test badge while it is on. Only the person who connected the app can switch it.
    • In test mode the app reads and writes the organization’s test-mode objects (the ones test keys create, cleared with DELETE /api/v1/test-data), gets fixture results from AI tools, is never held for approval and is left out of the audit log, exactly as a test key is. The request log records its calls in test mode.
    • Switching back to live takes effect on the app’s next call; nothing it did in test mode touches live data.

    Troubleshooting

  4. Agent profiles: say what an assistant is for

    EzarpenakMCP zerbitzaria

    Creating a key or connecting an app starts with one choice — Read only, Reviewer, Negotiator, Drafter, Case manager or Full access — instead of a dozen permission boxes. A profile sets the permissions and, for a key, the approval policy it starts with.

    • Read only reads documents, clauses, templates, legal sources and cases; Reviewer adds AI analysis; Negotiator adds redlines, negotiation analysis and uploading, with resolving redlines held for approval; Drafter adds drafting, workflows and uploading; Case manager adds keeping a case’s timeline, deadlines, facts and parties; Full access is everything, with destructive calls held for approval. Custom still lets you tick each permission.
    • The consent screen offers the same profiles, cut down to what the app asked for; Everything the app asks for grants its whole request, and any tick outside a profile is Choose myself.
    • POST /api/mcp/connections takes an optional approvalPolicy. The Standard preset is gone; a key made with it shows as a custom set of permissions and keeps working.

    Permissions

  5. Limit a key or connected app to named tools

    MCP zerbitzariaREST APIaEzarpenak

    Permissions say what a credential may do by area; a key or connected app can now also be limited to named tools, under Settings › Developers. Tools outside its list are left out of its tool list and refused, so an assistant connected to search clauses can be exactly that.

    • Each key and connected app has a Tools setting: every tool its permissions allow, or only the ones you pick. The picker offers the tools the permissions allow; the account context (organization_get_context) and operations_get are always offered.
    • tools/list offers only the named tools. A call outside the list fails with errorCode forbidden over MCP and 403 forbidden over the REST API, naming the tools the credential may use.
    • A member of a named composed tool stays callable by its own name: allowing analyses_create allows documents_analyze and documents_analyze_quick. Naming a member alone does not allow the composed tool.
    • The connection check reports the tools a limited credential is actually offered.

    Permissions

  6. What each key and connected app did lately

    Ezarpenak

    Every key and connected app on Settings › Developers has an Activity section: the last week’s requests and failures, when it was last seen and last failed, and its newest calls, with the full log one link away. It answers what an assistant did with your account without leaving the card.

    • Activity opens on demand under each key and app, next to Check connection, and reads the same request log as the Logs tab: live calls only, kept 30 days.
    • A revoked key keeps its activity: the log holds what it did before it was revoked.
    • See every request in the log opens the Logs tab filtered to that credential; the tab now takes a credential in its URL.
  7. MCP calls can wait for your approval

    MCP zerbitzariaEzarpenak

    Resolving redlines through a connected app is held until you approve it on Settings › Developers › Approvals: an assistant acts on a conversation, and a change it cannot take back should not ride on a misunderstanding. A key or app can also be set to ask before every change; the REST API is unchanged.

    • Each key and connected app on Settings › Developers has an approval policy, Ask me first: never, before destructive calls, or before every change. Connected apps start at destructive calls; keys at never. Destructive tools are those whose destructiveHint is set, such as redlines_apply. Deleting a document or a timeline event is never held here: those tools already ask you themselves, in your app or in Attorly, so you are asked once. Every change means every tool without readOnlyHint, from documents_upload to redlines_generate; a composed tool is judged by the member a call runs.
    • A held call is an operation in awaiting_approval. With the Tasks extension the client gets a task in input_required; otherwise a tool result with errorCode approval_required and the operation id. operations_get and tasks/get report the state until you decide; the call lapses after 24 hours.
    • You get an in-app notification. Approving runs the call as the client would have, with the credential loaded again (a revoked key or a disconnected app stops it), and stores the result where the client reads it. Denying stores a forbidden error that names the reason.
    • Test-mode keys are never held, and a call made over the REST API is never held: an integration is code, not a conversation.

    Troubleshooting

  8. Check a connection from Attorly’s side

    EzarpenakMCP zerbitzariaREST APIa

    Every key and connected app on Settings › Developers has a Check connection button: five checks, from the credential to a real tool call, say why an assistant does or does not work without reading its error log.

    • The credential: active, not expired or expiring this week; for a connected app, that it still holds a token to sign in with.
    • Its owner: still a member of the organization, on a plan with API access.
    • Its permissions: the tools and prompts the client is offered, named, and a warning when they unlock nothing beyond the account context.
    • Its last 24 hours in the request log, with the last failure’s code when the most recent request failed.
    • A real call: organization_get_context, run exactly as the client would run it (audit row, rate limit), skipped when an earlier check already explains the refusal.

    Settings › Developers

  9. Prompts on the MCP server

    MCP zerbitzariaEzarpenak

    Six ready-made prompts for the jobs people connect Attorly for, offered through prompts/list and prompts/get: a slash command in Claude Code, a prompt in the Claude and ChatGPT pickers.

    • review_contract, compare_contracts, propose_redlines, research_question, due_diligence_briefing and draft_document. Each takes named arguments, tells the model which tools to use in what order and how to report, and links the document it is about as a resource.
    • A prompt is offered only to a connection that may use the tools it leads with; prompts/get on one it may not use answers as a tool call would (a step-up challenge for OAuth, a forbidden error for keys). A missing required argument is an invalid-params error naming it.
    • The server advertises the prompts capability in both protocol eras. The MCP docs list every prompt with its arguments, and Settings › Developers › Connect shows what to ask once an assistant is connected.

    Prompts

  10. A smaller MCP tool list: 42 tools instead of 50

    MCP zerbitzaria

    Six new tools each stand in for two or three that did one job in different ways, so an assistant reads fewer tools on every turn and the consent screen shows fewer. Every earlier tool name still works, and the REST API is unchanged.

    • analyses_create analyses a contract: mode "full" (the clause-level analysis of a stored document, as documents_analyze) or "quick" (a single-pass review of a document or of text, as documents_analyze_quick).
    • clauses_assess assesses one clause: check "risk", "market" or "playbook" (clauses_analyze_risk, clauses_compare_to_market, clauses_check_playbook). The result is under the key of the check.
    • due_diligence_projects lists the projects or, with projectId, gets one, always as a page of projects (due_diligence_list_projects, due_diligence_get_project).
    • workflows_list lists kind "templates" or "executions" (workflows_list_templates, workflows_list_executions).
    • drafts_create writes a draft: mode "template" or "ai" (templates_draft, templates_generate_ai), as POST /api/v1/drafts does.
    • negotiations_plan analyses a position (mode "position") or builds a playbook (mode "playbook") (negotiations_analyze_position, negotiations_generate_playbook).
    • analyses_list is no longer offered in tools/list; documents_get carries the latest analysis and analyses_get the full content. It stays callable, and GET /api/v1/documents/{documentId}/analyses is unchanged.
    • A composed tool validates a call as the member it runs, counts against that member’s rate limit, and runs as a durable operation only when that member does. Server version 2.1.0.

    MCP tools

  11. Connect an assistant with a sign-in, and start read-only

    MCP zerbitzariaEzarpenak

    Claude, ChatGPT, Claude Code, Cursor and VS Code now connect by signing in to Attorly from the assistant itself; no key is pasted. A new connection, and a new key, can only read until you allow more.

    • Settings › Developers opens on Connect: pick the assistant and follow its sign-in steps, with the server URL to paste, the numbered settings flow for Claude and ChatGPT, and one-click install for Cursor and VS Code. The apps you allowed are listed below it.
    • The consent screen starts with reading ticked (documents, clauses, research and templates) and what the app already holds; writing, analysing, redlines, deletion and due diligence are ticked by you. A new API key starts from the same read-only preset.
    • Quickstarts at /docs/mcp/claude (claude.ai and the Claude apps), /docs/mcp/chatgpt and /docs/mcp/openai-api; /docs/mcp/claude-desktop redirects to the Claude guide. The Claude Code, Cursor and VS Code guides lead with the sign-in and keep the key setup for scripts.
    • When a tool needs a permission the app was not granted, the server answers insufficient_scope with the scope it needs, and the client signs in again to a consent screen that adds only that permission.

    MCP setup guidesPermissions

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

    MCP zerbitzariaREST APIaEzarpenak

    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

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

    REST APIaMCP zerbitzariaEzarpenak

    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

  14. API version 2026-11-01

    Aldaketa hausleaREST APIa

    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

  15. Settings › Developers and per-client setup guides

    EzarpenakMCP zerbitzariaREST APIa

    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

  16. Documents resource, idempotency and asynchronous operations

    REST APIaMCP zerbitzaria

    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

  17. Public REST API

    REST APIaMCP zerbitzaria

    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

  18. documents_analyze needs edit access to a stored document

    Aldaketa hausleaMCP zerbitzariaREST APIa

    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.
  19. Quick analysis needs the DOCUMENTS_ANALYZE scope

    Aldaketa hausleaMCP zerbitzaria

    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.
  20. MCP tool names are snake_case

    Aldaketa hausleaMCP zerbitzaria

    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.
  21. Claude Desktop can connect through mcp-remote

    MCP zerbitzaria

    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.