Agent platform guide

DealMeld is a multi-tenant CRM, deal room, communications, delivery, signing, and automation platform. Agents should treat the API as a tenant-scoped operating surface: authenticate, resolve tenant context, discover capabilities, then call the narrowest route that matches the requested user intent.

This guide explains what agents can do. The Complete API surface lists every mounted route from source. The interactive API Reference contains schema-backed details for the routes currently published in OpenAPI.

For CRM writes, read the CRM data model before creating companies, clients, projects, contacts, competitors, or duplicate merges.

Agent operating model

1. Discover platform capabilities with GET /api/agent/capabilities.
2. Load machine-readable artifacts when useful:
   • GET /api/agent/openapi.json
   • GET /api/agent/mcp.json
   • POST /api/agent/mcp for the authenticated MCP Streamable HTTP runtime.
   • GET /api/agent/a2a-card.json
   • GET /api/agent/connectors/{target} for openapi, openclaw, hermes, or custom.
3. Authenticate with either a user JWT or a tenant API access token.
4. Send tenant context on tenant-scoped calls with x-tenant-id.
5. Check feature gates, module access, role permissions, and agent scopes before mutating data.
6. Prefer idempotency keys on retried writes and long-running actions.
7. Use webhooks, jobs, and batch streams instead of polling aggressively.

Authentication and tenant context

Tenant-scoped API calls require a bearer token:

Authorization: Bearer <token>
x-tenant-id: <tenant uuid>

User JWTs represent signed-in users. Tenant API access tokens represent service or agent principals and require explicit tenant context. Agent tokens are scope-checked against the request method and path, and mutating agent calls can be blocked by tenant automation policy.

Admin and owner operations can require a fresh admin session. Do not use service tokens in browser code. Store tokens server-side, rotate them when an integration owner changes, and revoke unused tokens from API access settings.

Response conventions

Most successful responses use:

{
  "success": true,
  "data": {}
}

Paginated list endpoints commonly return data plus pagination fields such as page, pageSize, total, or totalPages. Errors use:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body is invalid"
  }
}

Agents should branch on the stable error.code first, then use the human-readable message for logs or user-facing summaries.

Platform capability map

Product area	App routes	API route groups	Agent capabilities
Dashboard and work queues	/dashboard, /my-work	/api/tenant-health, /api/my-work, /api/notifications	Read tenant health, assigned work, notification state, and operational summaries.
CRM accounts	/companies, /companies/{id}, /companies/{id}/edit	/api/companies, /api/companies/{id}/notes, /api/companies/{id}/dossier	Add, edit, search, enrich, annotate, and inspect company records, activities, contacts, deals, and dossier intelligence.
Contacts	/contacts, /contacts/{id}	/api/contacts, /api/contacts/{id}/notes, /api/contacts/{id}/deals	Add, edit, search, enrich, annotate, and relate people to companies and deals.
Deals	/deals, /deals/{id}	/api/deals, /api/deals/pipeline, /api/deals/{id}/stage, /api/deals/{id}/lineage	Create and update opportunities, classify contract structure, move stages, inspect pipeline state, and trace deal lineage.
Communications	/communications	/api/communications, /api/calls, /api/call-recordings, /api/call-templates, /api/outreach	Log calls, emails, meetings, notes, and tasks; schedule communication; manage attachments and recordings; inspect engagement timelines.
Campaigns and pulse	/campaigns, /pulse, /competitors, /content-multiplexer	/api/campaigns, /api/pulse, /api/competitors, /api/content	Create campaigns, add contacts, launch or pause campaigns, inspect buying signals, maintain competitor dossiers, and generate multiplexed content.
Rooms	/rooms, /rooms/{id}	/api/rooms, /api/rooms/{id}/items, /api/rooms/public/{token}	Create client rooms, update room metadata, manage room items, read public room views, post room events, and collect comments.
Delivery	/clients, /projects, /projects/new, /projects/{id}, /team	/api/clients, /api/projects, /api/tasks, /api/project-templates, /api/my-work	Manage client handoff, projects, tasks, templates, team work, delivery status, lifecycle transitions, and overdue checks.
Commercial documents	Settings and delivery views	/api/quotes, /api/work-orders, /api/invoices, /api/numbering	Create and update quote, work-order, invoice, and numbering records when tenant permissions allow it.
Imports and async jobs	/import, /import/wizard, /import/history, /import/hubspot, /settings/batch-jobs	/api/import, /api/pm-import, /api/jobs, /api/jobs/batch, /api/jobs/batch/{id}/stream	Upload import files, preview mappings, execute imports, create or inspect async jobs, and stream batch job progress.
Settings and access	/settings, /settings/api-access, /settings/organization, /settings/security, /settings/roles, /settings/features	/api/settings/api-access, /api/settings/agents, /api/settings/api-keys, /api/settings/models, /api/assistant, /api/roles, /api/audit-logs, /api/custom-fields, /api/saved-views	Manage API access tokens, agent credentials, assistant availability, model settings, provider keys, roles, audit history, custom fields, and saved views.
Signing	/settings/signing-templates, room item signing states	/api/signing, /api/signing/webhooks/opensign	Manage signing templates, create documents, send/resend/revoke signing requests, download artifacts, and receive signed provider callbacks.
Support and collaboration	/support, /support/new, /support/tickets/{id}	/api/support, /api/comments, /api/reactions, /api/notifications	Create support tickets, attach support files, update ticket status, comment, react, mention users, and mark notifications read.
Billing and checkout	/settings/billing, public lifetime pages	/api/billing, /api/checkout, /api/billing/webhooks/stripe, /api/webhooks/payments	Read plans and subscription state, start checkout sessions, complete/cancel subscription workflows, and process signed payment callbacks.
Platform admin	/admin, /admin/tenants, /admin/users, /admin/billing, /admin/ops, /admin/system, /admin/support	/api/admin	Operator-only tenant, user, billing, support, settings, ops, and system management. Customer agents should not call these routes.

Common automation patterns

Content Multiplexer Validation

POST /api/content/multiplex returns generated channel drafts with shared validation metadata so API clients and the app UI use the same count and limit path. POST /api/content/adapt supports draft-from-source, adapt-channel, shorten-to-fit, and regenerate-all actions. The response still treats deterministic validation as authoritative, returns fit attempts per channel, and exposes only audit-safe hashes for source/style metadata. Saved workspaces are managed through /api/content/drafts; each draft stores the master source, selected channels, editable channel variants, shared links/media metadata, customized state, and server-normalized validation metadata for the current tenant/user. Source imports use /api/content/import-source, while uploaded Multiplexer media stays private and is opened through signed draft media URLs. Approved handoff attempts are managed through /api/content/delivery-jobs. A delivery job must reference a saved draft and explicit approvedFormats; the server snapshots channel readiness, stores rendered text hashes, skips unapproved channels, and exposes copy/open-compose handoff status without silently posting to external accounts.

Target format	Channel	Validation behavior
linkedin-post	LinkedIn	3,000 character max, warning near 2,600 characters.
twitter-thread	Twitter	280 weighted characters per thread segment; URLs count as 23 characters.
facebook-post	Facebook	63,206 character max, warning near long-form copy.
instagram-caption	Instagram	2,200 character max, warning near 2,000 characters.
email-newsletter	Email	Subject, preview, and body counts are returned separately.

Unsupported channel IDs such as threads, mastodon, and bluesky are rejected by request validation.

Agents may prepare, adapt, and update Multiplexer drafts, but they should treat saved variants as draft-only content. Optional CRM context refs must be explicit and tenant-authorized before they are included in adaptation metadata. External delivery still requires an explicit user-approved handoff. Connector delivery requests must use a tenant-configured DealMeld connector path; otherwise the delivery job records a failed connector attempt instead of sending.

Search across the platform

The app's top search box is global. It fans out to bounded list reads for companies, clients, contacts, deals, projects, rooms, communications, campaigns, and competitors, then groups results client-side. Agents should follow the same pattern instead of assuming there is one global search endpoint.

Use search for most list endpoints and q for communications:

GET /api/companies?search=guide&pageSize=4
GET /api/clients?search=guide&pageSize=4
GET /api/contacts?search=guide&pageSize=4
GET /api/communications?q=guide&pageSize=4

Skip modules that are disabled for the tenant or return permission errors.

Create or update CRM data

1. Search before writing with the relevant list endpoint.
2. Create missing records with POST /api/companies, POST /api/contacts, or POST /api/deals.
3. Update existing records with the matching PATCH route.
4. Add notes or activities when the user intent includes context that should remain visible in the timeline.
5. Use enrichment endpoints only when the user or automation policy permits external or AI-assisted enrichment.

Create or link a client

Use POST /api/clients when a company is also a client. Send client_name and either website or domain. If the external client number is known, set it through POST /api/companies or PATCH /api/companies/{id} with client_number or client_id; POST /api/clients auto-assigns a client number when needed. DealMeld first searches company identifiers and legacy website/domain, then high-confidence normalized names and domain brands. If one company matches, it is promoted into the client workspace. If matching is ambiguous, the API returns 409 CONFLICT with candidate company IDs.

Do not create a second company when a conflict response says there are candidate matches. Resolve the duplicate or choose the primary company first.

Merge duplicate CRM records

Use company and contact merge routes only after the primary record is chosen:

POST /api/companies/{primaryCompanyId}/merge
POST /api/contacts/{primaryContactId}/merge

The request body names the duplicate ID. DealMeld reparents related identifiers, contacts, notes, deals, projects, communications, signing records, custom fields, and activity history before soft-deleting the duplicate. Treat merge as a destructive cleanup action even though the duplicate remains recoverable at the database level.

Work a deal

1. Read the deal and pipeline with /api/deals/{id} and /api/deals/pipeline.
2. Update fields with PATCH /api/deals/{id}.
3. Move stages with PATCH /api/deals/{id}/stage.
4. Link related contacts, communications, rooms, and delivery records through their resource-specific endpoints.

Prepare a client room

1. Create or fetch the room with /api/rooms.
2. Add room items with /api/rooms/{id}/items.
3. Attach signing documents when the item needs signature.
4. Use public room token routes only for public room viewing, events, and comments.
5. Never expose private tenant tokens in room URLs or public metadata.

Import data

1. Upload the file through /api/import or the project-management import routes.
2. Preview and validate mappings before execution.
3. Execute the import after the user approves the mapping.
4. Track work through /api/jobs, /api/jobs/batch, or the batch SSE stream.
5. Handle partial failures as records to review, not as a reason to retry the whole import blindly.

Propose risky agent actions

Agents can use /api/agent/actions/proposals to queue risky actions for approval. Human admins or owners approve or reject through /api/agent/actions/approvals/{approvalId}/approve or /api/agent/actions/approvals/{approvalId}/reject.

Risky actions include external sends, financial actions, destructive updates, and signing actions. If tenant automation is disabled, mutating agent requests can return AGENT_AUTOMATION_DISABLED.

Use the MCP runtime

POST /api/agent/mcp is the authenticated Streamable HTTP JSON-RPC endpoint for MCP clients. It supports initialize, tools/list, tools/call, resources/list, resources/templates/list, resources/read, prompts/list, and prompts/get.

MCP clients still send Authorization: Bearer <token> and x-tenant-id. Agent tokens need runtime scope such as agent.mcp:use or agent.runtime:use, plus the underlying tool scope such as crm.companies:read or crm.deals:write. Mutating tools require idempotencyKey and are routed through tenant automation and approval policy. Resource reads return redacted JSON and must not expose signer URLs, signed artifact URLs, provider payloads, tokens, or secrets.

Use the in-app assistant API

POST /api/assistant/chat powers the app shell assistant for signed-in users. It reads tenant-scoped CRM context through the same authenticated API routes a user can access, resolves the tenant/user model provider, returns citations to source records, and routes draft follow-ups, task proposals, and room updates into the agent approval queue instead of executing writes directly.

Admins and owners can enable or disable the workspace assistant through PATCH /api/assistant/settings; all authenticated tenant users can read the current setting with GET /api/assistant/settings. A disabled assistant returns ASSISTANT_DISABLED, and provider failures return deterministic fallback text with providerUnavailable so the UI can explain the degraded state without leaking credentials.

Feature gates and permissions

DealMeld is multi-tenant and module-gated. A route being mounted does not mean every tenant or token can use it.

Gate	Applies to
Tenant membership	Most authenticated routes. The token must resolve to the requested tenant.
Role permissions	Entity actions such as companies.read, contacts.update, tasks.create, or signing.read.
Agent scopes	API access tokens are scoped by method/path capability.
Admin session	Sensitive settings and credential routes can require recent human admin reauthentication.
Feature flags	Campaigns, pulse, competitors, multiplexer, rooms, deals, communications, import, command center, and other product modules.
Module access	Delivery features such as projects and tasks require delivery module access.
Platform admin	/api/admin routes require platform administrator privileges.

Agents should report permission failures clearly and ask for the missing permission or feature to be enabled. Do not retry 403, 423, or feature-disabled responses as if they were transient outages.

Rate limits, retries, and idempotency

General API traffic is rate-limited. Protected user traffic uses a user-aware limiter. Tenant write traffic is separately limited for POST, PATCH, PUT, and DELETE. Public webhook and public room routes have their own limits.

For retries:

• Retry only idempotent reads and explicitly idempotent writes.
• Include Idempotency-Key on write retries when the route supports it or the action could create duplicates.
• Back off on 429 and use the server-provided retry guidance when available.
• Use job and webhook state instead of tight polling loops.

Webhooks

Tenant webhook subscriptions live under /api/webhooks. They let integrations receive DealMeld events and delivery history. Signed provider ingress routes include payment and signing callbacks. Public ingress routes authenticate with provider-specific signatures, not bearer tokens.

When building webhook consumers:

• Verify signatures on inbound provider callbacks.
• Treat delivery as at least once.
• Use event ids or object ids for idempotency.
• Store delivery attempts and response status for troubleshooting.

Relationship intelligence

DealMeld exposes a bounded relationship intelligence layer so agents can help users understand contact context, identify due relationships, and prepare drafts. Agents must not gain a privileged path around RBAC, tenant isolation, idempotency, approval, or audit policy.

Read actions

• relationship.summary.read — Read the canonical relationship summary projection for an authorized contact (context, derived signals, recency band, governance envelope).
• relationship.followups.list — List bounded due relationship follow-ups with reason, priority, source evidence version, and suppression status.

Reads are risk read, approval not_required, no idempotency, and available to both human and agent principals.

Deferred relationship actions

The earlier semantic actions for follow-up evidence reads, commitment reads, participation reads, relationship proposals, disposition recording, and outcome recording are deferred until each has a distinct invokable endpoint and the source-version precondition contract is enforced. They are not advertised in the neutral manifest or generated connector artifacts.

Agent behavior rules

• Agents may read authorized relationship summaries and due-review candidates.
• Agents may not create versioned draft proposals, record dispositions, or produce relationship execution receipts until typed endpoints ship.
• No neutral capability may select a recipient/channel/send time or send, schedule, retry, switch channels, escalate, or treat approval as an external relationship action.
• Agents must not infer a promise from arbitrary text, mark a commitment fulfilled without attributable evidence, submit an application, contact an organizer, book travel, accept terms, pay, or publish.
• Agents must cite the contact/company, last meaningful touch, unresolved next step, and selected resource. State when evidence is missing or stale. Never claim that a recipient is interested in a topic unless a source record supports it.

See the CRM data model for the stored vs. derived relationship data model and governance rules.

Source-backed route catalog

The complete route catalog is generated from mounted Express routes in apps/api/src/index.ts and apps/api/src/routes/*.ts. It currently tracks:

Metric	Count
Mounted source operations	546
Operations represented in the interactive OpenAPI reference	506
Tenant, user, or agent-callable operations	459
Platform admin or operator operations	60

The route catalog is the broadest current reference. The OpenAPI reference remains the source for schema-backed endpoint details where coverage exists.

OpenAPI schema gap

The current documentation now exposes the full mounted API surface, but the interactive OpenAPI reference is still not schema-complete for every tenant automation route. Until schema coverage catches up, use this guide plus the Complete API surface to discover capabilities, then prefer the OpenAPI-backed route definitions when they exist.