Skip to content
Levr API Documentation
Download OpenAPI specOpenAPI

Hand off to an AI agent

Copy instructions to your AI agent

Copy this guide into your AI agent. It links to the current REST API and MCP documentation.

You are helping someone integrate their system with Levr. Use Levr's published documentation and machine-readable contracts as the source of truth. Do not invent endpoints, fields, or MCP tools.

  1. Start with the Levr API documentation to choose between a server-to-server REST integration and a user-authorized MCP connection.
  2. For REST, read the Markdown REST API guide, choose the user’s task, then fetch only the relevant resource guide and operation Markdown. Resource indexes include task guidance. For funding recommendations, start with the Matchmaking guide. Use the OpenAPI specification for exact paths, authentication, parameters, and envelope schemas.
  3. For REST client intake, Deal applications, or project Criteria, fetch that resource's contract_url. Its Application Contract is the authority for the current questions, stable keys, repeatable groups, file-transfer steps, accepted answer shapes, conditional visibility, supported operation URLs, and integration instructions. Repeatable fields require the returned item_id. File bytes use the expiring upload_url and multipart field named file; they never belong in JSON. Do not substitute a static example or the latest application definition.
  4. For an AI client acting with a signed-in user's access, read the MCP connection instructions in Markdown first, then the Model Context Protocol guide if needed. Let the connected MCP server expose its current tools and input contracts; do not infer tools from the REST API. Read the relevant MCP resource guide and follow the discovered tool’s revision, file-transfer, and confirmation requirements.
  5. Use URLs from the record handoff when supplied; otherwise use this documentation environment. Keep API keys and file-transfer credentials out of browser code, logs, prompts, and source control.
  6. Before implementing a write, verify authentication, required inputs, idempotency, error responses, and retry guidance in the current contract. If an operation is not documented, do not assume it exists.

Early access

Request an integration

Tell us what your integration needs to do. Add an email if you want a reply.

Chat guide

Work with a chat group

Read as Markdown

Connect your system to a group

Use chat to follow a business or Deal conversation from your CRM, or post an update from your underwriting system. Your API key is the sender: messages show its label, not the user who created the key. Rotating its token preserves that identity.

Give the key conversations:read to monitor groups, or conversations:write to send messages and upload files. The API exposes public groups within the key’s provider and source scope. Private groups and direct messages remain unavailable, even if the integration previously posted there. MCP and Levr AI instead act as the signed-in user and retain their origin attribution.

For a connected AI assistant, follow Chat and messages with MCP. MCP uses user OAuth and does not require this API key.

Find the group

The following responses illustrate one workflow. IDs and timestamps are examples; copy values from your own responses. The example.invalid link is illustrative; open the actual returned frontend_link.

List groups, optionally filtering by a Business or Deal ID copied from those APIs:

GET /v1/conversations/?business_id=biz_6q3n8v2k9m4x7p5r
Authorization: Bearer YOUR_API_KEY

Example 200 OK response:

{
  "object": "list",
  "items": [
    {
      "id": "chat_7k2m9q4v6x8n3p5r",
      "object": "conversation",
      "name": "Application updates",
      "kind": "group",
      "visibility": "public",
      "frontend_link": "https://example.invalid/chat/chat_7k2m9q4v6x8n3p5r",
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-01-15T09:30:00Z",
      "business_id": "biz_6q3n8v2k9m4x7p5r",
      "deal_id": null
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}

The id field is the conversation’s slug: a system-generated, opaque identifier such as chat_7k2m9q4v6x8n3p5r. The API calls this value id in responses and conversation_id in URL parameters. Copy it exactly; do not derive it from the group name or use a database ID.

Copy items[0].id as conversation_id. business_id and deal_id identify linked records when available; null means no linked record is exposed. Here, next_cursor: null means there are no more groups in this result.

Use deal_id for a Deal, or search for a group name. Collections accept page_size from 1 to 100 and opaque cursor values. Group ordering accepts created_at, -created_at, updated_at, or -updated_at and defaults to -updated_at. Combine up to three ordering fields with commas. Keep the filters and ordering unchanged when following a cursor. Follow next_cursor until you find the intended group. Save its chat_ ID; names can change. A business or Deal may have several groups, so confirm the group before posting. An empty list means no public group is available to this key; it does not create one.

Use GET /v1/conversations/chat_7k2m9q4v6x8n3p5r/participants/ to inspect the audience. Copy participant IDs into mentioned_participant_slugs when mentioning someone; typing their name alone is not a mention.

Example participants response (200 OK):

{
  "object": "list",
  "items": [
    {
      "id": "chp_3m8q5v2n9k4x7p6r",
      "name": "Alex Rivera",
      "email": "alex@example.invalid",
      "participation_mode": "account",
      "created_at": "2026-01-15T09:00:00Z"
    },
    {
      "id": "chp_8v2k6q9m3n7x4p5r",
      "name": "Jordan Lee",
      "email": "jordan@example.invalid",
      "participation_mode": "email",
      "created_at": "2026-01-15T09:05:00Z"
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}

account identifies a Levr account; email identifies an email-only participant. Mention Alex using "mentioned_participant_slugs": ["chp_3m8q5v2n9k4x7p6r"].

Read its messages:

GET /v1/conversations/chat_7k2m9q4v6x8n3p5r/messages/?page_size=20
Authorization: Bearer YOUR_API_KEY

Example messages response (200 OK):

{
  "object": "list",
  "items": [
    {
      "id": "msg_2v8q5n7k4m9x6p3r",
      "object": "chat_message",
      "conversation_id": "chat_7k2m9q4v6x8n3p5r",
      "text": "Please upload the latest bank statement.",
      "version": 1,
      "created_at": "2026-01-15T09:30:00Z",
      "edited_at": null,
      "deleted_at": null,
      "reply_to_id": null,
      "author": {
        "id": "chp_3m8q5v2n9k4x7p6r",
        "name": "Alex Rivera",
        "participation_mode": "account"
      },
      "origin": null,
      "attachments": []
    }
  ],
  "next_cursor": null,
  "previous_cursor": null
}

author identifies the sender. reply_to_id: null means this is not a reply; attachments: [] means no files. edited_at and deleted_at remain null until those actions occur.

Message ordering accepts created_at or -created_at and defaults to newest first (-created_at). Use search to match current message text. Participant ordering accepts those same two creation-time values and defaults to oldest first. Private groups, direct conversations, and out-of-scope IDs return 404 on detail, message, participant, attachment, edit, and delete endpoints, even if your integration was previously a participant. Follow next_cursor for older messages. Reading through the API does not mark messages read for a person. Deleted messages retain their ID and version but return empty content.

Send an update

The target group is selected by the conversation slug in the URL, not in the JSON body:

POST /v1/conversations/{conversation_id}/messages/

Replace {conversation_id} with the id returned by group discovery. Using the example response above:

POST /v1/conversations/chat_7k2m9q4v6x8n3p5r/messages/
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: crm-case-148-update-3
Content-Type: application/json

{
  "text": "We have reviewed the statements. Please upload the latest bank statement."
}

Example 201 Created response:

{
  "id": "msg_9p4r7k2v8m5q3n6x",
  "object": "chat_message",
  "conversation_id": "chat_7k2m9q4v6x8n3p5r",
  "text": "We have reviewed the statements. Please upload the latest bank statement.",
  "version": 1,
  "created_at": "2026-01-15T10:00:00Z",
  "edited_at": null,
  "deleted_at": null,
  "reply_to_id": null,
  "author": {
    "id": "chp_5n9x3q7v2k8m4p6r",
    "name": "Acme CRM",
    "participation_mode": "integration"
  },
  "origin": {
    "source": "external_api"
  },
  "attachments": []
}

The integration is the author (chp_5n9x3q7v2k8m4p6r), and origin.source records that the message came through the External API. Save the returned message ID and version. Reuse the same key and body after a timeout to recover the original response. Changing the body with the same key returns 409; use a new key for a new message. To reply to a specific message, include its ID as reply_to_slug.

Messages to email participants consume the sending provider’s guest-email allowance. A limit error rejects the send; it does not silently omit those recipients. Account notification emails are separate from this allowance.

Include a file

POST one multipart field named file to /v1/conversations/chat_7k2m9q4v6x8n3p5r/attachments/, with an Idempotency-Key. Each file can be up to 25 MiB. Example 201 Created upload response:

{
  "id": "chatfile_4q7n2v9k5m8x3p6r",
  "name": "bank-statement.pdf",
  "size": 48271,
  "content_type": "application/pdf"
}

size is in bytes. Copy the returned id into attachment_slugs when sending:

{
  "text": "The assessment is attached.",
  "attachment_slugs": ["chatfile_4q7n2v9k5m8x3p6r"]
}

Use the actual returned ID. Uploading alone does not share a file: a draft is visible only to the uploading API identity. Sending binds it to one message. Conversations with email participants allow at most 18 MiB of combined attachments per message.

After sending, the message response includes that same file object in its attachments array.

Download an authorized original from GET /v1/chat-attachments/{attachment_id}/download/. Files attached to deleted messages are unavailable.

Follow changes with webhooks

Subscribe your webhook destination to chat.message_sent, chat.message_edited, and chat.message_deleted. Each event contains conversation_id, message_id, and version. Fetch the current message from GET /v1/chat-messages/{message_id}/ when you need its content.

Example data object within a chat.message_sent webhook (not the full delivery envelope):

{
  "conversation_id": "chat_7k2m9q4v6x8n3p5r",
  "message_id": "msg_9p4r7k2v8m5q3n6x",
  "version": 1
}

Use message_id to fetch the message; the webhook data contains identifiers and a version, rather than the message text.

Deduplicate webhook deliveries by their event ID. Events can arrive after later edits, so the fetched message may have a higher version. Access is checked again before delivery; making a group private stops further API access and delivery of queued events for it. Webhooks never grant access to a group.

Your own API messages also produce events. Compare the message’s author ID with the integration author ID returned by your sends before generating an automated response, to avoid a reply loop.

Correct your integration’s message

Read /v1/chat-messages/{message_id}/ and copy its ETag. PATCH that URL with a new text, If-Match, and Idempotency-Key. DELETE uses the same headers and no body. Only the API identity that sent the message may change it.

For example, reading msg_9p4r7k2v8m5q3n6x returns the message above with ETag: "1". To correct it:

PATCH /v1/chat-messages/msg_9p4r7k2v8m5q3n6x/
Authorization: Bearer YOUR_API_KEY
If-Match: "1"
Idempotency-Key: crm-case-148-correction-1
Content-Type: application/json

{
  "text": "We have reviewed the statements. No further documents are needed."
}

The 200 OK response is the same message shape. These fields change (excerpt):

{
  "id": "msg_9p4r7k2v8m5q3n6x",
  "text": "We have reviewed the statements. No further documents are needed.",
  "version": 2,
  "edited_at": "2026-01-15T10:15:00Z"
}

The new response ETag is "2". A subsequent deletion returns the message with a higher version, text: "", attachments: [], and a populated deleted_at.

A 412 means another change won: read the message again before deciding what to do. Edits and deletions update the chat transcript; they cannot retract emails already sent.

Follow application reviews separately

A request to update documents or answers belongs to the application. Sending that review emails the selected collaborators; it does not send a chat message. Starting a discussion afterward is a separate action.

Subscribe to deal_application.review_sent or client_intake_application.review_sent to follow these requests. Each event identifies the application and includes returned_document_count and review_note_count. updated_at records when the review was sent. A review may contain documents, notes, or both. Draft notes and queued returns do not trigger an event.

Use conversations permissions for chat. Reading the linked application requires deal_applications:read or client_intake_applications:read; chat access does not grant application access. Webhook destinations have their own event subscriptions and provider or Lead source scope, independent of API keys.

These events report a sent review, not confirmed email delivery. They leave the application's status unchanged. Continue using application updated events for answer edits and status_changed events for decisions.