POST v1/accounts/{foreignaccountkey}/networks/{foreignkey}/agents

Create a new Agent on the network. Each Agent must have a unique AgentName, otherwise a failure result with a 409 error code is returned. A key property of the Agent is the InstallKey. This must be used during Agent software installation to security bind the Agent to the correct network in the Asavie Cloud. The InstallKey is one of the values that is populated once the creation request is processed from the queue.<br/><br/> Note that is endpoint returns a 202 code as the requests is Q'd. A status url is returned in the return metadata that can be used to poll the status of this request. When the Agent is created successfully on the Asavie network it's Status property will be set as 'complete'

Request Information

URI Parameters

NameDescriptionTypeAdditional information
foreignaccountkey

The Api Account to create the Agent on

string

Required

foreignkey

The network on the account create the Agent on

string

Required

Body Parameters

Agent
NameDescriptionTypeAdditional information
AgentName

The name of the Agent. This is the unique identifier for a SIM

string

Required

Matching regular expression pattern: ^[A-z0-9_]+$

NetworkStatus

The connection status of the Agent to the Asavie Passbridge core. It can have one of the following values:-<br/> disconnected = 0 connected = 1 activation = 10

NetworkStatusValues

None.

Enabled

Gets and sets whether the Agent is enabled or disabled on the Passbridge Core

boolean

None.

AgentTunnel

Gets the name of the Agent tunnel to the Passbridge core.

string

None.

WANAdapter

Gets and sets the IP address of the Agent.

string

Required

Routes

Gets the routes that the Agent can see.

string

None.

Info

Gets the list of details collected by the Agent about its host environment

string

None.

Services

Gets the list of services collected by the Agent about its host environment

string

None.

CertCname

Gets the Common name of the Agent certificate. Every Agent is authenticated to the Passbridge core via x509 certificate.

string

None.

InstallKey

Gets the installation key required to complete an Agent installation

string

None.

Version

The version of the Agent actor. Every time a change is made to the Agent its version is incremented.

integer

None.

ActorStatus

The Agent actor status. Every resource in the api is represented by an actor. The actor status represents the health of the resource. The ActorStatus can be one of the following values:-<br/> stable = 0 /* everything is ok */ pending = 1 /* an operation is long running */ stalled = 10 /* an unrecoverable error has occurred that will require support desk intervention */

ActorStatusValues

None.

Status

StatusValues

None.

ContextSettings

Gets and sets optional settings required to set up the Agent.

Collection of Setting

None.

Request Formats

application/json, text/json

Sample:
{
  "AgentName": "sample string 1",
  "NetworkStatus": 0,
  "Enabled": true,
  "AgentTunnel": "sample string 3",
  "WANAdapter": "sample string 4",
  "Routes": "sample string 5",
  "Info": "sample string 6",
  "Services": "sample string 7",
  "CertCname": "sample string 8",
  "InstallKey": "sample string 9",
  "Version": 10,
  "ActorStatus": 0,
  "Status": 0,
  "ContextSettings": [
    {
      "Key": "sample string 1",
      "SettingType": 0,
      "Value": "sample string 2"
    },
    {
      "Key": "sample string 1",
      "SettingType": 0,
      "Value": "sample string 2"
    }
  ]
}

application/xml, text/xml

Sample:
<Agent xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/AS.Models.API">
  <ActorStatus>stable</ActorStatus>
  <AgentName>sample string 1</AgentName>
  <AgentTunnel>sample string 3</AgentTunnel>
  <CertCname>sample string 8</CertCname>
  <ContextSettings xmlns:d2p1="http://schemas.datacontract.org/2004/07/AS.Interfaces.Models">
    <d2p1:Setting>
      <d2p1:Key>sample string 1</d2p1:Key>
      <d2p1:SettingType>ipaddress</d2p1:SettingType>
      <d2p1:Value>sample string 2</d2p1:Value>
    </d2p1:Setting>
    <d2p1:Setting>
      <d2p1:Key>sample string 1</d2p1:Key>
      <d2p1:SettingType>ipaddress</d2p1:SettingType>
      <d2p1:Value>sample string 2</d2p1:Value>
    </d2p1:Setting>
  </ContextSettings>
  <Enabled>true</Enabled>
  <Info>sample string 6</Info>
  <InstallKey>sample string 9</InstallKey>
  <NetworkStatus>disconnected</NetworkStatus>
  <Routes>sample string 5</Routes>
  <Services>sample string 7</Services>
  <Status>pending</Status>
  <Version>10</Version>
  <WANAdapter>sample string 4</WANAdapter>
</Agent>

application/x-www-form-urlencoded

Sample:

Failed to generate the sample for media type 'application/x-www-form-urlencoded'. Cannot use formatter 'JQueryMvcFormUrlEncodedFormatter' to write type 'Agent'.

Response Information

Resource Description

The newly created Agent with a unique Id

PBPRReturnOfAgent
NameDescriptionTypeAdditional information
Data

Agent

None.

Success

Gets the success status of the API call

boolean

None.

Meta

Gets the optional meta-data

Dictionary of string [key] and string [value]

None.

Code

Get the http code of the API call e.g. 200, 202, 409

integer

None.

ErrorCode

Get the failure error code of the API call. This is available if Success is false

integer

None.

ErrorSubCode

Gets the error sub code if available

integer

None.

ErrorDescription

Gets a textual description of the error

string

None.

StatusUrl

Gets the status url for any ACCEPTed API commands. Any command (POST,DELETE,PATCh,PUT) to the API usually returns a 202 response code. The status of the command can be queried using the URL provided

string

None.

ContinuationToken

Gets the token to be used for paged queries

string

None.

Response Formats

application/json, text/json

Sample:
{
  "Success": true,
  "Meta": {
    "sample string 1": "sample string 2",
    "sample string 3": "sample string 4"
  },
  "Code": 2,
  "ErrorCode": 3,
  "Data": {
    "AgentName": "sample string 1",
    "NetworkStatus": 0,
    "Enabled": true,
    "AgentTunnel": "sample string 3",
    "WANAdapter": "sample string 4",
    "Routes": "sample string 5",
    "Info": "sample string 6",
    "Services": "sample string 7",
    "CertCname": "sample string 8",
    "InstallKey": "sample string 9",
    "Version": 10,
    "ActorStatus": 0,
    "Status": 0,
    "ContextSettings": [
      {
        "Key": "sample string 1",
        "SettingType": 0,
        "Value": "sample string 2"
      },
      {
        "Key": "sample string 1",
        "SettingType": 0,
        "Value": "sample string 2"
      }
    ]
  },
  "ErrorSubCode": 4,
  "ErrorDescription": "sample string 5",
  "StatusUrl": "sample string 6",
  "ContinuationToken": "SlwNEFhJZBgzAF5WVx0LOQ%3D%3D"
}

application/xml, text/xml

Sample:
<PBPRReturnOfAgent7NMnQmOk xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/AS.Models.API">
  <Code>2</Code>
  <ContinuationToken>SlwNEFhJZBgzAF5WVx0LOQ%3D%3D</ContinuationToken>
  <ErrorCode>3</ErrorCode>
  <ErrorDescription>sample string 5</ErrorDescription>
  <ErrorSubCode>4</ErrorSubCode>
  <Meta xmlns:d2p1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
    <d2p1:KeyValueOfstringstring>
      <d2p1:Key>sample string 1</d2p1:Key>
      <d2p1:Value>sample string 2</d2p1:Value>
    </d2p1:KeyValueOfstringstring>
    <d2p1:KeyValueOfstringstring>
      <d2p1:Key>sample string 3</d2p1:Key>
      <d2p1:Value>sample string 4</d2p1:Value>
    </d2p1:KeyValueOfstringstring>
  </Meta>
  <StatusUrl>sample string 6</StatusUrl>
  <Success>true</Success>
  <Data>
    <ActorStatus>stable</ActorStatus>
    <AgentName>sample string 1</AgentName>
    <AgentTunnel>sample string 3</AgentTunnel>
    <CertCname>sample string 8</CertCname>
    <ContextSettings xmlns:d3p1="http://schemas.datacontract.org/2004/07/AS.Interfaces.Models">
      <d3p1:Setting>
        <d3p1:Key>sample string 1</d3p1:Key>
        <d3p1:SettingType>ipaddress</d3p1:SettingType>
        <d3p1:Value>sample string 2</d3p1:Value>
      </d3p1:Setting>
      <d3p1:Setting>
        <d3p1:Key>sample string 1</d3p1:Key>
        <d3p1:SettingType>ipaddress</d3p1:SettingType>
        <d3p1:Value>sample string 2</d3p1:Value>
      </d3p1:Setting>
    </ContextSettings>
    <Enabled>true</Enabled>
    <Info>sample string 6</Info>
    <InstallKey>sample string 9</InstallKey>
    <NetworkStatus>disconnected</NetworkStatus>
    <Routes>sample string 5</Routes>
    <Services>sample string 7</Services>
    <Status>pending</Status>
    <Version>10</Version>
    <WANAdapter>sample string 4</WANAdapter>
  </Data>
</PBPRReturnOfAgent7NMnQmOk>