Kataven Hub API — telephony endpoints

Carrier credentials and phone-number management. Wrapped by the Python SDK and Node SDK.

Endpoints at a glance

Method	Path	Summary
`GET`	`/api/v1/telephony/numbers`	List phone numbers
`POST`	`/api/v1/telephony/numbers`	Register a phone number
`PATCH`	`/api/v1/telephony/numbers/{id}`	Pin or unpin a phone number to an agent
`DELETE`	`/api/v1/telephony/numbers/{id}`	Delete a phone number
`GET`	`/api/v1/telephony/providers`	List telephony provider credentials
`POST`	`/api/v1/telephony/providers`	Add a telephony provider credential
`DELETE`	`/api/v1/telephony/providers/{id}`	Delete a telephony provider credential

Reference

`GET /api/v1/telephony/numbers`

List phone numbers Parameters

Name	In	Type	Required	Description
`agent_id`	query	`string`	No	Filter by agent id

Responses

Code	Description	Body
`200`	OK	`object`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/telephony/numbers \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`POST /api/v1/telephony/numbers`

Register a phone number Binds an E.164 number to a carrier credential row and (optionally) pins it to one agent. Inbound + outbound default to enabled. Request body (application/json) Schema: handlers.CreateNumberRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.

Field	Type	Description
`agent_id`	`string`	e.g. `agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`
`credentials_id`	`string`	e.g. `prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`
`e164`	`string`	e.g. `+12025550123`
`inbound_enabled`	`boolean`	e.g. `True`
`outbound_enabled`	`boolean`	e.g. `True`
`provider`	`string`	e.g. `twilio`

Responses

Code	Description	Body
`201`	Created	`object`
`400`	Invalid body or duplicate number	`string`

Example

curl https://api.kataven.ai/v1/telephony/numbers \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "credentials_id": "prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "e164": "+12025550123",
  "inbound_enabled": true,
  "outbound_enabled": true,
  "provider": "twilio"
}'

`PATCH /api/v1/telephony/numbers/{id}`

Pin or unpin a phone number to an agent Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Phone number id (uuid)

Request body (application/json) Schema: handlers.UpdateNumberRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.

Field	Type	Description
`agent_id`	`string`	e.g. `agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`

Responses

Code	Description	Body
`204`	Updated	—
`404`	Phone number not found	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/telephony/numbers/agent_01HZ2N... \
  -X PATCH \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z"
}'

`DELETE /api/v1/telephony/numbers/{id}`

Delete a phone number Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Phone number id (uuid)

Responses

Code	Description	Body
`204`	Deleted	—
`404`	Phone number not found	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/telephony/numbers/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`GET /api/v1/telephony/providers`

List telephony provider credentials Returns metadata about every carrier credential configured for this account. Plaintext credentials are not returned. Responses

Code	Description	Body
`200`	OK	`object`
`400`	Missing X-Account-ID header	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/telephony/providers \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`POST /api/v1/telephony/providers`

Add a telephony provider credential Encrypts the credentials JSON via the Secret Encryptor service, then inserts the row. Plaintext is never persisted. Request body (application/json) Schema: handlers.CreateProviderRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.

Field	Type	Description
`credentials`	`object`
`label`	`string`	e.g. `Production Twilio`
`provider`	`string`	e.g. `twilio`

Responses

Code	Description	Body
`201`	Created	`object`
`400`	Invalid body or missing field	`string`
`500`	Database error	`string`
`503`	Encryption service unavailable	`string`

Example

curl https://api.kataven.ai/v1/telephony/providers \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Production Twilio",
  "provider": "twilio"
}'

`DELETE /api/v1/telephony/providers/{id}`

Delete a telephony provider credential Refuses if any phone-number row still references this credential — detach numbers first. Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Credential id (uuid)

Responses

Code	Description	Body
`204`	Deleted	—
`404`	Credential not found	`string`
`409`	Credential in use by phone numbers	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/telephony/providers/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

Get started

Resources

Kataven Hub API — telephony endpoints

Endpoints at a glance

Reference

`GET /api/v1/telephony/numbers`

`POST /api/v1/telephony/numbers`

`PATCH /api/v1/telephony/numbers/{id}`

`DELETE /api/v1/telephony/numbers/{id}`

`GET /api/v1/telephony/providers`

`POST /api/v1/telephony/providers`

`DELETE /api/v1/telephony/providers/{id}`

​Endpoints at a glance

​Reference

​GET /api/v1/telephony/numbers

​POST /api/v1/telephony/numbers

​PATCH /api/v1/telephony/numbers/{id}

​DELETE /api/v1/telephony/numbers/{id}

​GET /api/v1/telephony/providers

​POST /api/v1/telephony/providers

​DELETE /api/v1/telephony/providers/{id}

Endpoints at a glance

Reference

`GET /api/v1/telephony/numbers`

`POST /api/v1/telephony/numbers`

`PATCH /api/v1/telephony/numbers/{id}`

`DELETE /api/v1/telephony/numbers/{id}`

`GET /api/v1/telephony/providers`

`POST /api/v1/telephony/providers`

`DELETE /api/v1/telephony/providers/{id}`