Docs
Go to Conductrics.com →
  1. Administrative APIs

Agent Management API

You can use this Administrative API if you have a need to manage agents programmatically (rather than creating and updating them in the Conductrics Admin).

📘

API keys and such

To keep this page relatively clear, we're omitting certain details from the example snippets:

  • These examples assume that your account is available at https://api-v3.conductrics.com. Your account likely uses a different endpoint (URL), especially if you're using a private Conductrics server or if your Conductrics account is located outside of the United States.
  • These examples show a pretend account code (acc-xxxxxx). You will need to replace that with your actual account code.
  • You also need to provide the admin API key for your account, either as a query parameter called apikey (so, ?apikey=admin-xxxxxxxx) or as a HTTP header called x-conductrics-apikey.

All of the above details are available in the Conductrics Admin, under Developers > API Info & Keys. If you get an "Unauthorized" message when trying to use these APIs, it's likely that one of these items wasn't provided correctly.

Getting a List of Agents

To get a list of existing agents, issue a GET to:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents

Conductrics will respond with a structure such as the following:

{
  "status": 200,
  "data": [
    {
      "code": "a-H509Pq90EL",
      "name": "Agent 1",
      "desc": "my first agent",
      "status": "stopped",
      "num_days": 0,
      "choices": [
        {
          "code": "A",
          "name": "A Variation",
          "weight": 0.5
        },
        {
          "code": "B",
          "name": "B Variation",
          "weight": 0.5
        }
      ],
      "tags": [ "api", "my-tag" ],
      "workflow_tags": {
        "c-ar": [
          {code: "c-ar-xxxxx", name: "Checkout Funnel"}
        ],
        "c-ob": [
          {code: "c-ar-yyyyy", name: "Increase Sales"}
        ],
        "c-ou": [
          {code: "c-ar-zzzzz", name: "Challenger Won"}
        ]
      },
      "members": [],
      "rec": {
        "u_ts": 1683058908,
        "c_ts": 1683058858,
        "c_by": "[email protected]",
        "s_r_ts": 1683058865,
        "s_r_by": "[email protected]"
      }
    },
    {
      // info about next agent here...
    }
  ]
}

The Conductrics admin uses this API call internally to display the main "Agent List" page.

Here's a summary of what each agent item contains:

  • code - the agent's API code (for instance, you would use this code to get variation selections from the agent via the Runtime API.
  • name - the friendly name of the agent, if one has been provided. If no name has been provided, the agent's code will be repeated in lieu of a name.
  • desc - the agent's description, if one has been provided. If no description has been provided this will be an empty string.
  • status - the agent's current status (stopped, running, or archived).
  • num_days - the number of days that this agent has been marked to run for, if provided. If not provided, this will be set to zero (0).
  • tags - any "tags" that have been assigned to the agent in the Agent List page in the admin.
    One or more tags set internally by Conductrics may also be included, which are used to help display the agent correctly in the admin (for instance api if the agent was created as an API agent, c-wa if the agent is an Express agent, c-q-surv for Survey agents, or c-qa for agents currently in "QA-Only Mode").
  • workflow_tags - any "Workflow Tags" (Area, Objective, and/or Outcome) that have been assigned to the Agent. These Areas / Objectives / Outcomes are shown on the main Dashboard Page and can be created/managed via Settings > Workflow Tags in the Conductrics Admin.
  • choices - the variations that this agent can select from. Each choice contains:
    • code - the variation's API code
    • name - the friendly name of the variation, assuming one has been provided (if not, the choice code is repeated in lieu of a name).
    • meta - an object of name/value pairs if any variation-level "meta-data" has been provided. See the note about variation-level metadata below.
    • weight - the "computed random weight" of the variation, as a number from 0 to 1, inclusive (such as 0.5 for a simple agent with two variations that haven't been specifically weighted with custom weights). Please note that these weights are used for "random" selections only, and thus may not actually be used at runtime if the agent is currently Paused, or is set to Adaptive/Predictive/Bandit mode, or has fixed targeting rules that "force" it to choose a particular variation.
  • members - if the agent in question is a Multivariate (MVT) Agent or Mutually Exclusive Agent, this will contain the "member" agents that are conceptually contained by this agent. The members array is empty otherwise.
  • rec - Information about when certain changes were made to the agent:
    • c_ts - when the agent was created, as a timestamp (seconds since Jan 1 1970 UTC).
    • u_ts - when the agent was last updated (even in a trivial way), as a timestamp.
    • s_r_ts - when the agent's status was last set to "Running" (if ever), as a timestamp. If the agent has ever been "Stopped" or "Paused", there may be corresponding timestamps for s_s_ts and/or s_p_ts respectively.
    • c_by - the admin user that created the agent originally
    • s_r_by - the admin user that last set the agent's status to "Running" (if ever). If the agent has ever been "Stopped" or "Paused", there may be corresponding users listed for s_s_by and/or s_p_by respectively.
  • goals - an array of items with the code and name of each Goal currently associated with the agent. Included only if requested via the with_goals option (see note below).
📘

There are a few other fields returned by the API (such as diagram, ui, and badges) that are not documented here. Feel free to reach out to Conductrics if you have questions about any of them.

Options
There are a few options you can provide when requesting the agent list:

  • To get information about only certain agents, provide an agents query parameter, with the agent codes you want (separated by commas). Omit to get the full list of agents.
  • To filter the list of agents to those assigned to a particular Team, provide a teams query parameter with the team's unique identifier, for example &teams=team-abc123xxx (you can get the team's identifier from the Settings > Users / Teams page in the Conductrics Admin).
    • If you want agents for multiple teams, provide them to the teams query parameter separated by commas. For instance, &teams=team-xxxx123,team-xxxx456 would return agents that belong to either team.
    • You can also provide the special identifier &teams=(none) to get a list of agents that have no team assignments.
  • To filter the list of agents to those assigned to a particular Deployment Target, provide a distros query parameter with the Deploy Target's unique identifier, for example &distros=dt-xxxxxx123 (you can get the Deploy Target's identifier from the Settings > Deploy Targets page in the Conductrics Admin).
    • If you want agents for multiple Deploy Targets, provide them to the distros query parameter separated by commas. For instance, &distros=dt-xxxx123,dt-xxxx456 would return agents that belong to either Deploy Target.
    • This parameter is supported in Conductrics 3.7.14 build 240318.32 and later.
  • To filter the list of agents to those with a particular "Tag" (as assigned on the agent's main page in the admin), provide a tags query parameter with the tag(s) you want (separated by commas).
    • You can also use the tags query parameter to filter by tags that Conductrics adds internally, such as api to only get API agents, c-wa to only get Express agents, c-q-surv for Survey agents, or c-qa for agents currently in "QA-Only Mode").
    • Use commas to filter by multiple tags, which will return only those agents that have ALL of the specified tags (such as tags=c-q-surv,c-qa to get back only Survey agents in QA-Only Mode).
    • You can also use an exclamation point for negation, such as tags=c-wa,!c-qa for Express agents that are NOT in QA-Only mode.
  • To include information about associated goals, provide with_goals as a query parameter (see note below).
  • To include information about agent-level "Visitor Conditions", provide with_agent_conds as a query parameter (see note below).

Sort Order
The items are sorted in alphabetical order by the name field.

Including Goal Associations

If you would like information about which Goals are associated with each agent in the list, add with_goals=true as a query parameter. This will add a goals array for each agent item, where the array contains the code and name of each associated goal. The goals are listed in alphabetical order (by name). For agents that have no associated goals, the goals array will be empty. To get other goal-related details, or to change goal/agent associations, use the Goal Management API.

Including Deploy Target Associations

If you would like information about which Deploy Targets are currently associated with each agent in the list, add with_distros=true as a query parameter. This will add a _distros array for each agent item, where the array contains the code and name of each associated Deploy Target (aka "distro"), listed in alphabetical order by name. For agents that aren't associated with any Deploy Targets, the _distros array will be empty.

Including Conditions

If you would like information about any agent-level "Visitor Conditions" for each agent, add with_agent_conds=true as a query parameter. This will add a agent_conds array for each agent item. For agents with no Visitor Conditions, the array will be empty. For agents with Visitor Conditions, the agent_conds array will contain one or more "nested" arrays, each of which would contain three values (the "left side" of the comparison, the "operator" such as eq or nin, and the "right side" of the comparison).

The agent_conds array may also contain a mode item at the end, which indicates whether the conditions are in any vs all vs none mode. If the mode item is missing, that is equivalent to all. If the Visitor Conditions are in "groups", the sets of conditions will be wrapped in an additional array, with a mode item at the end that indicates sets or setsor. Contact Conductrics if you have questions about the conditions format.

Please note that agent_conds returns just the conditions provided at the agent level (the ones that show up under the Visitor Conditions button in the agent's page in the Conductrics admin). These do not include URL/Page Conditions for Express agents, nor conditions for variation-level "Targeting Rules", etc. That said, you can get those via the "diagrams" portion of the full agent record (see "Retrieving an Existing Agent Record" later in this doc).

Creating an Agent

You can create a new agent by sending a PUT request (with content-type of application/json) to a URL such as this the following. Note that you'll need to make up an API code for the new agent, which appears at the end of the URL:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL

The body of the request should be a JSON structure which describes the agent. At a minimum the agent structure should include the following fields:

{
  "code": "a-H509Pq90EL",
  "name": "Agent 2",
  "status": "stopped",
  "choices": [{
    "code": "A",
    "name": "A Variation"
  }, {
    "code": "B",
    "name": "B Variation"
  }]
}
  • code - the agent's API code. This code must match the agent code in the URL. The Conductrics Admin generates codes that start with a- but that is not a requirement for your own agent codes.
  • name - the friendly name of the agent for display in the Conductrics admin, etc.
  • status - the initial status for the agent (stopped or running).
  • choices - the variations that the agent should select from, as an array of "variation" or "choice" objects. Each of these objects must contain a code and a name:
    • code - the API code for the variation. This is what you'll get back from the Runtime API when you ask the agent for a selection. When creating agents in the Conductrics admin, the UI tends to use codes such as A, B, and so on, but that is not required.
    • name - the friendly name of the variation for display in the Conductrics admin, etc.
    • meta (optional) - an object of name/value pairs. See the note about variation-level metadata below.
📘

Characters allowed in API codes

All code fields in Conductrics may contain letters, numbers, dashes and underscores, up to 100 characters in length.

In addition, you may provide the following additional fields, though we expect and generally recommend that you leave these to users of the Conductrics admin:

  • desc - the agent's description; if no description has been provided this will be an empty string.
  • tags - an array of any "tags" you wish to apply to the agent, though we recommend that you do this in the Conductrics Admin instead. (If you do provide tags, they should not start with c-, as that prefix is reserved for use by Conductrics.)

Finally, these fields are used internally by the admin, but not documented or supported for developer use at this time (contact Conductrics if you have interest in these items):

  • conds - Conditions that specify which visitors this agent should apply to.
  • rules - Any "targeted selection rules" that specify that certain visitors should always get certain variations.
  • conf - Additional configuration options for the agent.
  • diagram - Additional instructions for the agent (populated internally by the Conductrics admin to store and configure the variation "changes" set up "visually" for Express agents).
📘

Variation-Level Metadata

You can use the optional meta field at the variation ("choice") level to provide ad-hoc metadata for use by your application logic if this variation is selected. For instance, if you provide {"hex": "#ff0000"} for the meta field, then Conductrics will return that metadata when the agent selects the variation at runtime. You would presumably use this to change the color of some UI element on your side.

See Using Variation Meta-Data section in the Runtime API Reference page for details.

There are a few rules about what you can provide in the meta object. The keys are validated as "API codes", so they may contain only letters, numbers, dashes and underscores, up to 100 characters in length. The values may be numbers, booleans, or strings of up to 100 characters. Nested arrays or objects are not allowed.

Updating an Existing Agent

The process for updating an existing agent is the same as for creating a new one as explained above.

You may provide a partial object for existing agents, providing only the portions of the agent structure that you wish to change. For instance, if you only want to update the agent's status, you could PUT just the following:

{"status": "running"}

Retrieving an Existing Agent Record

You can retrieve a single agent with a GET, substituting your agent code at the end:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL

Assuming the agent exists, Conductrics will respond with an agent structure with the same fields discussed above.

Archiving an Agent

Equivalent to changing an agent's status to "Archived" in the Conductrics Admin. Archived agents are displayed separately in your agent list, and don't "do anything" (they don't collect data, don't make page changes, don't make selections via the Runtime API, etc).

To archive an agent, issue a POST like the following, substituting your agent code:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL/archive

You can likewise un-archive an archived agent via a POST like the following:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL/unarchive

Deleting an Agent

Equivalent to the Delete Agent button in the Conductrics Admin.

Issue a DELETE to the same endpoint used to PUT or GET the agent, for example:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL

This will completely remove an agent from your account, forever. See also Archiving an Agent on this page for something less "final". :)

Resetting an Agent's Reporting History

Equivalent to the Reset Data button in the Conductrics Admin. Throws away all recorded reporting data for the agent, for all dates. All reports will then show "all zeroes" for the agent.

Issue a POST to a URL in the following form, substituting your agent code near the end:

https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/a-H509Pq90EL/reset-data

There is no "undo" when resetting agent reporting history.

Changing the Selection Policy

You can change the selection policy between "random" and "adaptive" by providing a conf structure with a c-pol value of r or random or a for adaptive. This is equivalent to setting the "gets a selection" dropdown to "Randomly" or "Using Predictive Analytics" in the Conductrics admin.

For instance, to change the policy to adaptive, you can do a PUT as described earlier on this page, with the request body set to:

{"conf": {"c-pol": "a"}}

Creating Multivariate (MVT) Agents

You can create Multivariate (MVT) Agents, which are made up of two or more "normal" or "child" agents. This mirrors the process of creating a multivariate agent grouping in the Conductrics Admin.

Creating an MVT "parent" agent is the same as creating a normal agent as discussed above, except:

  • Specify the codes for the "member" agents as query parameter mvt-members, separating the member codes with commas.

  • Omit the choices portion, as the choices will be created for you (one for each combination of choices in the member agents).

For instance, if you already have two "normal" API agents called btn-size and btn-color, you could issue a POST something like the following:

POST https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/mvt-size-color?mvt-members=btn-size,btn-color

{
  "code": "mvt-size-color",
  "name": "Size + Color",
  "status": "stopped"
}
📘

A few limitations about the "member" agents:

  • The member agents must already exist, and should not be in another grouping.
  • There must be at least 2 member agents, up to a maximum of 5.
  • The total number of choice combinations may not exceed 128.
  • Currently, there is an internal limitation that each combination of choice codes must total 100 characters or less, so don't use long choice codes in the member agents, especially if you are combining more than two agents.

Once created, you'll find that MVT agents have some special properties:

  • The agent will have c-mvt in its tags array, which you can't remove.
  • The agent will have an auto-generated set of choices, which you can't change.
  • When you GET your list of agents (see above):
  • The item for the MVT parent agent will have a members array, with the codes of the child agents
  • The item for the "member" agents will have tag c-mvt-m, which you can't remove.

In other words, there isn't much you can change about an existing MVT parent agent. You can change its status (stopped vs running, etc), and you can change its name, but that's about it.

🚧

MVT Membership is Immutable

The members of an MVT agent cannot be changed, meaning you can't add or remove members once you've created an MVT grouping. You can, however, DELETE the "parent" agent, which will make its members available to be grouped into a new parent agent if you wish.

Creating Mutually-Exclusive (ME) Agents

You can create mutually-exclusive agents in the same basic manner as creating MVT agents (see section above).

Create the "parent" agent by providing a me-members query parameter:

POST https://api-v3.conductrics.com/admin/acc-xxxxxx/agents/agent/me-parent-1?mvt-members=child-1,child-2

{
  "code": "me-parent-1",
  "name": "Child 1 and 2 are Mutually Exclusive",
  "status": "stopped"
}
🚧

ME Membership is Also Immutable

Like MVTs, members of an MVT agent cannot be changed, meaning you can't add or remove members once you've created an MVT grouping. You can, however, DELETE the "parent" agent, which will make its members available to be grouped into a new parent agent if you wish.

Updated about 1 year ago