Install Jentic One Beta
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Saperly API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fsaperly.com%2Fsaperly" | shStep 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fsaperly.com%2Fsaperly" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
What an agent can do with Saperly API.
Provision a phone number by country, numberType such as local or toll_free, and areaCode, after quoting its price
Create a hosted or manual connection with its own instructions and bind it to a number to answer calls and SMS
Place an outbound call from a Saperly number with per-call instructions, then end it or blind-transfer it to a number or sip: URI
Send an SMS of up to 1600 characters from one of your numbers, checked against the recipient's opt-out status
GET STARTED
Fetch a call's transcript or a redirect to its recording after the call
Record, check, and revoke consent per contact with consentType implied_inbound or explicit_outbound
Mint child API keys limited by scopes, a numberScope allow-list, and spendLimitCents
Patterns agents use Saperly API for, with concrete tasks.
★ AI agent making outbound calls
An agent asked to confirm appointments searches Jentic for 'place a phone call', loads the voice.place operation, and calls each customer from a Saperly number with a per-call instructions prompt describing what to confirm. After the call it reads the transcript to record the outcome, and the Saperly key is injected at call time rather than handed to the agent.
POST /calls with fromNumberId num_123, to +14155550123, and instructions 'Confirm the 3pm appointment tomorrow', then GET /calls/{id}/transcript once the call ends
Giving an assistant its own phone line
A team that wants an AI receptionist provisions a number with the country, numberType, and areaCode they need, creates a hosted connection whose instructions describe the assistant's behaviour, and binds the connection to the number. Inbound calls and messages on that line are then answered by the connection, and a manual connection hands each turn to your own LLM instead.
GET /pricing/quote with country US and numberType local, POST /numbers with country US and areaCode 415, POST /connections with name 'Front desk' and mode hosted, then POST /numbers/{id}/connection with the new connectionId
Consent-aware SMS outreach
Texting a contact responsibly starts with knowing they agreed to it. The consent check operation takes numberId and peerNumber and reports whether active consent exists, consent records store consentType and a source note for the audit trail, and SMS sends are checked against the recipient's STOP status before leaving the network.
GET /consent/check with numberId num_123 and peerNumber +14155550123, and only if consent is active POST /messages with fromNumberId num_123, to +14155550123, and body 'Your order has shipped.'
Delivery debugging for webhooks
Saperly POSTs subscribed events such as call.completed and message.received to workspace webhook endpoints, each signed in the x-saperly-signature header. When events stop arriving, the deliveries operation lists recent attempts with outcome, responseStatus, and attempt number so the failing receiver is easy to spot.
GET /workspaces/{slug}/webhooks/{webhookId}/deliveries for workspace acme and report any failed attempts with their responseStatus
48 endpoints — the saperly api gives an ai agent its own phone line: it provisions phone numbers, binds them to connections that answer calls and messages, places and transfers outbound calls, and sends sms.
METHOD
PATH
DESCRIPTION
/numbers
Provision a phone number
/connections
Create a hosted or manual connection
/numbers/{id}/connection
Bind a connection to a number
/calls
Place an outbound call
/calls/{id}/transcript
Get a call transcript
/messages
Send an SMS message
/consent/check
Check a contact's consent
/api-tokens
Mint a scoped API key
/numbers
Provision a phone number
/connections
Create a hosted or manual connection
/numbers/{id}/connection
Bind a connection to a number
/calls
Place an outbound call
/calls/{id}/transcript
Get a call transcript
/messages
Send an SMS message
/consent/check
Check a contact's consent
/api-tokens
Mint a scoped API key
What agents get from Jentic-routed access to this vendor.
Setup
Wiring Saperly by hand means working out how to present an sk_ key that the spec never declares, chaining number quotes, provisioning, and connection binding, and verifying HMAC-signed webhooks. Through Jentic you install once, import Saperly from the API Directory, store the key once, and your agent calls it.
Permission scoping
Saperly carries the sending number inside the request body (fromNumberId on calls and messages), so a Jentic rule bounds which operations your agent may call, such as placing calls and reading transcripts, not which number it uses; pair it with a Saperly child key whose numberScope limits the numbers. You choose the operations it may call, so destructive ones like number release or connection deletion are not included unless you add them.
Credential isolation
Your Saperly key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'place a phone call' or 'send an SMS', and Jentic returns the matching Saperly operation, such as voice.place or messaging.send, with its input schema.
Alternatives and complements available in the Jentic catalogue.
Specific to using Saperly API through Jentic.
What authentication does the Saperly API use?
The Saperly OpenAPI spec does not declare a security scheme. Its description says the agent data plane resolves your organization from an sk_ API key, and that a key with keys:admin can mint child keys bounded by its own ceiling. Check the Saperly docs at https://saperly.com for how to send the key. Through Jentic the key is stored by your own instance and attached at call time.
Can I limit what a Saperly API key can do?
Yes, on Saperly's side. The mint key operation accepts scopes of read, write, or admin, a numberScope allow-list of phone numbers, and a spendLimitCents cap with an optional monthly reset, each within the minting key's own ceiling. The plaintext key is returned once, in the response to that call.
What is the difference between hosted and manual connections?
In hosted mode an in-network voice assistant answers the line using the connection's instructions. In manual mode your own LLM is the brain: Saperly forwards text turns and executes the directives you return. Audio stays in Saperly's network in both modes.
What are the rate limits for the Saperly API?
The OpenAPI spec does not specify rate limits. Check the Saperly documentation at https://saperly.com for current limits.
Is there a Saperly MCP server?
Yes. The Saperly spec describes a separate JSON-RPC MCP surface at /mcp. You can also connect the API directly through Jentic: your agent gets the full 48-endpoint surface from the spec without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.
How do I place a call with Saperly through Jentic?
Search Jentic for 'place a phone call', load the voice.place operation, and execute POST /calls with fromNumberId and a to number in E.164 format, adding instructions to steer that call. To run it on your own infrastructure, install Jentic One from its GitHub repo.
Can I limit what my agent is allowed to do with the Saperly API?
Yes. Allow POST /calls, GET /calls/{id}/transcript, and GET /consent/check, and the agent can phone customers and read the results, while number release, connection deletion, and key minting stay off its list. Every call it makes is logged.
For Agents
Provision phone numbers, place and transfer AI voice calls, send SMS, and read call transcripts and recordings, with consent tracking and scoped keys bounded by number and spend.
Use for: Provision a local US number in the 415 area code, Call +14155550123 and ask whether they want to reschedule their appointment, Send an SMS reminder from our support number, Get the transcript of yesterday's call with the customer
Not supported: Does not handle email, video meetings, or contact management. Use for AI phone numbers, calls, SMS, and consent records only.
The Saperly API gives an AI agent its own phone line: it provisions phone numbers, binds them to connections that answer calls and messages, places and transfers outbound calls, and sends SMS. A connection runs in hosted mode, where an in-network voice assistant follows your instructions, or manual mode, where your own LLM receives each conversation turn. Calls expose recordings and transcripts, and the API also covers consent records, voices and custom voice samples, number price quotes, usage summaries, outbound webhooks signed with HMAC-SHA256, and scoped API keys with number allow-lists and spend caps.
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
Base layer of spec validity and structural soundness.
Aggregated quality score from linter diagnostics, weighted by severity.
Percentage of `$ref` references that resolve successfully.
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
Structural correctness score based on schema issues using logarithmic dampening.
Clarity, completeness, and ingestion readiness for developers and tooling.
How richly the API is illustrated with examples.
Percentage of examples that conform to their schemas.
Percentage of operations with complete response definitions (success, client error, server error).
Health of API ingestion, bundling, and resolution within Jentic pipelines.
Semantic breadth, depth, and agent comprehension for AI systems.
Coverage of descriptions across API elements.
Coverage of RFC 9457 Problem Details for error responses.
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
Coverage of summaries across operations/tags/info.
Functional utility, complexity comfort, and AI orchestration readiness.
Agent comfort level based on API operational and structural complexity.
Trust, risk posture, and security compliance.
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
Findability, semantic richness, and reasoning readiness.
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>