AgentLine Numbers API
The Numbers API from AgentLine — 5 operation(s) for numbers.
The Numbers API from AgentLine — 5 operation(s) for numbers.
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/agentline-cloud:agentline-cloud-numbers-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. 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:
title: Agentline Cloud Numbers API
version: 0.3.0
x-refined-note:
- x-guidance differs across the merged source definitions and was not carried
description: 'Operations tagged Numbers across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
description: Production
tags:
- name: Numbers
paths:
/v1/numbers:
get:
tags:
- Numbers
summary: List Numbers
description: 'List all phone numbers provisioned on your account.
Returns every phone number you''ve bought for your AI agents,
including which agent each number is assigned to, the number''s
status (active/released), and country.'
operationId: list_phone_numbers
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
security:
- API Key or OAuth: []
x-fern-sdk-group-name:
- numbers
x-fern-sdk-method-name: list
post:
tags:
- Numbers
summary: Provision
description: 'Buy a US or Canadian phone number for your AI agent.
Buys a real +1 number from the carrier, attaches it to the agent and
uses an included subscription number, or charges $3.00 to the wallet. Once attached, the agent can make
outbound calls and answers inbound calls on this number. Not idempotent:
every successful call buys and charges for another number.
Prerequisites: an agent from create_agent with no active number (each
agent has at most one; a second purchase returns HTTP 409), plus a remaining
subscription number allowance or $3.00 in the wallet
(HTTP 402 otherwise; see get_account_balance).
Returns the number''s id (num_..., used by release_phone_number and as
from_number_id), phone_number, country, number_type, status, cost,
balance_remaining and a private number card link (card_url,
card_image_url, card_url_expires_at). If the account has an owner email,
the card link is also emailed there.'
operationId: buy_phone_number
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NumberProvision'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- API Key or OAuth: []
x-fern-sdk-group-name:
- numbers
x-fern-sdk-method-name: buy
servers:
- url: https://api.agentline.cloud
description: Production
/v1/numbers/{number_id}:
get:
tags:
- Numbers
summary: Get Number
description: 'Get details of a specific phone number.
Returns the phone number, its assigned AI agent, provider ID,
country, and current status.'
operationId: get_phone_number
security:
- API Key or OAuth: []
parameters:
- name: number_id
in: path
required: true
schema:
type: string
title: Number Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-fern-sdk-group-name:
- numbers
x-fern-sdk-method-name: get
servers:
- url: https://api.agentline.cloud
description: Production
/v1/numbers/{number_id}/reassign:
patch:
tags:
- Numbers
summary: Reassign Number
description: 'Reassign a phone number to a different AI agent.
Moves an existing phone number from one AI agent to another.
The target agent must not already have an active number assigned.
The phone number remains active — only the agent ownership changes.'
operationId: reassign_number
security:
- API Key or OAuth: []
parameters:
- name: number_id
in: path
required: true
schema:
type: string
title: Number Id
- name: agent_id
in: query
required: true
schema:
type: string
title: Agent Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-fern-sdk-group-name:
- numbers
x-fern-sdk-method-name: reassign
servers:
- url: https://api.agentline.cloud
description: Production
/v1/numbers/{number_id}/release:
post:
tags:
- Numbers
summary: Release Phone Number
description: 'Permanently release a phone number that is not in use.
Destructive: unrents the number from the carrier. The number cannot be recovered, and calls and texts to it will stop. Refused while a call is in progress or a lease is still active.'
operationId: release_phone_number
security:
- API Key or OAuth: []
parameters:
- name: number_id
in: path
required: true
schema:
type: string
title: Number Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
x-fern-sdk-group-name:
- numbers
x-fern-sdk-method-name: release
servers:
- url: https://api.agentline.cloud
description: Production
/v1/numbers/attach:
post:
tags:
- Numbers
summary: Attach Existing Number
description: 'Manually attach a number that was bought outside this account.
Each agent can only have ONE active number.
Query params:
- phone_number: E.164 format (e.g. "+12125551234")
- agent_id: agent to attach to
- country: "US" (default) or "CA" — both are +1, so say which'
operationId: attach_existing_number
security:
- API Key or OAuth: []
parameters:
- name: phone_number
in: query
required: true
schema:
type: string
title: Phone Number
- name: agent_id
in: query
required: true
schema:
type: string
title: Agent Id
- name: country
in: query
required: false
schema:
type: string
default: US
title: Country
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
servers:
- url: https://api.agentline.cloud
components:
schemas:
NumberProvision:
properties:
agent_id:
type: string
title: Agent Id
description: ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')
country:
type: string
title: Country
description: Country code for the phone number ('US' or 'CA')
default: US
number_type:
type: string
title: Number Type
description: 'Type of phone number: ''local'' or ''tollfree'''
default: local
area_code:
anyOf:
- type: string
- type: 'null'
title: Area Code
description: Preferred 3-digit US area code (e.g. '212' for NYC, '415' for SF, '310' for LA)
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
description: Legacy digit pattern match (prefer area_code instead)
type: object
required:
- agent_id
title: NumberProvision
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
NumberProvision_2:
properties:
agent_id:
type: string
title: Agent Id
description: ID of the AI agent to assign this phone number to (e.g. 'agt_abc123')
country:
type: string
title: Country
description: Country code for the phone number ('US' or 'CA')
default: US
number_type:
type: string
title: Number Type
description: '''local'' for a number in a geographic area code, or ''tollfree'' for a toll-free 8xx number'
default: local
area_code:
anyOf:
- type: string
- type: 'null'
title: Area Code
description: For local numbers, the area code the number should be in, written as 3 digits (US e.g. '212' NYC, '415' SF; Canada e.g. '416' Toronto, '604' Vancouver, '514' Montreal); other values make the purchase fail. For tollfree, a prefix such as '800' or '888' narrows the search and other values are ignored. Omit to take any available number.
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
description: 'Legacy search: digits the local number must contain, e.g. ''555''. Used only for local numbers when area_code is omitted; prefer area_code.'
type: object
required:
- agent_id
title: NumberProvision
securitySchemes:
API_Key_or_OAuth:
type: http
description: 'AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).'
scheme: bearer
bearerFormat: API key (al_live_...)
x-fern-bearer:
name: apiKey
env: AGENTLINE_API_KEY
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json