Vercel AI SDK

The @apiverve/ai-sdk package gives a Vercel AI SDK model APIVerve as tools. Six cover the common lookups directly; two more let the model search the catalog and call any API in it by id.

bash

npm install @apiverve/ai-sdk ai zod

Works with AI SDK 5, 6 and 7, on Node 18 or later.

The shortest working example

import { generateText, isStepCount } from 'ai';
import { apiverveTools } from '@apiverve/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt: 'Is jane@gmial.com a deliverable address, and where is 8.8.8.8?',
  tools: apiverveTools(),
  stopWhen: isStepCount(5),
});

console.log(text);

The tools read APIVERVE_API_KEY from the environment:

bash

export APIVERVE_API_KEY="apv_..."

To use a different key, pass it to the tool instead: apiverveTools({ apiKey }). See security for where credentials should live.

The tools

Tool	What it does
`validateEmail`	Syntax, MX and SMTP checks; flags disposable, free and role addresses
`validatePhoneNumber`	Formats, country, carrier and line type
`lookupIpAddress`	Location, timezone and network of an IPv4 or IPv6 address
`lookupDnsRecords`	A, AAAA, MX, TXT, NS, CNAME and other records
`checkSslCertificate`	Issuer, validity dates and days until expiry
`getExchangeRate`	Latest or historical rate between two currencies
`findApis`	Searches the catalog and returns API ids and parameters. Free, and needs no key
`runApi`	Calls any catalog API by id with its parameters

Each tool's result is the data object of the API's normal response, so it has the same fields as the API reference.

Reaching the whole catalog

findApis and runApi are how a model gets past the six named tools. It searches for what it needs, reads the parameter names from the result, then calls the API:

import { findApis, runApi } from '@apiverve/ai-sdk';

const { text } = await generateText({
  model: 'openai/gpt-5-mini',
  prompt: 'Decode VIN 1HGCM82633A004352 and tell me the make and model year.',
  tools: { findApis: findApis(), runApi: runApi() },
  stopWhen: isStepCount(5),
});

This keeps the tool list short. Every tool definition is sent to the model on every turn, so two general tools cost far less context than hundreds of specific ones, and the model picks correctly more often.

Picking tools

Pass only the tools the task needs:

import { validateEmail, checkSslCertificate } from '@apiverve/ai-sdk';

const tools = {
  validateEmail: validateEmail(),
  checkSslCertificate: checkSslCertificate(),
};

Errors and credits

Each tool call is one API request and uses that API's credits. findApis uses none. A failed call throws an ApiverveError with a readable message, which the AI SDK hands back to the model as the tool result:

An invalid key: APIVerve rejected the API key.
A key that can't make this call (scoping or IP rules): a 403 message.
Out of credits or rate-limited: a 429 message.

The key is sent only to api.apiverve.com, redirects are refused, and the key is removed from any error text before the model sees it.

Source: github.com/apiverve/ai-sdk.