Answering requests with an AI agent

An assistant that speaks MCP, such as Claude, can do all of this through Cerclen's MCP server without code. This guide is for agents you write yourself.

An agent works through the same steps a person does: find what's assigned, read the request and its conversation, fetch the files, and post an answer. It does so with your key, as you.

Before you startCopy Anchor Link

• Give the agent its own key, named for it, so its calls are easy to tell apart and to revoke.
• Limit the key to the deals the agent works on.
• Use a read only key for an agent that only reads, summarizes or drafts outside Cerclen.

1. Find your workCopy Anchor Link

Your person id on a deal is me.participant_id:

curl https://app.cerclen.com/api/v1/deals/$DEAL_ID \
  -H "Authorization: Bearer $CERCLEN_KEY"

Requests assigned to you are those whose assignee_id is that id; those still to answer have a status other than complete. Sections (kind: "section") are headings: skip them.

import os
import httpx

api = httpx.Client(
    base_url="https://app.cerclen.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['CERCLEN_KEY']}"},
)
deal_id = os.environ["DEAL_ID"]
me = api.get(f"/deals/{deal_id}").json()["me"]["participant_id"]
todo = [
    r
    for r in api.get(f"/deals/{deal_id}/requests").json()
    if r["kind"] == "request" and r["assignee_id"] == me and r["status"] != "complete"
]
for r in todo:
    print(r["number"], r["title"], r["due_date"])

2. Read the requestCopy Anchor Link

body is the request in full, in Markdown. The conversation has every answer, question and note you may see, oldest first:

curl https://app.cerclen.com/api/v1/deals/$DEAL_ID/requests/$REQUEST_ID/messages \
  -H "Authorization: Bearer $CERCLEN_KEY"

A file given in answer has a version_id. Ask for a download link, then fetch the link without your key, soon: it expires within a minute.

curl -X POST https://app.cerclen.com/api/v1/deals/$DEAL_ID/files/$VERSION_ID/download-link \
  -H "Authorization: Bearer $CERCLEN_KEY"

3. AnswerCopy Anchor Link

curl -X POST https://app.cerclen.com/api/v1/deals/$DEAL_ID/requests/$REQUEST_ID/messages \
  -H "Authorization: Bearer $CERCLEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The FY2025 audited accounts are in the data room.",
    "links": [{ "url": "https://dataroom.example.com/f/123", "label": "FY2025 audit" }]
  }'

• An answer (kind: "response", the default) moves the request to complete, or to partial with "partial": true. Send "update_status": false to leave the status as it is.
• kind can also be question (asking the other side), reference or internal_note.
• Answers can carry up to 20 https links, to a data room or a drive. Uploading files through the API isn't available yet.
• The answer appears at once, under your name, marked via API, and the other side is notified as for any answer.

Drafts and reviewCopy Anchor Link

On the side that runs the request list, an agent can post "internal": true (or an internal_note): only your side sees it, so a colleague can check it and post the final answer.

On the other side, everything you post is shared: there are no private notes there. If an agent's answers need a person's review first, have it prepare them outside Cerclen and post only what has been checked.

Be a good citizenCopy Anchor Link

• Stay under about 600 calls a minute per key; past that, wait as Retry-After says. See Errors and limits.
• A list you poll answers 304 Not Modified to If-None-Match when nothing has changed.
• Point the agent at /llms.txt and the OpenAPI document: they describe this API for machines.