asterisk/rest-api/api-docs/endpoints.json

{
	"_copyright": "Copyright (C) 2012 - 2013, Digium, Inc.",
	"_author": "David M. Lee, II <dlee@digium.com>",
	"_svn_revision": "$Revision$",
	"apiVersion": "2.0.0",
	"swaggerVersion": "1.1",
	"basePath": "http://localhost:8088/ari",
	"resourcePath": "/api-docs/endpoints.{format}",
	"since": [
		"12.0.0"
	],
	"apis": [
		{
			"path": "/endpoints",
			"description": "Asterisk endpoints",
			"operations": [
				{
					"httpMethod": "GET",
					"since": [
						"12.0.0"
					],
					"summary": "List all endpoints.",
					"nickname": "list",
					"responseClass": "List[Endpoint]"
				}
			]
		},
		{
			"path": "/endpoints/sendMessage",
			"description": "Send a message to some technology URI or endpoint.",
			"operations": [
				{
					"httpMethod": "PUT",
					"since": [
						"13.0.0"
					],
					"summary": "Send a message to some technology URI or endpoint.",
					"nickname": "sendMessage",
					"responseClass": "void",
					"parameters": [
						{
							"name": "to",
							"description": "The endpoint resource or technology specific URI to send the message to. Valid resources are sip, pjsip, and xmpp.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "from",
							"description": "The endpoint resource or technology specific identity to send this message from. Valid resources are sip, pjsip, and xmpp.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "body",
							"description": "The body of the message",
							"paramType": "query",
							"required": false,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "variables",
							"descriptioni": "The \"variables\" key in the body object holds technology specific key/value pairs to append to the message. These can be interpreted and used by the various resource types; for example, pjsip and sip resource types will add the key/value pairs as SIP headers,",
							"paramType": "body",
							"required": false,
							"dataType": "containers",
							"allowMultiple": false
						}
					],
					"errorResponses": [
						{
							"code": 400,
							"reason": "Invalid parameters for sending a message."
						},
						{
							"code": 404,
							"reason": "Endpoint not found"
						}
					]
				}
			]
		},
		{
			"path": "/endpoints/refer",
			"description": "Refer an endpoint or technology URI to some technology URI or endpoint.",
			"operations": [
				{
					"httpMethod": "POST",
					"since": [
						"18.20.0",
						"20.5.0"
					],
					"summary": "Refer an endpoint or technology URI to some technology URI or endpoint.",
					"nickname": "refer",
					"responseClass": "void",
					"parameters": [
						{
							"name": "to",
							"description": "The endpoint resource or technology specific URI that should be referred to somewhere. Valid resource is pjsip.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "from",
							"description": "The endpoint resource or technology specific identity to refer from.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "refer_to",
							"description": "The endpoint resource or technology specific URI to refer to.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "to_self",
							"description": "If true and \"refer_to\" refers to an Asterisk endpoint, the \"refer_to\" value is set to point to this Asterisk endpoint - so the referee is referred to Asterisk. Otherwise, use the contact URI associated with the endpoint.",
							"paramType": "query",
							"required": false,
							"allowMultiple": false,
							"dataType": "boolean",
							"defaultValue": false
						},
						{
							"name": "variables",
							"description": "The \"variables\" key in the body object holds technology specific key/value pairs to append to the message. These can be interpreted and used by the various resource types; for example, the pjsip resource type will add the key/value pairs as SIP headers. The \"display_name\" key is used by the PJSIP technology. Its value will be prepended as a display name to the Refer-To URI.",
							"paramType": "body",
							"required": false,
							"dataType": "containers",
							"allowMultiple": false
						}
					],
					"errorResponses": [
						{
							"code": 400,
							"reason": "Invalid parameters for referring."
						},
						{
							"code": 404,
							"reason": "Endpoint not found"
						}
					]
				}
			]
		},
		{
			"path": "/endpoints/{tech}",
			"description": "Asterisk endpoints",
			"operations": [
				{
					"httpMethod": "GET",
					"since": [
						"12.0.0"
					],
					"summary": "List available endoints for a given endpoint technology.",
					"nickname": "listByTech",
					"responseClass": "List[Endpoint]",
					"parameters": [
						{
							"name": "tech",
							"description": "Technology of the endpoints (sip,iax2,...)",
							"paramType": "path",
							"dataType": "string"
						}
					],
					"errorResponses": [
						{
							"code": 404,
							"reason": "Endpoints not found"
						}
					]
				}
			]
		},
		{
			"path": "/endpoints/{tech}/{resource}",
			"description": "Single endpoint",
			"operations": [
				{
					"httpMethod": "GET",
					"since": [
						"12.0.0"
					],
					"summary": "Details for an endpoint.",
					"nickname": "get",
					"responseClass": "Endpoint",
					"parameters": [
						{
							"name": "tech",
							"description": "Technology of the endpoint",
							"paramType": "path",
							"dataType": "string"
						},
						{
							"name": "resource",
							"description": "ID of the endpoint",
							"paramType": "path",
							"dataType": "string"
						}
					],
					"errorResponses": [
						{
							"code": 400,
							"reason": "Invalid parameters for sending a message."
						},
						{
							"code": 404,
							"reason": "Endpoints not found"
						}
					]
				}
			]
		},
		{
			"path": "/endpoints/{tech}/{resource}/sendMessage",
			"description": "Send a message to some endpoint in a technology.",
			"operations": [
				{
					"httpMethod": "PUT",
					"since": [
						"13.0.0"
					],
					"summary": "Send a message to some endpoint in a technology.",
					"nickname": "sendMessageToEndpoint",
					"responseClass": "void",
					"parameters": [
						{
							"name": "tech",
							"description": "Technology of the endpoint",
							"paramType": "path",
							"dataType": "string"
						},
						{
							"name": "resource",
							"description": "ID of the endpoint",
							"paramType": "path",
							"dataType": "string"
						},
						{
							"name": "from",
							"description": "The endpoint resource or technology specific identity to send this message from. Valid resources are sip, pjsip, and xmpp.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "body",
							"description": "The body of the message",
							"paramType": "query",
							"required": false,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "variables",
							"descriptioni": "The \"variables\" key in the body object holds technology specific key/value pairs to append to the message. These can be interpreted and used by the various resource types; for example, pjsip and sip resource types will add the key/value pairs as SIP headers,",
							"paramType": "body",
							"required": false,
							"dataType": "containers",
							"allowMultiple": false
						}
					],
					"errorResponses": [
						{
							"code": 400,
							"reason": "Invalid parameters for sending a message."
						},
						{
							"code": 404,
							"reason": "Endpoint not found"
						}
					]
				}
			]
		},
		{
			"path": "/endpoints/{tech}/{resource}/refer",
			"description": "Refer an endpoint in a technology to some technology URI or endpoint..",
			"operations": [
				{
					"httpMethod": "POST",
					"since": [
						"18.20.0",
						"20.5.0"
					],
					"summary": "Refer an endpoint or technology URI to some technology URI or endpoint.",
					"nickname": "referToEndpoint",
					"responseClass": "void",
					"parameters": [
						{
							"name": "tech",
							"description": "Technology of the endpoint",
							"paramType": "path",
							"dataType": "string"
						},
						{
							"name": "resource",
							"description": "ID of the endpoint",
							"paramType": "path",
							"dataType": "string"
						},
						{
							"name": "from",
							"description": "The endpoint resource or technology specific identity to refer from.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "refer_to",
							"description": "The endpoint resource or technology specific URI to refer to.",
							"paramType": "query",
							"required": true,
							"allowMultiple": false,
							"dataType": "string"
						},
						{
							"name": "to_self",
							"description": "If true and \"refer_to\" refers to an Asterisk endpoint, the \"refer_to\" value is set to point to this Asterisk endpoint - so the referee is referred to Asterisk. Otherwise, use the contact URI associated with the endpoint.",
							"paramType": "query",
							"required": false,
							"allowMultiple": false,
							"dataType": "boolean",
							"defaultValue": false
						},
						{
							"name": "variables",
							"description": "The \"variables\" key in the body object holds technology specific key/value pairs to append to the message. These can be interpreted and used by the various resource types; for example, the pjsip resource type will add the key/value pairs as SIP headers,",
							"paramType": "body",
							"required": false,
							"dataType": "containers",
							"allowMultiple": false
						}
					],
					"errorResponses": [
						{
							"code": 400,
							"reason": "Invalid parameters for referring."
						},
						{
							"code": 404,
							"reason": "Endpoint not found"
						}
					]
				}
			]
		}
	],
	"models": {
		"Endpoint": {
			"id": "Endpoint",
			"description": "An external device that may offer/accept calls to/from Asterisk.\n\nUnlike most resources, which have a single unique identifier, an endpoint is uniquely identified by the technology/resource pair.",
			"properties": {
				"technology": {
					"type": "string",
					"description": "Technology of the endpoint",
					"required": true
				},
				"resource": {
					"type": "string",
					"description": "Identifier of the endpoint, specific to the given technology.",
					"required": true
				},
				"state": {
					"type": "string",
					"description": "Endpoint's state",
					"required": false,
					"allowableValues": {
						"valueType": "LIST",
						"values": [
							"unknown",
							"offline",
							"online"
						]
					}
				},
				"channel_ids": {
					"type": "List[string]",
					"description": "Id's of channels associated with this endpoint",
					"required": true
				}
			}
		},
		"TextMessage": {
			"id": "TextMessage",
			"description": "A text message.",
			"properties": {
				"from": {
					"type": "string",
					"description": "A technology specific URI specifying the source of the message. For sip and pjsip technologies, any SIP URI can be specified. For xmpp, the URI must correspond to the client connection being used to send the message.",
					"required": true
				},
				"to": {
					"type": "string",
					"description": "A technology specific URI specifying the destination of the message. Valid technologies include sip, pjsip, and xmp. The destination of a message should be an endpoint.",
					"required": true
				},
				"body": {
					"type": "string",
					"description": "The text of the message.",
					"required": true
				},
				"variables": {
					"type": "object",
					"description": "Technology specific key/value pairs (JSON object) associated with the message.",
					"required": false
				}
			}
		}
	}
}