Documentation

Everything you need to integrate with the Veld AI platform.

Overview

Veld AI provides a RESTful API and TypeScript SDK for programmatic access to signals, tasks, CRM deals, and agent management. All endpoints require authentication via API key or OAuth bearer token.

Base URL: https://api.veldai.io/api/v1

Quickstart

npm install @veldai/sdk

import { VeldAI } from '@veldai/sdk';

const veld = new VeldAI({
  apiKey: process.env.VELD_API_KEY,
});

// List recent signals
const signals = await veld.signals.list({ limit: 10 });
console.log(signals);

Authentication

All API requests must include an Authorization header with a valid API key or OAuth access token.

curl -H "Authorization: Bearer veld_sk_live_..." \
  https://api.veldai.io/api/v1/signals

API Reference

GET

/api/v1/signals

List all extracted signals with filtering and pagination.

POST

/api/v1/signals

Manually create a signal from an external source.

GET

/api/v1/tasks

List all tasks with status, priority, and assignee filters.

POST

/api/v1/tasks

Create a task manually or from an existing signal.

GET

/api/v1/teams

List team members, roles, and permissions.

GET

/api/v1/agents

List running agents and their current status.

GET

/api/v1/crm/deals

List CRM deals with pipeline stage and value.

POST

/api/v1/crm/deals

Create or update a deal in the CRM pipeline.

Microsoft 365 Integration

Veld AI connects to Microsoft 365 via the Graph API with delegated permissions. Required scopes:

Mail.Read
Calendars.Read
OnlineMeetings.Read
User.Read
Team.ReadBasic.All

Webhooks

Configure webhooks to receive real-time notifications when signals are created, tasks are updated, or deals progress through your pipeline.

POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhook",
  "events": ["signal.created", "task.updated", "deal.stage_changed"],
  "secret": "whsec_..."
}

TypeScript SDK

import { VeldAI } from '@veldai/sdk';

const veld = new VeldAI({ apiKey: 'veld_sk_live_...' });

// Create a task from a signal
const task = await veld.tasks.create({
  signalId: 'sig_abc123',
  title: 'Follow up with Acme Corp',
  priority: 'high',
  assignee: 'jane@company.com',
});

Rate Limits

Plan	Requests/min	Burst
Starter	60	10
Team	300	50
Enterprise	Custom	Custom

Error Codes

Code	Meaning
401	Invalid or missing API key
403	Insufficient permissions
404	Resource not found
422	Validation error — check request body
429	Rate limit exceeded
500	Internal server error — contact support