How Sapiom Works

Sapiom is a gateway that sits between your AI agents and paid third-party services. It handles authentication, payment, and governance so you can call any supported API with a single key.

Architecture

  Your Agent                  Sapiom                     Service Provider
 ┌──────────┐           ┌──────────────┐            ┌──────────────────┐
 │          │  request   │              │  proxied   │  Linkup, OpenAI, │
 │  Code +  ├──────────►│   Gateway    ├───────────►│  ElevenLabs, ... │
 │  Sapiom  │           │              │            │                  │
 │  SDK     │◄──────────┤  • Auth      │◄───────────┤                  │
 │          │  response  │  • Payment   │  response  │                  │
 └──────────┘           │  • Rules     │            └──────────────────┘
                        │  • Tracking  │
                        └──────────────┘

1. Your code makes a normal HTTP request through the Sapiom SDK
2. The gateway authenticates the request, checks governance rules, and handles payment
3. The request is forwarded to the service provider
4. The response comes back through the gateway, which logs the transaction

You never need credentials for the underlying service — just your Sapiom API key.

Capabilities

Capabilities are the paid services available through Sapiom. Each capability maps to a third-party provider and is accessed at a *.services.sapiom.ai URL:

Capability	Providers	What it does
Verify Users	Prelude	Phone and email verification
Search the Web	Linkup, You.com	AI-powered web search with live crawling
AI Model Access	OpenRouter	400+ models (GPT-4, Claude, Llama, etc.)
Generate Images	Fal.ai	FLUX and SDXL image generation
Audio Services	ElevenLabs	Text-to-speech, transcription, sound effects
Browser Automation	Anchor Browser	Web scraping, screenshots, AI browser tasks

Each provider’s API is available at its own subdomain. For example, Linkup search lives at https://linkup.services.sapiom.ai/v1/search.

The Payment Flow

Sapiom uses the HTTP 402 Payment Required status code to handle payments inline. The SDK manages this automatically — here’s what happens under the hood:

  Your Code              SDK                Gateway            Provider
     │                    │                    │                   │
     │  client.get(url)   │                    │                   │
     ├───────────────────►│  POST with payment │                   │
     │                    ├───────────────────►│                   │
     │                    │                    │  Forward request  │
     │                    │                    ├──────────────────►│
     │                    │                    │◄──────────────────┤
     │                    │◄───────────────────┤                   │
     │◄───────────────────┤  Response data     │                   │
     │                    │                    │                   │

The SDK wraps your HTTP client (axios, fetch, etc.) and attaches payment headers to every request. You write normal HTTP code — the payment negotiation is invisible.

import axios from "axios";
import { withSapiom } from "@sapiom/axios";

// Wrap your client once
const client = withSapiom(axios.create(), {
  apiKey: process.env.SAPIOM_API_KEY!,
});

// Then make requests as usual — payment is handled automatically
const { data } = await client.get(
  "https://linkup.services.sapiom.ai/v1/search",
  { params: { q: "latest AI news", depth: "standard" } }
);

Note

Each billable request creates a transaction — a record of the API call, its cost, and its status (pending, authorized, completed, or denied). You can view all transactions in the Dashboard.

Agents

An agent is an identity for your AI application in Sapiom. When you create an API key in the Dashboard, it’s associated with an agent. Agents let you:

• Track usage per application — see which app is calling which services
• Set spend limits — cap costs per agent on a per-run, daily, weekly, or monthly basis
• Enforce rules — apply different governance policies to different apps

A single Sapiom account can have multiple agents. For example, you might have one agent for your production chatbot and another for internal tooling — each with its own limits and usage history.

Governance

Governance is how you control what your agents can do. Sapiom provides two types of rules:

• Spend limits — Cap how much an agent can spend per run, day, week, or month
• Usage limits — Restrict the number of API calls or tokens an agent can consume

Rules are optional. You can start without any and add them as you move toward production. See Setting Up Rules for details.

Activity

Sapiom logs every request as a transaction. The Dashboard gives you a real-time view of:

• Request and response details for every API call
• Cost breakdown per service and per agent
• Rule enforcement — which requests were allowed or blocked
• Execution traces showing the full lifecycle of each call

---

Next Steps

Quick Start Call a paid API in 3 steps.

Browse Capabilities See all available services and their APIs.

Set Up Governance Add spend limits and usage rules.

Integration Guide Axios, Fetch, LangChain, and more.