Skip to content
New: Mac downloadRead →

API

Developer access

Vesso’s Public API v1 is available in beta for enabled workspaces. Teams can read and write CRM records, update tasks, read meetings, transcripts and call intelligence, send product events into contact timelines, and configure signed outbound webhooks to deliver workspace activity to their endpoints.

Public API beta status

API keys and webhooks are currently available for enabled workspaces while the v1 beta stabilizes. Endpoint contracts may change during the beta period. Subscribe to the changelog or contact support@vesso.ai if you need notification before production integration changes.

Connect AI tools with MCP

Vesso’s remote MCP server brings CRM, tasks, meetings, published knowledge and workspace search into supported AI clients. It shares the Platform API access gate. Connect through OAuth or a scoped API key, with audited tool calls and revocable access.

Explore supported clients, scopes and setup →

Authentication

Send API keys as Bearer tokens. Keys are workspace-scoped, include explicit scopes, and should be rotated any time they are exposed.

bash
curl -H "Authorization: Bearer $VESSO_API_KEY" \
  https://api.vesso.ai/v1/me

A successful GET /v1/me response returns the workspace ID, key ID, scopes, and environment for the key.

Core endpoints

Read data

  • →GET /v1/accounts
  • →GET /v1/contacts
  • →GET /v1/opportunities
  • →GET /v1/tasks
  • →GET /v1/meetings

Write data

  • →POST /v1/contacts and PATCH /v1/contacts/{id}
  • →POST /v1/opportunities and PATCH /v1/opportunities/{id}
  • →POST /v1/tasks and PATCH /v1/tasks/{id}

List endpoints use cursor pagination. Write endpoints enforce allowlists so computed or system-managed fields, such as scores and derived analytics, cannot be set from external clients. Account creation is not yet available through the beta API.

Meetings, transcripts and call intelligence

Keys with the meetings:read scope can read recorded meetings and calls. These endpoints are read-only and never return audio or video.

  • →GET /v1/meetings lists meetings and calls, newest first. Filter with start_date, end_date, owner, account_id, opportunity_id and has_recording. Without dates it covers the last 90 days, and one request can span at most 400 days.
  • →GET /v1/meetings/{event_id} returns the meeting, its attendees and recordings, and the AI notes: summary, key points, decisions, next steps and action items.
  • →GET /v1/meetings/{event_id}/transcript returns speaker-labelled segments with start and end times in seconds. It is paginated by segment: limit defaults to 200 and can go up to 1,000. It responds 409 transcript_not_ready while transcription is still running.
  • →GET /v1/meetings/{event_id}/intelligence returns scores, talk-time and interaction stats, sentiment, topics, risks and the methodology scorecard. Pass methodology to pick one framework when a call was scored against several.
bash
# Recorded meetings and calls from October, newest first
curl -H "Authorization: Bearer $VESSO_API_KEY" \
  "https://api.vesso.ai/v1/meetings?start_date=2026-10-01&end_date=2026-10-31&has_recording=true"

# One meeting's transcript, 200 speaker turns at a time
curl -H "Authorization: Bearer $VESSO_API_KEY" \
  "https://api.vesso.ai/v1/meetings/$EVENT_ID/transcript?limit=200"

A key reads the meetings organized by the member who created it, inside that member’s workspace. Meetings it cannot read answer 404. Every transcript read is recorded in the workspace audit log against the key.

Product events

Use POST /v1/events to send customer or product activity into Vesso. Events are matched to contacts by email. Include an idempotency_key to prevent duplicate timeline entries and duplicate webhook deliveries during retries.

bash
curl -X POST https://api.vesso.ai/v1/events \
  -H "Authorization: Bearer $VESSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "buyer@example.com",
    "event_name": "trial_started",
    "idempotency_key": "trial-started-123",
    "properties": { "plan": "growth" }
  }'

Outbound webhooks

Enabled workspaces can subscribe HTTPS endpoints to Vesso events. Deliveries are signed with X-Vesso-Signature using the format t=<timestamp>,v1=<hmac>. Always verify both the timestamp freshness and HMAC before trusting the payload.

javascript
import crypto from 'node:crypto';

function verifyVessoSignature({ rawBody, signatureHeader, secret }) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map((part) => part.split('='))
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!timestamp || !signature) return false;

  const ageSeconds = Math.abs(Date.now() / 1000 - timestamp);
  if (ageSeconds > 300) return false;

  const signedPayload = timestamp + '.' + rawBody;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex')
    );
  } catch {
    return false;
  }
}

Vesso retries failed deliveries and records delivery status so teams can inspect failures and recover receiver outages.

meeting.completed and call.completed carry the meeting’s event_id, its recording_id and links to the meeting endpoints. Transcripts and notes are never sent in a webhook: fetch them with a key that has meetings:read.

json
{
  "delivery_id": "whd_...",
  "attempt": 1,
  "event": {
    "event_type": "meeting.completed",
    "entity_type": "meeting",
    "entity_id": "evt_123",
    "payload": {
      "event_id": "evt_123",
      "recording_id": "rec_456",
      "title": "Acme discovery",
      "has_transcript": true,
      "links": {
        "meeting": "https://api.vesso.ai/v1/meetings/evt_123",
        "transcript": "https://api.vesso.ai/v1/meetings/evt_123/transcript",
        "intelligence": "https://api.vesso.ai/v1/meetings/evt_123/intelligence"
      }
    }
  }
}

Production guidance

  • ✓Keep API keys server-side. Do not embed keys in browser snippets, public pages, or customer-facing scripts.
  • ✓Rate limits are applied per API key during beta. Contact support if a production integration needs higher throughput.
  • ✓Use idempotency keys for event ingestion and external retry logic.
  • ✓Verify webhook signatures with the raw request body before parsing or acting on a payload.

Use the same access foundation with MCP

Connect supported AI clients to the remote MCP endpoint using scoped API keys or an approved OAuth connection. The MCP guides explain tools, acting members, audits, and revocation.