Agent Management API

This is the same API that our web-based pages use internally for creating agents, adjusting settings, removing agents, etc.

Providing Your API Key: You must provide a valid API key to any of the methods in our Management API. You can provide it as a URL param called 'apikey' as shown above, or you can pass it in a HTTP Header called 'x-mpath-apikey' if you want to keep it out of the query string.

Contents:

Getting a List of Agents

You can get a list of agents via a GET to your 'list-agents' URL, like so:

GET http://api.conductrics.com/undefined/list-agents

Assuming your API key has the appropriate access, the server will respond with a JSON data structure like this (comments and newlines added for clarity):

{
  "data": {
    "agents": [
      // One block like this for each agent
      {
        "code": "agent-1",
        "created": 1344607999, // Seconds after Jan 1 1970 (GMT)
        "name": "Agent 1"
      },
      {
        "code": "agent-2",
        "created": 1347255265,
        "name": "Agent 2"
      }
      ...
    ]
  }
}

Resetting Agent Data

You can reset all of an agent's data (including all learning and reporting history) by issuing a DELETE to the agent's /data URL, like so:

DELETE http://api.conductrics.com/undefined/agent-1/data

Assuming your API key has the appropriate access, the server will respond with a simple status message:

{
  "success": true
}

This API call corresponds to the 'Reset all Data' menu item in our web-based tools.

Deleting an Agent

You can completely delete an agent (including all learning and reporting history) by issuing a DELETE to the agent's base URL, like so:

DELETE http://api.conductrics.com/undefined/agent-1

Assuming your API key has the appropriate access, the server will respond with a simple status message:

{
  "success": true
}

This API call corresponds to the 'Delete Agent' menu item in our web-based tools.

Getting an Agent's Structure as JSON

If you want to get a JSON document that represents an agent's complete configuration, including its decisions, decision options, decision points, and various settings, you can issue a GET to the agent's base URL, like so:

GET http://api.conductrics.com/undefined/agent-1

Assuming your API key has the appropriate access, the server will respond with a JSON structure like the following.

This is for a typcial 'vanilla' agent created automatically by asking for a decision with a new agent code:

{
  "code": "agent-1",
  "owner": "undefined",
  "created": 1344607999,

  "goals": [
    {"code": "goal-1"}
  ],

  "points": [
    {
    "code": "point-1",
    "decisions": [
        {
          "code": "decision-1",
          "choices": [
            {"code": "a"},
            {"code": "b"}
          ]
        }
      ]
    }
  ]
}

JSON Schema

The JSON documents you GET or PUT to our service should conform to the JSON Schema available at http://api.conductrics.com/undefined/schema/agent

You can use this schema definition to document or validate the agent on your side before sending it to our service, if you wish.

Please visit http://json-schema.org for more information about JSON Schemas.

Creating or Changing an Agent with JSON

You can create a new agent (or make changes to an existing agent) by issuing a PUT to the agent's base URL, with the desired agent JSON sent as the message body.

PUT http://api.conductrics.com/undefined/agent-1

The body of the request should be the JSON description of the desired agent, with whatever decisions, settings, goals, or other configuration details you desire. See the preceding section for examples of what the agent JSON documents might look like.

Assuming your API key has the appropriate access, the server will respond with a simple status message:

{
  "success": true
}

JSON Schema Validation

The agent-structure document you PUT to our service should conform to our JSON Schema for Agents (see note above).

If not, you will receive an error message rather than the 'success' message shown here.