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.

Deal application editor

Read as Markdown

Choose an action to read its inputs, results, and usage guidance. Your connection determines which tools are available to you.

The Deal application editor changes the questions in an existing Deal application. Only the Deal’s processing Portal can use this editor; authorized Support users can also use it with an explicit grant. Access to answer or submit the application does not grant editing access. Changing a form can affect answers, uploaded documents, signatures, and participants who are already using it. To prepare questions for future applications, use Application definitions.

Request access

This MCP toolset requires a specific grant and is not assigned by default. Use Request an integration in the documentation header to request Deal application editor access, or contact Support. Documentation describes the tools; your connection's live discovery determines which you can use. A toolset grant does not grant access to additional applications or Portals.

Edit an existing form

  1. Use providers.list to choose a Portal, then deals.list to find the Deal. Copy the Portal’s provider_slug and the Deal’s returned id as deal_id for every deal_application_editor.* call. Check deals.get and the returned links before changing it. Both selectors must identify the same Portal and Deal; do not supply an application or storage ID.
  2. Read deal_application_editor.get_config and get_config_schema. Include all existing and proposed block_kinds when using its schema to validate a complete document. Retain the current draft and live revisions, and preserve the complete config_version, config_type, and application_runtime_structure document. Reads do not create drafts. Use view: "live" to compare published questions with an existing draft; config_source identifies the returned document while both state tokens remain current. Use open_draft to start or reuse the editable draft, then read it again.
  3. Change only the requested structure. Preserve retained question identities and answer shapes. Call validate_config with the complete candidate. Review the returned answer impacts as well as structural findings.
  4. Explain the exact candidate's effects and save the validated draft directly with deal_application_editor.replace. Pass the unchanged candidate and review_digest; copy live_revision to expected_live_revision and draft_revision to expected_draft_revision. Supply a unique client_request_id; identical retries reuse that key. Read the saved draft to confirm it. Draft edits do not require human approval or user_confirmed, and do not publish the form or delete stored answers.

For an optional file question, change only request.is_required to false. Keep its two ordered request.fields: file / FileValue / is_required: true, followed by file_name / CharValue / is_required: false. These fixed fields describe an uploaded response; they do not make the question mandatory. Start from the block catalog's default_config.

allow_destructive_changes defaults to false for publication. Draft removal leaves stored answers intact. For a deliberately reviewed destructive publication, set the flag consistently in publish_review and publish. Publishing removal of an answered scalar question requires an explicit reviewed decision: it permanently deletes its question and stored answer records, and uploaded files become inaccessible. Restoring the question structure does not restore deleted answers. Unsupported field identity or type conversions, list scope changes, and loss of existing repeated data remain blocked. Do not invent replacement identities to bypass protection.

Work with JSON files

For a large form, use get_config_download (optionally view: "live") and GET the returned URL with transfer_token as a Bearer credential outside the model. Keep the returned state tokens. Open the draft before reviewing edits. Edit the complete UTF-8 JSON envelope locally, preserving identities, then call prepare_config_validation with a JSON filename, exact content_sha256, size_bytes, and both expected revisions. POST the file as multipart field config within five minutes. Files must be at most 1 MiB; validation does not save.

Read the HTTP response's findings and answer impact. If valid, explain the exact change and call prepare_config_replacement directly with its validation_token and client_request_id. POST the same reviewed bytes as multipart config using the returned capability. The response is the saved draft receipt. Changed bytes or state require fresh validation. Identical uncertain retries reuse the same capability, bytes, and request key. Keep credentials private; live access is checked again at redemption.

Change template PDFs

The attachments inventory in get_config identifies template PDFs by stable_block_id. These templates are separate from submitted answer files. Only file questions support template changes; signature templates are unsupported. Use get_attachment_download with the selected block and expected revisions to read a template. Choose view: "live" when comparing the published template to a staged replacement.

For a replacement, call review_attachment_change with action: "set", the PDF filename, exact SHA-256 digest, and size. PDFs must be nonempty and at most 25 MiB. Explain the returned effects and call prepare_attachment_upload directly, passing the exact reviewed metadata, digest, revisions, and request key. POST the reviewed bytes as multipart attachment with the returned Bearer credential within five minutes. Preparation alone does not save; the upload response confirms the staged template.

To remove a template, review action: "remove" without replacement file metadata, then call remove_attachment directly with the review digest, expected revisions, and request key. Template changes affect the draft; publishing and notifications require a separate review and confirmation. Submitted answer files remain unchanged by these attachment actions.

Review publication and notifications

The Deal’s processing Portal controls publication. Access to submit answers does not authorize editing or publishing its questions. Use deal_applications.get_contract and get_answers to inspect existing answers separately; editing questions does not submit the application.

First use publish_review without a recipient selection to inspect the eligible audience, then review an explicit recipient_ids selection and message. Choose only recipients returned as eligible; choose an empty list deliberately when no notification is wanted. Explain the live form changes, existing-answer impacts, selected recipients, and message. Publication is a dangerous action even when no notification is selected.

Ask for human approval of those reviewed effects. Call publish with user_confirmed: true and the exact reviewed digest, preconditions, recipients, and message. If any reviewed state changes, review again and obtain fresh confirmation. Check the publication result and read the live form. If the result includes notification attempts, report their outcomes separately; a selected recipient list does not establish delivery. Do not publish again solely to retry a failed notification.

Recover unpublished changes

Read list_history, then use review_undo followed by undo for the reviewed draft change, or review_reset followed by reset to discard unpublished changes. Explain what will be lost and execute directly with the exact review digest, expected revisions, and request key. Undo and reset do not require human approval. Draft recovery does not reverse live publication or recall notifications. Publication changes the shared live form. Any other Portal drafts keep their template overrides and history, but become stale after a live form publication. Preserve the staged config with a read or download, explicitly review and reset the stale draft, then reapply and validate the intended changes against the current live form. Further draft edits do not rebase it; obtain fresh approval before publication.

Live review tokens also change after answer edits and editor events. If a revision is stale, read the application again, reconcile changes, and obtain a fresh review before retrying a draft action. Publication requires new human approval of the current review. Form edits can advance answer revisions without changing stored values; treat revisions as concurrency tokens rather than edit counts. An identical retry returns the original receipt, so its change indicator describes the original execution rather than a new update. After a timeout or uncertain write outcome, read the authoritative state before another write; do not assume the operation failed or choose a new request identity blindly.

Available tools

deal_application_editor.get_config_schemaRead application form editing contractdeal_application_editor.review_attachment_changeReview application template attachment changedeal_application_editor.get_config_downloadDownload application form configdeal_application_editor.open_draftOpen application form draftdeal_application_editor.prepare_attachment_uploadPrepare reviewed application template uploaddeal_application_editor.list_historyRead application form draft historydeal_application_editor.get_attachment_downloadRead application template PDFdeal_application_editor.get_configRead existing application formdeal_application_editor.remove_attachmentRemove reviewed application template PDFdeal_application_editor.prepare_config_validationReview application form JSON filedeal_application_editor.validate_configReview proposed application form changesdeal_application_editor.replaceSave reviewed application form draftdeal_application_editor.prepare_config_replacementSave reviewed application form filedeal_application_editor.publish_reviewReview application form publicationdeal_application_editor.publishPublish application form changesdeal_application_editor.review_resetReview application form draft resetdeal_application_editor.review_undoReview application form draft undodeal_application_editor.resetReset application form draftdeal_application_editor.undoUndo application form draft