Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/telnyx:telnyx-bot-signup-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 2.0.0
x-latency-category: responsive
x-endpoint-cost: light
title: Telnyx Bot Signup API
description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services.
contact:
email: support@telnyx.com
servers:
- url: https://api.telnyx.com/v2
description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Bot Signup
description: Agentic (bot) signup for Telnyx accounts. An AI agent solves a reverse-CAPTCHA challenge designed to be easy for LLMs and hard for humans, registers an account, and signs in by consuming a magic link emailed to the account owner. All endpoints are public and unauthenticated; signup endpoints are additionally gated by the freemium feature flags and per-country availability.
paths:
/v2/bot_challenge:
post:
summary: Issue a bot challenge
description: Generates a reverse-CAPTCHA challenge used to gate the bot signup flow. A random active problem is selected from the pool; math problems are returned obfuscated (case randomization, symbol injection, spacing noise) with an unobfuscated rounding instruction appended, while string and binary problems are returned as-is. The response contains a single-use nonce, the problem text, and the current terms-and-conditions and privacy-policy URLs, which must be echoed back on the signup request. Challenges expire after a short window (10 minutes by default) and can only be answered once. This endpoint is public and unauthenticated.
operationId: createBotChallenge
x-latency-category: responsive
tags:
- Bot Signup
x-endpoint-cost: light
security: []
requestBody:
required: false
description: Optional self-reported metadata about the LLM solving the challenge. Used for analytics only; it does not influence which problem is served.
content:
application/json:
schema:
$ref: '#/components/schemas/BotChallengeRequest'
example:
llm_model_name: claude-opus-4
llm_parameter_count: 175B
llm_quantization: int8
responses:
'201':
description: Challenge issued.
content:
application/json:
schema:
$ref: '#/components/schemas/BotChallengeResponse'
example:
data:
nonce: c6feda4e-6501-4db9-a21f-665e5b4ce2ba
problem: W#hAt iS f!Ve tImEs sEvEn? Round to 0 decimal places. Omit units.
challenge_type: math
precision: 0
terms_and_conditions_url: https://telnyx.com/terms-and-conditions-of-service
privacy_policy_url: https://telnyx.com/privacy-policy
'400':
description: The JSON request body could not be parsed.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: There was a problem in the JSON you submitted. Please check your formatting and try again.
'503':
description: No bot challenge problems are currently available.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: No bot challenge problems available
/v2/bot_sessions:
get:
summary: Exchange a magic link token for a session
description: Consumes the one-time portal redirect (magic link) token emailed during bot signup and returns an API session. The token is a UUIDv7 that encodes its creation time; it expires after a configurable validity window (15 minutes by default) and is cleared on first use. Although the action creates a session, the route uses the GET verb because it is opened from an email link. On first use the account is also initialized. For bot signup (freemium) accounts the response is a minimal envelope containing only the `api_v2_token`; accounts that are permitted to use magic links but are not freemium accounts may instead receive an extended session payload when additional steps (such as two-factor authentication or identity verification) are required. This endpoint is public; the magic link token in the query string is the credential.
operationId: createBotSession
x-latency-category: responsive
tags:
- Bot Signup
x-endpoint-cost: medium
security: []
parameters:
- name: email
in: query
required: true
description: Email address associated with the magic link token.
schema:
type: string
format: email
example: agent-owner@example.com
- name: portal_redirect_token
in: query
required: true
description: Single-use portal redirect (magic link) token, a UUIDv7 sent to the account owner's email.
schema:
type: string
format: uuid
example: 01890a7e-e2f7-7c3d-8dbb-9a2c5f3d1e0b
responses:
'200':
description: Session created. Bot signup accounts receive a minimal token envelope.
content:
application/json:
schema:
$ref: '#/components/schemas/BotSessionResponse'
example:
data:
api_v2_token: KEY0189A1B2C3D4E5F6071829AB3C4D5E_5FhZonmFvcw8Yq0dME27Bg
'400':
description: The account could not be initialized.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Account could not be initialized
'401':
description: Missing or invalid email or token, expired token, or the account is not eligible to sign in (inactive, suspended, not permitted to use magic links, or must use SSO).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Your sign-in link has expired. Please request a new one-time sign-in link.
'403':
description: Request blocked by security policy (for example, the caller's country is not accepted).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Your registration cannot be accepted as it does not comply with our security standards. You may contact support for assistance.
'404':
description: Bot signup is not available (freemium master switch disabled or the caller's country is not enabled).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- code: '10005'
title: Resource not found
detail: The requested resource or URL could not be found.
source:
pointer: /
meta:
url: https://developers.telnyx.com/docs/overview/errors/10005
/v2/bot_signup:
post:
summary: Register via bot signup
description: Creates a freemium Telnyx account through the agentic signup flow. The request must carry a valid answer to a previously issued bot challenge (`bot_challenge_nonce` and `bot_challenge_answer`), accept the terms of service, and echo the exact terms-and-conditions and privacy-policy URLs returned by the challenge endpoint. When EU consent enforcement is enabled, `terms_of_service_eu` and `terms_and_conditions_eu_url` are also required. On success a one-time sign-in (magic) link is emailed to the address provided; if the email address belongs to an existing account, a sign-in link is sent instead of creating a duplicate account. `email` may only be omitted when placeholder-email registration is enabled server-side. This endpoint is public and unauthenticated, gated by the freemium feature flags and per-country availability, and subject to per-IP and per-domain registration limits.
operationId: createBotSignup
x-latency-category: responsive
tags:
- Bot Signup
x-endpoint-cost: medium
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BotSignupRequest'
example:
email: agent-owner@example.com
terms_of_service: true
terms_and_conditions_url: https://telnyx.com/terms-and-conditions-of-service
privacy_policy_url: https://telnyx.com/privacy-policy
bot_challenge_nonce: c6feda4e-6501-4db9-a21f-665e5b4ce2ba
bot_challenge_answer: '35'
responses:
'200':
description: Registration accepted and a magic link emailed.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
success: true
message: A one-time sign-in link has been sent to your email address.
'400':
description: Bot challenge parameters missing or verification failed, terms of service not accepted, or terms/privacy URLs missing or not matching the expected values.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Bot challenge parameters are required
'403':
description: Registration blocked by security policy (for example, registration from the caller's country is not accepted).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Your registration cannot be accepted as it does not comply with our security standards. You may contact support for assistance.
'404':
description: Bot signup is not available (freemium master switch disabled or the caller's country is not enabled).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- code: '10005'
title: Resource not found
detail: The requested resource or URL could not be found.
source:
pointer: /
meta:
url: https://developers.telnyx.com/docs/overview/errors/10005
'422':
description: Validation failed (for example an invalid email address), or the IP address has reached its bot signup limit.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- code: '10027'
title: Unprocessable Entity
detail: Email is invalid
source:
pointer: /email
meta:
url: https://developers.telnyx.com/docs/overview/errors/10027
'429':
description: Too many registrations from this email domain.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- code: '10011'
title: Too many requests
detail: You have exceeded the maximum number of allowed requests.
source:
pointer: /
meta:
url: https://developers.telnyx.com/docs/overview/errors/10011
/v2/bot_signup/resend_magic_link:
post:
summary: Resend a bot signup magic link
description: Resends the one-time sign-in (magic) link for an eligible bot signup account. Eligibility (account exists, was registered through bot signup, is active, and has not exceeded the resend limit or rate window) is evaluated server-side; the response is intentionally uniform and does not reveal whether the account exists or whether a link was actually sent. This endpoint is public and unauthenticated, gated by the freemium feature flags and per-country availability.
operationId: resendBotSignupMagicLink
x-latency-category: responsive
tags:
- Bot Signup
x-endpoint-cost: light
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResendMagicLinkRequest'
example:
email: agent-owner@example.com
responses:
'200':
description: Uniform acknowledgement, returned whether or not a link was sent.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
success: true
message: A one-time sign-in link has been sent to your email address.
'400':
description: The JSON request body could not be parsed.
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: There was a problem in the JSON you submitted. Please check your formatting and try again.
'403':
description: Request blocked by security policy (for example, the caller's country is not accepted).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- detail: Your registration cannot be accepted as it does not comply with our security standards. You may contact support for assistance.
'404':
description: Bot signup is not available (freemium master switch disabled or the caller's country is not enabled).
content:
application/json:
schema:
$ref: '#/components/schemas/bot-signup_ErrorResponse'
example:
errors:
- code: '10005'
title: Resource not found
detail: The requested resource or URL could not be found.
source:
pointer: /
meta:
url: https://developers.telnyx.com/docs/overview/errors/10005
components:
schemas:
ResendMagicLinkRequest:
type: object
properties:
email:
type: string
format: email
description: Email address of the bot signup account to resend the magic link to.
example: agent-owner@example.com
required:
- email
BotSignupRequest:
type: object
properties:
email:
type: string
format: email
description: Email address for the new account. The magic link is sent here. May only be omitted when placeholder-email registration is enabled server-side.
example: agent-owner@example.com
terms_of_service:
type: boolean
enum:
- true
description: Must be true to accept the terms of service.
example: true
terms_and_conditions_url:
type: string
description: Must exactly match the terms-and-conditions URL returned by the challenge endpoint.
example: https://telnyx.com/terms-and-conditions-of-service
privacy_policy_url:
type: string
description: Must exactly match the privacy-policy URL returned by the challenge endpoint.
example: https://telnyx.com/privacy-policy
terms_of_service_eu:
type: boolean
enum:
- true
description: EU terms-of-service acceptance. Required when EU consent enforcement is enabled.
example: true
terms_and_conditions_eu_url:
type: string
description: EU terms-and-conditions URL. Required when EU consent enforcement is enabled.
example: https://telnyx.com/terms-and-conditions-of-service-eu
bot_challenge_nonce:
type: string
format: uuid
description: Nonce from a previously issued bot challenge.
example: c6feda4e-6501-4db9-a21f-665e5b4ce2ba
bot_challenge_answer:
type: string
description: Answer to the issued bot challenge.
example: '35'
required:
- terms_of_service
- terms_and_conditions_url
- privacy_policy_url
- bot_challenge_nonce
- bot_challenge_answer
bot-signup_ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/bot-signup_Error'
required:
- errors
SuccessResponse:
type: object
description: Status envelope used by the signup and magic-link flows.
required:
- success
- message
properties:
success:
type: boolean
description: Whether the request was accepted.
example: true
message:
type: string
description: Human-readable status message.
example: A one-time sign-in link has been sent to your email address.
bot-signup_Error:
type: object
description: API error. General errors carry only `detail`; structured errors also include `code`, `title`, `source`, and `meta`.
properties:
code:
type: string
description: Machine-readable Telnyx error code.
example: '10005'
title:
type: string
description: Short human-readable summary.
example: Resource not found
detail:
type: string
description: Human-readable explanation of the error.
example: The requested resource or URL could not be found.
source:
type: object
properties:
pointer:
type: string
description: JSON pointer to the offending attribute.
example: /
meta:
type: object
properties:
url:
type: string
description: Link to the error documentation.
example: https://developers.telnyx.com/docs/overview/errors/10005
required:
- detail
BotSessionResponse:
type: object
required:
- data
properties:
data:
type: object
required:
- api_v2_token
properties:
api_v2_token:
type: string
description: API v2 session token for the signed-in user. Use it as a bearer token on authenticated endpoints.
example: KEY0189A1B2C3D4E5F6071829AB3C4D5E_5FhZonmFvcw8Yq0dME27Bg
BotChallengeRequest:
type: object
description: Optional self-reported metadata about the LLM solving the challenge. Analytics only; values are truncated to 50 characters.
properties:
llm_model_name:
type: string
description: Name of the LLM the client is using.
example: claude-opus-4
llm_parameter_count:
type: string
description: Parameter count of the client LLM.
example: 175B
llm_quantization:
type: string
description: Quantization of the client LLM.
example: int8
BotChallengeResponse:
type: object
required:
- data
properties:
data:
type: object
required:
- nonce
- problem
- challenge_type
- terms_and_conditions_url
- privacy_policy_url
properties:
nonce:
type: string
format: uuid
description: Single-use challenge identifier. Submit it as `bot_challenge_nonce` on the signup request.
example: c6feda4e-6501-4db9-a21f-665e5b4ce2ba
problem:
type: string
description: Problem text to solve. Math problems are obfuscated and end with an unobfuscated rounding instruction; string and binary problems are returned as-is.
example: W#hAt iS f!Ve tImEs sEvEn? Round to 0 decimal places. Omit units.
challenge_type:
type: string
description: Type of challenge.
enum:
- math
- string
- binary
example: math
precision:
type: integer
description: Decimal places expected in the answer. Present only for math challenges.
example: 0
terms_and_conditions_url:
type: string
description: Current terms-and-conditions URL. Echo this back on the signup request.
example: https://telnyx.com/terms-and-conditions-of-service
privacy_policy_url:
type: string
description: Current privacy-policy URL. Echo this back on the signup request.
example: https://telnyx.com/privacy-policy
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
Payment:
type: apiKey
in: header
name: Authorization
description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
agent-memory_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
bearerAuth:
type: http
scheme: bearer
branded-calling_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
collections_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
number-reputation_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
oauthClientAuth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
tokenUrl: https://api.telnyx.com/v2/oauth/token
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
outbound-voice-profiles_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
pronunciation-dicts_bearerAuth:
type: http
scheme: bearer
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
rcs-registration_bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
stored-payment-transactions_bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
transcriptions-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
web-search_bearerAuth:
type: http
scheme: bearer
description: Telnyx API key
x-service-info:
categories:
- communication
- developer-tools
docs:
apiReference: https://developers.telnyx.com
homepage: https://telnyx.com
llms: https://telnyx.com/llms.txt