Rest API

Polemarch provides REST API for all its functionality accessible via web GUI, because our GUI also uses this API to work. Below comes information about every entity we have in Polemarch and methods applicable to it.

All methods urls stated with /api/v1/ for first api version. With other versions number will be changed. Current documentation wrote for version 1. All methods here placed with this prefix to simplify copy & pasting.

Hosts

GET /api/v1/hosts/{id}/

Get details about one host.

Parameters:
  • id – id of host.

Example request:

GET /api/v1/hosts/12/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":12,
   "name":"038108237241668497-0875926814493907",
   "type":"HOST",
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/hosts/12/?format=json"
}
Response JSON Object:
 
  • id (number) – id of host.
  • name (string) – either human-readable name or hostname/IP or range of them (it is depends at context of using this host during playbooks run).
  • type (string) – it is RANGE if name is range of IPs or hosts, otherwise is HOST.
  • url (string) – url to this specific host.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.
GET /api/v1/hosts/

List of hosts. Pagination is used for this list.

Query Parameters:
 
  • id – id of host if we want to filter by it.
  • name – name of host if we want to filter by it.
  • id__not – id of host, which we want to filter out.
  • name__not – name of host, which we want to filter out.

Example request:

GET /api/v1/hosts/?name__not=192.168.0.1 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":4,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":1,
         "name":"127.0.0.1",
         "type":"HOST",
         "url":"http://testserver/api/v1/hosts/1/"
      },
      {
         "id":2,
         "name":"hostonlocal",
         "type":"HOST",
         "url":"http://testserver/api/v1/hosts/2/"
      },
      {
         "id":3,
         "name":"127.0.0.[3:4]",
         "type":"RANGE",
         "url":"http://testserver/api/v1/hosts/3/"
      },
      {
         "id":4,
         "name":"127.0.0.[5:6]",
         "type":"RANGE",
         "url":"http://testserver/api/v1/hosts/4/"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/hosts/{id}/.

DELETE /api/v1/hosts/{id}/

Delete host.

Parameters:
  • id – id of host.
POST /api/v1/hosts/

Create host.

Request JSON Object:
 
  • name (string) – either human-readable name or hostname/IP or range of them (it is depends at context of using this host during playbooks run).
  • type (string) – it is RANGE if name is range of IPs or hosts, otherwise is HOST.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.

Example request:

POST /api/v1/hosts/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"038108237241668497-0875926814493907",
   "type":"HOST",
   "vars":{

   },
}

Results:

{
   "id":12,
   "name":"038108237241668497-0875926814493907",
   "type":"HOST",
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/hosts/12/?format=json"
}

Response JSON Object: response json fields same as in GET /api/v1/hosts/{id}/.

PATCH /api/v1/hosts/{id}/

Update host. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of host.

Request JSON Object: request json fields same as in POST /api/v1/hosts/

Example request:

PATCH /api/v1/hosts/12/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"038108237241668497-0875926814493907",
   "type":"HOST",
   "vars":{

   },
}

Results:

{
   "id":12,
   "name":"038108237241668497-0875926814493907",
   "type":"HOST",
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/hosts/12/?format=json"
}

Response JSON Object: response json fields same as in GET /api/v1/hosts/{id}/.

Groups

GET /api/v1/groups/{id}/

Get details about one group.

Parameters:
  • id – id of group.

Example request:

GET /api/v1/groups/12/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":1,
   "name":"Group1",
   "hosts":[
      {
         "id":41,
         "name":"127.0.0.2",
         "type":"HOST",
         "url":"http://localhost:8080/api/v1/hosts/41/"
      },
      {
         "id":42,
         "name":"192.168.0.[1-10]",
         "type":"RANGE",
         "url":"http://localhost:8080/api/v1/hosts/42/"
      }
   ],
   "groups":[

   ],
   "vars":{

   },
   "children":false,
   "url":"http://localhost:8080/api/v1/groups/1/"
}
Response JSON Object:
 
  • id (number) – id of group.
  • name (string) – name of group.
  • hosts (array) – list of hosts in group if children is false, otherwise empty. See Hosts for fields explanation.
  • groups (array) – list of subgroups in group if children is true, otherwise empty.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.
  • children (boolean) – either this group of subgroups or group of hosts.
  • url (string) – url to this specific group.
GET /api/v1/groups/

List of groups. Pagination is used for this list.

Query Parameters:
 
  • id – id of group if we want to filter by it.
  • name – name of group if we want to filter by it.
  • id__not – id of group, which we want to filter out.
  • name__not – name of group, which we want to filter out.

Example request:

GET /api/v1/groups/?name__not=web-servers HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":1,
         "name":"Group1",
         "children":false,
         "url":"http://localhost:8080/api/v1/groups/1/"
      },
      {
         "id":2,
         "name":"Group2",
         "children":true,
         "url":"http://localhost:8080/api/v1/groups/2/"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/groups/{id}/.

DELETE /api/v1/groups/{id}/

Delete group.

Parameters:
  • id – id of group.
POST /api/v1/groups/

Create group.

Request JSON Object:
 
  • name (string) – name of new group.
  • children (boolean) – either this group of subgroups or group of hosts.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.

Example request:

POST /api/v1/groups/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"SomeGroup",
   "children":true,
   "vars":{

   }
}

Results:

{
   "id":3,
   "name":"SomeGroup",
   "hosts":[

   ],
   "groups":[

   ],
   "vars":{

   },
   "children":true,
   "url":"http://localhost:8080/api/v1/groups/3/"
}

Response JSON Object: response json fields same as in GET /api/v1/groups/{id}/.

PATCH /api/v1/groups/{id}/

Update group. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of group.

Request JSON Object: request json fields same as in POST /api/v1/groups/

Example request:

PATCH /api/v1/groups/3/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"SomeGroupChanged",
   "children":true,
   "vars":{

   }
}

Results:

{
   "id":3,
   "name":"SomeGroupChanged",
   "hosts":[

   ],
   "groups":[

   ],
   "vars":{

   },
   "children":true,
   "url":"http://localhost:8080/api/v1/groups/3/"
}

Response JSON Object: response json fields same as in GET /api/v1/groups/{id}/.

POST /api/v1/groups/{group_id}/hosts/

Add hosts to group. See Sublists for details.

Status Codes:
  • 409 Conflict – attempt work with hosts list of children group (children=true). Such kind of groups only for store other groups in there.
PUT /api/v1/groups/{group_id}/hosts/

Replace sublist of hosts with new one. See Sublists for details.

Status Codes: status codes same as in POST /api/v1/groups/{group_id}/hosts/.

DELETE /api/v1/groups/{group_id}/hosts/

Remove those hosts from group. See Sublists for details.

Status Codes: status codes same as in POST /api/v1/groups/{group_id}/hosts/.

POST /api/v1/groups/{group_id}/groups/

Add subgroups to group. See Sublists for details.

Status Codes:
  • 409 Conflict – attempt work with group list of not children group (children=false). Such kind of groups only for store hosts in there.
PUT /api/v1/groups/{group_id}/groups/

Replace sublist of subgroups with new one. See Sublists for details.

Status Codes: status codes same as in POST /api/v1/groups/{group_id}/groups/.

DELETE /api/v1/groups/{group_id}/groups/

Remove those subgroups from group. See Sublists for details.

Status Codes: status codes same as in POST /api/v1/groups/{group_id}/groups/.

Inventories

GET /api/v1/inventories/{id}/

Get details about one inventory.

Parameters:
  • id – id of inventory.

Example request:

GET /api/v1/inventories/8/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":8,
   "name":"Inventory1",
   "hosts":[

   ],
   "groups":[

   ],
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/inventories/8/"
}
Response JSON Object:
 
  • id (number) – id of inventory.
  • name (string) – name of inventory.
  • hosts (array) – list of hosts in inventory. See Hosts for fields explanation.
  • groups (array) – list of groups in inventory. See Groups for fields explanation.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.
  • url (string) – url to this specific inventory.
GET /api/v1/inventories/

List of inventories. Pagination is used for this list.

Query Parameters:
 
  • id – id of inventory if we want to filter by it.
  • name – name of inventory if we want to filter by it.
  • id__not – id of inventory, which we want to filter out.
  • name__not – name of inventory, which we want to filter out.

Example request:

GET /api/v1/inventories/?name__not=production HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":1,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":8,
         "name":"Inventory1",
         "url":"http://localhost:8080/api/v1/inventories/8/"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/inventories/{id}/.

DELETE /api/v1/inventories/{id}/

Delete inventory.

Parameters:
  • id – id of inventory.
POST /api/v1/inventories/

Create inventory.

Request JSON Object:
 
  • name (string) – name of new inventory.
  • vars (object) – dictionary of variables associated with this object. See Variables for details.

Example request:

POST /api/v1/inventories/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"Test servers",
   "vars":{

   }
}

Results:

{
   "id":9,
   "name":"Test servers",
   "hosts":[

   ],
   "groups":[

   ],
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/inventories/9/"
}

Response JSON Object: response json fields same as in GET /api/v1/inventories/{id}/.

PATCH /api/v1/inventories/{id}/

Update inventory. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of inventory.

Request JSON Object: request json fields same as in POST /api/v1/inventories/

Example request:

PATCH /api/v1/inventories/9/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"Test servers",
   "vars":{

   }
}

Results:

{
   "id":9,
   "name":"Test servers",
   "hosts":[

   ],
   "groups":[

   ],
   "vars":{

   },
   "url":"http://localhost:8080/api/v1/inventories/9/"
}

Response JSON Object: response json fields same as in GET /api/v1/inventories/{id}/.

POST /api/v1/inventories/{inventory_id}/hosts/

Add hosts to inventory. See Sublists for details.

PUT /api/v1/inventories/{inventory_id}/hosts/

Replace sublist of hosts with new one. See Sublists for details.

DELETE /api/v1/inventories/{inventory_id}/hosts/

Remove those hosts from inventory. See Sublists for details.

POST /api/v1/inventories/{inventory_id}/groups/

Add groups to inventory. See Sublists for details.

PUT /api/v1/inventories/{inventory_id}/groups/

Replace sublist of groups with new one. See Sublists for details.

DELETE /api/v1/inventories/{inventory_id}/groups/

Remove those groups from inventory. See Sublists for details.

Projects

GET /api/v1/projects/{id}/

Get details about project.

Parameters:
  • id – id of project.

Example request:

GET /api/v1/projects/5/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":7,
   "name":"project_pooh",
   "status":"WAIT_SYNC",
   "repository":"git@ex.us:dir/rep1.git",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_password":"forgetit",
      "repo_type":"GIT"
   },
   "url":"http://localhost:8080/api/v1/projects/7/"
}
Response JSON Object:
 
  • id (number) – id of project.
  • name (string) – name of project.
  • repository (string) – URL of repository (repo-specific URL). For TAR it is just HTTP-link to archive.
  • status (string) – current state of project. Possible values are: NEW - newly created project, WAIT_SYNC - repository synchronization scheduled but not yet started to perform, SYNC - synchronization in progress, ERROR - synchronization failed (cvs failure? incorrect credentials?), OK - project is synchronized.
  • hosts (array) – list of hosts in project. See Hosts for fields explanation.
  • groups (array) – list of groups in project. See Groups for fields explanation.
  • vars (object) – dictionary of variables associated with this object. See Variables for details. In this special case always exists variables repo_password to store password for repository and repo_type to store type of repository. Currently implemented types are GIT for Git repositories. And TAR for uploading tar archive with project files.
  • url (string) – url to this specific inventory.
GET /api/v1/projects/

List of projects. Pagination is used for this list.

Query Parameters:
 
  • id – id of project if we want to filter by it.
  • name – name of project if we want to filter by it.
  • id__not – id of project, which we want to filter out.
  • name__not – name of project, which we want to filter out.
  • statusstatus of projects to show in list
  • status__notstatus of projects to not show in list

Example request:

GET /api/v1/projects/?status__not=SYNC HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":7,
         "name":"project_pooh",
         "status":"WAIT_SYNC",
         "type":"GIT",
         "url":"http://localhost:8080/api/v1/projects/7/"
      },
      {
         "id":8,
         "name":"project_tigger",
         "status":"WAIT_SYNC",
         "type":"GIT",
         "url":"http://localhost:8080/api/v1/projects/8/"
      }
   ]
}
Response JSON Object:
 
  • type (string) – special shortcut to var repo_type. Details about that var and other json fields of response you can see at GET /api/v1/projects/{id}/
DELETE /api/v1/projects/{id}/

Delete project.

Parameters:
  • id – id of project.
POST /api/v1/projects/

Create project. Operation automatically triggers synchronization. Details about what it is you can see in description POST /api/v1/projects/{id}/sync/

Request JSON Object:
 
  • name (string) – name of new project.
  • vars (object) – dictionary of variables associated with this object. See Variables for details. In this special case always exists variables repo_password to store password for repository and repo_type to store type of repository. Currently implemented types are GIT for Git repositories. And TAR for uploading tar archive with project files.
  • repository (string) – URL of repository (repo-specific URL). For TAR it is just HTTP-link to archive.

Example request:

POST /api/v1/projects/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"project_owl",
   "repository":"somewhere-in-emptiness",
   "vars":{
      "repo_type":"TAR",
      "repo_password":""
   }
}

Results:

{
   "id":9,
   "name":"project_owl",
   "status":"WAIT_SYNC",
   "repository":"somewhere-in-emptiness",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_password":"",
      "repo_type":"TAR"
   },
   "url":"http://localhost:8080/api/v1/projects/9/"
}

Response JSON Object: response json fields same as in GET /api/v1/projects/{id}/.

PATCH /api/v1/projects/{id}/

Update project. Operation does not start synchronization again. If you want synchronize, you must do it by using POST /api/v1/projects/{id}/sync/ All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of project.

Request JSON Object: request json fields same as in POST /api/v1/projects/

Example request:

PATCH /api/v1/projects/9/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"project_owl",
   "repository":"somewhere-in-emptiness",
   "vars":{
      "repo_type":"TAR",
      "repo_password":""
   }
}

Results:

{
   "id":9,
   "name":"project_owl",
   "status":"WAIT_SYNC",
   "repository":"somewhere-in-emptiness",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_password":"",
      "repo_type":"TAR"
   },
   "url":"http://localhost:8080/api/v1/projects/9/"
}

Response JSON Object: response json fields same as in GET /api/v1/projects/{id}/.

POST /api/v1/projects/{project_id}/hosts/

Add hosts to project. See Sublists for details.

PUT /api/v1/projects/{project_id}/hosts/

Replace sublist of hosts with new one. See Sublists for details.

DELETE /api/v1/projects/{project_id}/hosts/

Remove those hosts from project. See Sublists for details.

POST /api/v1/projects/{project_id}/groups/

Add groups to project. See Sublists for details.

PUT /api/v1/projects/{project_id}/groups/

Replace sublist of groups with new one. See Sublists for details.

DELETE /api/v1/projects/{project_id}/groups/

Remove those groups from project. See Sublists for details.

POST /api/v1/projects/{project_id}/inventories/

Add inventories to project. See Sublists for details.

PUT /api/v1/projects/{project_id}/inventories/

Replace sublist of inventories with new one. See Sublists for details.

DELETE /api/v1/projects/{project_id}/inventories/

Remove those inventories from project. See Sublists for details.

GET /api/v1/projects/supported-repos/

Returns list of supported repository types.

Results:

[
    "TAR",
    "GIT"
]
POST /api/v1/projects/{id}/sync/

Starts synchronization. During that process project files uploading from repository. Concrete details of process highly depends on project type. For GIT is git pull, for TAR it just downloading archive from URL again and unpacking it with rewrite of old files. And so on.

Parameters:
  • id – id of project.

Results:

{
   "detail":"Sync with git@ex.us:dir/rep1.git."
}
POST /api/v1/projects/{id}/execute-playbook/

Execute ansible playbook. Returns history id for watching execution process.

Parameters:
  • id – id of project.
Request JSON Object:
 
  • inventory (number) – inventory to execute playbook at.
  • playbook (string) – playbook to execute.
  • * – any number parameters with any name and string or number type. All those parameters just passes as additional command line arguments to ansible-playbook utility during execution, so you can use this feature to widely customize of ansible behaviour. For any key:value in command line will be --key value. If you want only key without a value (--become option for example), just pass null as value.

Example request:

POST /api/v1/projects/1/execute-playbook/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "inventory": 13,
   "playbook": "main.yml"
   "become": null,
   "su-user": "rootburger"
}

Results:

{
   "detail":"Started at inventory 13.",
   "history_id": 87
}
POST /api/v1/projects/{id}/execute-module/

Execute ansible module. Just like running ansible -m {something} by hands. You can quickly do something with ansible without boring and time consuming work with playbooks etc.

Request JSON Object:
 
  • inventory (number) – inventory to execute at.
  • module (string) – name of module (like ping, shell and so on). You can use any of modules available in ansible.
  • group (string) – to which group in your inventory it must be executed. Use all for all hosts in inventory.
  • args (string) – which args must be passed to module. Just raw string with arguments. You can specify here contains of args option. For example ls -la for shell module.
  • * – any number parameters with any name and string or number type. All those parameters just passes as additional command line arguments to ansible-playbook utility during execution, so you can use this feature to widely customize of ansible behaviour. For any key:value in command line will be --key value. If you want only key without a value (--become option for example), just pass null as value.

Example request:

POST /api/v1/projects/1/execute-module/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

  {
     "inventory":3,
     "module":"shell",
     "group":"all",
     "args":"ls -la"
  }

Results:

{
   "detail":"Started at inventory 3.",
   "history_id": 87
}

Tasks

GET /api/v1/tasks/{id}/

Get details about task.

Parameters:
  • id – id of task.

Example request:

GET /api/v1/tasks/5/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":5,
   "name":"Ruin my environment",
   "playbook":"ruin_my_env.yml",
   "project":13
   "url":"http://localhost:8080/api/v1/tasks/5/"
}
Response JSON Object:
 
  • id (number) – id of task.
  • name (string) – name of task.
  • playbook (string) – playbook file to run within this task.
  • project (number) – id of project, to which this task belongs.
  • url (string) – url to this specific task.
GET /api/v1/tasks/

List tasks. Pagination is used for this list.

Query Parameters:
 
  • id – id of task if we want to filter by it.
  • name – name of task if we want to filter by it.
  • id__not – id of task, which we want to filter out.
  • name__not – name of task, which we want to filter out.
  • playbook – filter by name of playbook.
  • project – filter by id of project.

Example request:

GET /api/v1/tasks/?project=13 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":1,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":5,
         "name":"Ruin my environment",
         "url":"http://localhost:8080/api/v1/tasks/5/"
      }
   ]
}

Periodic tasks

GET /api/v1/periodic-tasks/{id}/

Get details about periodic task.

Parameters:
  • id – id of periodic task.

Example request:

GET /api/v1/periodic-tasks/10/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":10,
   "type":"CRONTAB",
   "schedule":"60* */2 sun,fri 1-15 *",
   "mode":"collect_data.yml",
   "kind":"PLAYBOOK",
   "project":7,
   "inventory":8,
   "vars":{

   },
   "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json"
}
Response JSON Object:
 
  • id (number) – id of periodic task.
  • type (string) – type of periodic task. Either INTERVAL for tasks that runs every N seconds or CRONTAB for tasks, which runs according by more complex rules. According to that schedule field will be interpreted as integer - number of seconds between runs. Or string in cron format with one small exception - Polemarch expect string without year, because years is not supported. You can easily find documentation for cron format in web. Like those, for example: https://linux.die.net/man/5/crontab and http://www.nncron.ru/help/EN/working/cron-format.htm
  • schedule (string) – string with integer value or string in cron format, what depends on type value. Look at type description for details.
  • mode (string) – playbook or module to run periodically.
  • kind (string) – either this task is playbook run (PLAYBOOK) or module run (MODULE).
  • project (number) – id of project which this task belongs to.
  • inventory (number) – id of inventory for which must execute_playbook playbook.
  • vars (object) – those vars have special meaning. All those parameters just passes as additional command line arguments to ansible-playbook utility during execution, so you can use this feature to widely customize of ansible behaviour. For any key:value in command line will be --key value. If you want only key without a value (--become option for example), just pass null as value. In all other aspects this field works like usual vars: dictionary of variables associated with this object. See Variables for details.
  • url (string) – url to this specific periodic task.
GET /api/v1/periodic-tasks/

List of periodic tasks. Pagination is used for this list.

Query Parameters:
 
  • id – id of template if we want to filter by it.
  • id__not – id of template, which we want to filter out.
  • mode – filter by playbook or module name.
  • kind – filter by kind of task.
  • type – filter by type.
  • project – filter by project id.

Example request:

GET /api/v1/periodic-tasks/?project=7 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":10,
         "type":"INTERVAL",
         "schedule":"60",
         "mode":"collect_data.yml",
         "kind":"PLAYBOOK",
         "inventory":8,
         "vars":{

         },
         "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json"
      },
      {
         "id":11,
         "type":"CRONTAB",
         "schedule":"* */2 sun,fri 1-15 *",
         "mode":"do_greatest_evil.yml",
         "kind":"PLAYBOOK",
         "inventory":8,
         "vars":{

         },
         "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/11/?format=json"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/periodic-tasks/{id}/.

DELETE /api/v1/periodic-tasks/{id}/

Delete periodic task.

Parameters:
  • id – id of periodic task.
POST /api/v1/periodic-tasks/

Create periodic task

Request JSON Object:
 
  • type (string) – type of periodic task. Either INTERVAL for tasks that runs every N seconds or CRONTAB for tasks, which runs according by more complex rules. According to that schedule field will be interpreted as integer - number of seconds between runs. Or string in cron format with one small exception - Polemarch expect string without year, because years is not supported. You can easily find documentation for cron format in web. Like those, for example: https://linux.die.net/man/5/crontab and http://www.nncron.ru/help/EN/working/cron-format.htm
  • schedule (string) – string with integer value or string in cron format, what depends on type value. Look at type description for details.
  • mode (string) – playbook or module to run periodically. Depends on value of kind field.
  • kind (string) – Optional argument. Either this task is playbook run (PLAYBOOK) or module run (MODULE). If omitted, will be default - PLAYBOOK. Module tasks also requires two variables for execution: args for module-specific args (can be omitted or empty string) and group to specify for which group in inventory module must run. If you forget to specify group, your task will fail.
  • project (number) – id of project, which task belongs to.
  • inventory (number) – id of inventory to run playbook on.
  • vars (object) – those vars have special meaning. All those parameters just passes as additional command line arguments to ansible-playbook utility during execution, so you can use this feature to widely customize of ansible behaviour. For any key:value in command line will be --key value. If you want only key without a value (--become option for example), just pass null as value. In all other aspects this field works like usual vars: dictionary of variables associated with this object. See Variables for details.

Example request:

POST /api/v1/periodic-tasks/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "project": 7,
    "inventory": 8
    "vars":{

     },
}

Results:

{
    "id": 14,
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "vars":{

     },
    "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api"
}

Response JSON Object: response json fields same as in GET /api/v1/periodic-tasks/{id}/.

PATCH /api/v1/periodic-tasks/{id}/

Update periodic task. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of periodic task.

Request JSON Object: request json fields same as in POST /api/v1/periodic-tasks/

Example request:

PATCH /api/v1/periodic-tasks/14/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "project": 7,
    "inventory": 8
}

Results:

{
    "id": 14,
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "url": "http://127.0.0.1:8080/api/v1/periodic-tasks/14/?format=api"
}

Response JSON Object: response json fields same as in GET /api/v1/periodic-tasks/{id}/.

Templates

GET /api/v1/templates/{id}/

Get template with details.

Parameters:
  • id – id of template.

Example request:

GET /api/v1/templates/1/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "id": 1,
    "name": "test_tmplt",
    "kind": "Task",
    "data": {
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    }
}
Response JSON Object:
 
GET /api/v1/templates/

Get list of templates. Pagination is used for this list.

Query Parameters:
 
  • id – id of project if we want to filter by it.
  • id__not – id of project, which we want to filter out.
  • name – filter by name.
  • name__not – filter by name, which we want to filter out.
  • kind – filter by kind.
  • project – filter by project.
  • inventory – filter by inventory.

Example request:

GET /api/v1/templates/?kind=Task HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "test_tmplt",
            "kind": "Task"
        }
    ]
}

Response JSON Object: response json fields same as in GET /api/v1/templates/{id}/.

DELETE /api/v1/templates/{id}/

Delete periodic task.

Parameters:
  • id – id of periodic task.
POST /api/v1/templates/

Create template

Request JSON Object:
 

Example request:

POST /api/v1/templates/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name": "test",
   "kind": "Task",
   "data": {
      "playbook": "test.yml",
      "vars": {
            "connection": "paramiko"
      }
   }
}

Results:

{
    "id": 2,
    "name": "test",
    "kind": "Task",
    "data": {
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    }
}

Response JSON Object: response json fields same as in GET /api/v1/templates/{id}/.

PATCH /api/v1/templates/{id}/

Update template. If update data, should send full template data. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of template.

Request JSON Object: request json fields same as in POST /api/v1/templates/

Example request:

PATCH /api/v1/templates/2/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
    "name": "test_new_name"
}

Results:

{
    "id": 2,
    "name": "test_new_name",
    "kind": "Task",
    "data": {
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    }
}

Response JSON Object: response json fields same as in GET /api/v1/templates/{id}/.

GET /api/v1/templates/supported-kinds/

List of supported kinds.|pagination_def|

Example request:

GET /api/v1/history/supported-kinds/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "Task": [
        "playbook",
        "vars",
        "inventory",
        "project"
    ],
    "Host": [
        "name",
        "vars"
    ],
    "PeriodicTask": [
        "playbook",
        "vars",
        "inventory",
        "project",
        "type",
        "name",
        "schedule"
    ],
    "Group": [
        "name",
        "vars",
        "children"
    ]
}

History records

GET /api/v1/history/{id}/

Get details about one history record.

Parameters:
  • id – id of history record.

Example request:

GET /api/v1/history/1/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":1,
   "project":2,
   "mode":"task.yml",
   "status":"OK",
   "kind": "PLAYBOOK",
   "start_time":"2017-07-02T12:48:11.922761Z",
   "stop_time":"2017-07-02T13:48:11.922777Z",
   "raw_inventory":"inventory",
   "raw_args": "ansible-playbook main.yml -i /tmp/tmpvMIwMg -v",
   "raw_stdout":"text",
   "initiator": 1,
   "initiator_type": "users"
}
Response JSON Object:
 
  • id (number) – id of history record.
  • project (number) – id of project, which record belongs to.
  • mode (string) – name of executed playbook or module.
  • kind (string) – either was run of ansible-playbook (PLAYBOOK) or ansible (MODULE).
  • status (string) – either DELAY, OK, INTERRUPTED, RUN, OFFLINE or ERROR, which indicates different results of execution (scheduled for run, good, interrupted by user, currently running, can’t connect to node, failure).
  • start_time (string) – time, when playbook execution was started.
  • stop_time (string) – time, when playbook execution was ended (normally or not)
  • raw_inventory (string) – Ansible inventory, which used for execution. It is generates from on of Polemarch’s Inventories
  • raw_args (string) – ansible command line during execution.
  • raw_stdout (string) – what Ansible wrote to stdout and stderr during execution. The size is limited to 10M characters. Full output in GET /api/v1/history/{id}/raw/.
  • initiator (number) – initiator id.
  • initiator_type (string) – initiator type like in api url.
  • url (string) – url to this specific history record.
POST /api/v1/history/{id}/cancel/

Cancel currently executed task.

Parameters:
  • id – id of history record.

Example request:

POST /api/v1/history/1/cancel/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "detail": "Task canceled: 1"
}
GET /api/v1/history/{id}/raw/

Get full output of executed task.

Parameters:
  • id – id of history record.
Query Parameters:
 
  • color – Default is no. If yes you will get output with ANSI Esc color codes printed by Ansible in addition to text itself.

Example request:

GET /api/v1/history/1/raw/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

PLAY [all] *********************************************************************

TASK [Gathering Facts] *********************************************************

ok: [chat.vstconsulting.net]

ok: [pipc.vst.lan]

ok: [git.vst.lan]

ok: [git-ci-2]

ok: [git-ci-1]

ok: [redmine.vst.lan]

ok: [test2.vst.lan]

ok: [test.vst.lan]
......
GET /api/v1/history/{id}/lines/

List of history record lines. Pagination is used for this list.

Query Parameters:
 
  • after – filter lines to return lines after this number.
  • before – filter lines to return lines before this number.

Example request:

GET /api/v1/history/1/lines/?after=2 HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "line_number": 4,
            "line": ""
        },
        {
            "line_number": 3,
            "line": "ERROR! the playbook: /home/centos/test/polemarch/projects/1/test.yml could not be found"
        }
    ]
}
GET /api/v1/history/

List of history records. Pagination is used for this list.

Query Parameters:
 
  • id – id of inventory if we want to filter by it.
  • id__not – id of inventory, which we want to filter out.
  • start_time__gt – filter records whose start_time greater than specified.
  • stop_time__gt – filter records whose stop_time greater than specified.
  • start_time__lt – filter records whose start_time less than specified.
  • stop_time__lt – filter records whose stop_time less than specified.
  • start_time__gte – filter records whose start_time greater or equal to specified.
  • stop_time__gte – filter records whose stop_time greater or equal to specified.
  • start_time__lte – filter records whose start_time less or equal to specified.
  • stop_time__lte – filter records whose stop_time less or equal to specified.
  • mode – filter by mode.
  • kind – filter by kind.
  • project – filter by project.
  • status – filter by status.
  • start_time – get records only with start_time equal to specified.
  • stop_time – get records only with stop_time equal to specified.

Example request:

GET /api/v1/history/?start_time__gte=2017-06-01T01:48:11.923896Z HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id": 121,
         "project": 3,
         "mode": "main.yml",
         "kind": "PLAYBOOK",
         "status": "OK",
         "start_time": "2017-07-24T06:39:52.052504Z",
         "stop_time": "2017-07-24T06:41:06.521813Z",
         "url": "http://localhost:8000/api/v1/history/121/"
      },
      {
         "id": 118,
         "project": null,
         "mode": "ping",
         "kind": "MODULE",
         "status": "OK",
         "start_time": "2017-07-24T06:27:40.481588Z",
         "stop_time": "2017-07-24T06:27:42.499873Z",
         "url": "http://localhost:8000/api/v1/history/118/"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/history/{id}/.

DELETE /api/v1/history/{id}/

Delete history record.

Parameters:
  • id – id of record.
GET /api/v1/history/{id}/facts/

Get facts gathered during execution of setup module.

Parameters:
  • id – id of history record.

Example request:

GET /api/v1/history/1/facts/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "172.16.1.29":{
      "status":"SUCCESS",
      "ansible_facts":{
         "ansible_memfree_mb":526
      },
      "changed":false
   },
   "172.16.1.31":{
      "status":"SUCCESS",
      "ansible_facts":{
         "ansible_memfree_mb":736
      },
      "changed":false
   },
   "172.16.1.30":{
      "status":"UNREACHABLE!",
      "changed":false,
      "msg":"Failed to connect to the host via ssh: ssh: connect to host 172.16.1.30 port 22: No route to host\r\n",
      "unreachable":true
   },
   "172.16.1.32":{
      "status":"FAILED!",
      "changed":false,
      "failed":true,
      "module_stderr":"Shared connection to 172.16.1.32 closed.\r\n",
      "module_stdout":"/bin/sh: /usr/bin/python: No such file or directory\r\n",
      "msg":"MODULE FAILURE"
   }
}
Status Codes:

Ansible

GET /api/v1/ansible/

Get list of available methods in that category. All methods under /ansible/ designed to provide information about ansible installation which Polemarch is currently using.

Example request:

GET /api/v1/ansible/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "cli-reference": "http://localhost:8000/api/v1/ansible/cli_reference/",
    "modules": "http://localhost:8000/api/v1/ansible/modules/"
}
GET /api/v1/ansible/cli_reference/

Get list of available ansible command line tools arguments with their type and hint.

Query Parameters:
 
  • filter – filter by tool, for which you want get help (either ansible or ansible-playbook).

Example request:

GET /api/v1/ansible/cli_reference/?filter=ansible HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "ansible": {
        "extra-vars": {
            "type": "text",
            "help": "set additional variables as key=value or YAML/JSON"
        },
        "help": {
            "type": "boolean",
            "help": "show this help message and exit"
        },
        // there is much more arguments to type it here
        // ...
    }
}
GET /api/v1/ansible/modules/

Get list of installed ansible modules.

Query Parameters:
 
  • filter – filter to search by module name. It is Python regular expression.

Example request:

GET /api/v1/ansible/modules/?filter=\.git HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

[
    "extras.source_control.git_config",
    "extras.source_control.github_release",
    "extras.source_control.github_hooks",
    "extras.source_control.gitlab_user",
    "extras.source_control.github_key",
    "extras.source_control.gitlab_group",
    "extras.source_control.gitlab_project",
    "core.source_control.git"
]

Variables

Hosts, groups, inventories, projects in Polemarch may have variables associated with them. Usually (with one exception - variables for additional repository data in Projects) those variables passes to Ansible to somehow customize his behaviour or playbook logic. In all this kinds of objects variables works in same way, so here additional chapter which describes their behaviour abstracting from details related to every concrete type of object.

In JSON responses related to those objects variables are placed in field vars. This field is just key-value dictionary of existent variables for object. It can be saved in POST and PATCH request completely overwriting previous dictionary.

It can be represented in such more formal way:

GET /api/v1/{object_kind}/{object_id}

Get details about one object.

Parameters:
  • id – id of this object.

Example request:

GET /api/v1/hosts/12/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   // object-special data goes here
   "vars":{
        "string_variable1": "some_string",
        "integer_variable2": 12,
        "float_variable3": 0.3
   }
}
Response JSON Object:
 
  • vars (object) – dictionary of variables for this object.
PATCH /api/v1/{object_kind}/{object_id}

Update object.

Parameters:
  • id – id of object.
Request JSON Object:
 
  • vars (object) – dictionary of variables to save in object. It is completely rewrites old dictionary.

Example request:

PATCH /api/v1/hosts/12/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   // there is may be other object-related stuff
   "vars":{
          "string_variable1": "some_string",
          "integer_variable2": 12,
          "float_variable3": 0.3
   }
}

Results:

{
   // object-special data goes here
   "vars":{
        "string_variable1": "some_string",
        "integer_variable2": 12,
        "float_variable3": 0.3
   },
}

Also for all previously enumerated kinds of objects (which support variables) there is filtering by variables possible in get requests like this:

GET /api/v1/{object_kind}/

Get list of objects. Pagination is used for this list.

Query Parameters:
 
  • variables – filter objects by variables and their values. Variables specified as list using , as separator for every list item and : as separator for key and value. Like var1:value,var2:value,var3:12.

Example request:

GET /api/v1/groups/?variables=ansible_port:222,ansible_user:one HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Sublists

Many of objects types in Polemarch can contain collections of other objects. For example Group can contain sublist of Hosts included in this group. Because all of those sublists base on the same logic, we documenting here general principles of this logic. Its made in order to not duplicate this information for every method of such kind.

Here the list of those methods:

Groups:

Inventories:

Projects:

As you can see there is plenty of urls and for every url post, put and delete methods are present. They all takes list of IDs in json request body, but do different things with those IDs. put methods completely rewrite sublist with new list. post method just append new IDs to already existent. delete method removes specified IDs from existent list.

All of those methods returns such json as result:

{
   "not_found":0,
   "operated":2,
   "total":2,
   "failed_list": []
}

There not_found counter for items, which can’t be processed for some reason. operated for processed successfully. And total is number of elements that was in initial request. If some items not operated successfully, failed_list will be list of them. Otherwise just empty list.

IDs always for object kind, which must be stored in this sublist. For example, for groups/{group_id}/hosts/ it must be ids of existent hosts. If host with id from list not exist method still return 200 OK, but result stats will reflect that fact, that one of the ids can’t be processed successfully.

To clarify information above here is example detailed structured explanation (with request and response examples) for those methods:

ANY /api/v1/{object_kind}/{object_id}/{sublist_kind}/

Operate with sublist of objects for some concrete object.

  • post - append new objects to already existent sublist.
  • delete - removes those objects from existent sublist.
  • put - rewrite sublist with this one.
Parameters:
  • object_kind – kind of object, whose sublist we modify.
  • object_id – id of concrete object, whose sublist we modify.
  • sublist_kind – kind of objects, stored in sublist
Request JSON Array of Objects:
 
  • Ids – Ids of objects, which we must add/remove/replace in sublist.

Example request:

POST /api/v1/groups/1/hosts/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

[2, 3]
{
   "not_found":0,
   "operated":2,
   "total":2
}
Response JSON Object:
 
  • not_found (number) – count of processed with error (not exists or no access).
  • operated (number) – count of processed successfully.
  • total (number) – count of all sent ids.

Users

GET /api/v1/users/{id}/

Get details about one user.

Parameters:
  • id – id of user.

Example request:

GET /api/v1/users/3/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "id":3,
   "username":"petya",
   "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=",
   "is_active":true,
   "is_staff":false,
   "first_name":"Petya",
   "last_name":"Smith",
   "email":"petyasupermail@example.com",
   "url":"http://127.0.0.1:8080/api/v1/users/3/"
}
Response JSON Object:
 
  • id (number) – id of user.
  • username (string) – login.
  • password (string) – hash of password.
  • is_active (boolean) – is account enabled.
  • is_staff (boolean) – is it superuser. Superuser have access to all objects/records despite of access rights.
  • first_name (string) – name.
  • last_name (string) – last name.
  • email (string) – email.
  • url (string) – url to this specific user.
GET /api/v1/users/

List of users. Pagination is used for this list.

Query Parameters:
 
  • id – id of host if we want to filter by it.
  • id__not – id of host, which we want to filter out.
  • username – filter by login.
  • is_active – filter enabled users.
  • first_name – filter by name.
  • last_name – filter by last name.
  • email – filter by email.

Example request:

GET /api/v1/users/?is_active=true HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":1,
         "username":"admin",
         "is_active":true,
         "url":"http://127.0.0.1:8080/api/v1/users/1/"
      },
      {
         "id":3,
         "username":"petya",
         "is_active":true,
         "url":"http://127.0.0.1:8080/api/v1/users/3/"
      }
   ]
}

Response JSON Object: response json fields same as in GET /api/v1/users/{id}/.

DELETE /api/v1/users/{id}/

Delete user.

Parameters:
  • id – id of user.
POST /api/v1/users/

Create user.

Request JSON Object:
 
  • username (string) – login.
  • password (string) – password.
  • is_active (boolean) – is account enabled.
  • is_staff (boolean) – is it superuser. Superuser have access to all objects/records despite of access rights.
  • first_name (string) – name.
  • last_name (string) – last name.
  • email (string) – email.

Example request:

POST /api/v1/users/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "email":"petyasupermail@example.com",
   "first_name":"Petya",
   "last_name":"Smith",
   "username":"petya",
   "is_active":"true",
   "is_staff":"false",
   "password":"rex"
}

Results:

{
   "id":3,
   "username":"petya",
   "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=",
   "is_active":true,
   "is_staff":false,
   "first_name":"Petya",
   "last_name":"Smith",
   "email":"petyasupermail@example.com",
   "url":"http://127.0.0.1:8080/api/v1/users/3/"
}

Response JSON Object: response json fields same as in GET /api/v1/users/{id}/.

PATCH /api/v1/users/{id}/

Update user. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of host.

Request JSON Object: request json fields same as in POST /api/v1/users/

Example request:

PATCH /api/v1/users/3/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "email":"petyasupermail@example.com",
   "first_name":"Petya",
   "last_name":"Smith",
   "username":"petya",
   "is_active":"true",
   "is_staff":"false",
   "password":"rex"
}

Results:

{
   "id":3,
   "username":"petya",
   "password":"pbkdf2_sha256$36000$usSWH0uGIPZl$+Xzz3KpJrq8ZP3truExYOe3CjsaIWgOxuN6jIvJ5ZO8=",
   "is_active":true,
   "is_staff":false,
   "first_name":"Petya",
   "last_name":"Smith",
   "email":"petyasupermail@example.com",
   "url":"http://127.0.0.1:8080/api/v1/users/3/"
}

Response JSON Object: response json fields same as in GET /api/v1/users/{id}/.

Teams (Polemarch+ only)

Teams is groups of users to which you can collectively assign rights to objects in ACL system.

GET /api/v1/teams/{id}/

Get details about one team.

Parameters:
  • id – id of team.

Example request:

GET /api/v1/teams/1/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "id": 1,
    "name": "myteam",
    "users": [
        {
            "id": 1,
            "username": "admin",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/1/"
        }
    ],
    "users_list": [
        1
    ],
    "owner": {
        "id": 1,
        "username": "admin",
        "is_active": true,
        "is_staff": true,
        "url": "http://localhost:8000/api/v1/users/1/"
    },
    "url": "http://localhost:8000/api/v1/teams/1/"
}
Response JSON Object:
 
  • id (number) – id of team.
  • name (string) – name of team.
  • users (array) – array of users in team. See Users for fields explanation.
  • users_list (array) – ids of users in team.
  • owner (object) – owner of team. See Users for fields explanation.
  • url (string) – url to this specific team.
GET /api/v1/teams/

List of teams. Pagination is used for this list.

Query Parameters:
 
  • id – id of team if we want to filter by it.
  • name – name of team if we want to filter by it.
  • id__not – id of team, which we want to filter out.
  • name__not – name of team, which we want to filter out.

Example request:

GET /api/v1/teams/?name__not=outsiders HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "myteam",
            "url": "http://localhost:8000/api/v1/teams/1/"
        }
    ]
}

Response JSON Object: response json fields same as in GET /api/v1/teams/{id}/.

DELETE /api/v1/teams/{id}/

Delete team.

Parameters:
  • id – id of team.
POST /api/v1/teams/

Create team.

Request JSON Object:
 
  • name (string) – name of new team.

Example request:

POST /api/v1/teams/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"another_team"
}

Results:

{
    "id": 2,
    "name": "another_team",
    "users": [],
    "users_list": [],
    "owner": {
        "id": 1,
        "username": "admin",
        "is_active": true,
        "is_staff": true,
        "url": "http://localhost:8000/api/v1/users/1/"
    },
    "url": "http://localhost:8000/api/v1/teams/2/"
}

Response JSON Object: response json fields same as in GET /api/v1/teams/{id}/.

PATCH /api/v1/groups/{id}/

Update team. All parameters except id are optional, so you can specify only needed to update. Only name for example.

Parameters:
  • id – id of team.
Request JSON Object:
 
  • name (string) – name of new team.
  • users_list (array) – list of users to put in team.

Example request:

PATCH /api/v1/teams/2/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{
   "name":"another_team",
   "users_list": [1, 2]
}

Results:

{
    "id": 2,
    "name": "another_team",
    "users": [
        {
            "id": 1,
            "username": "admin",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/1/"
        },
        {
            "id": 2,
            "username": "max",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/2/"
        }
    ],
    "users_list": [
        1,
        2
    ],
    "owner": {
        "id": 1,
        "username": "admin",
        "is_active": true,
        "is_staff": true,
        "url": "http://localhost:8000/api/v1/users/1/"
    },
    "url": "http://localhost:8000/api/v1/teams/2/"
}

Response JSON Object: response json fields same as in GET /api/v1/teams/{id}/.

ACL system (Polemarch+ only)

Because Polemarch supports multiple users it have access rights for every kind of objects. Most kinds of objects (if to be precise: Hosts, Groups, Inventories, Projects, Templates ) have owner and set of permissions associated to every instance of such kind. However other objects (if to be precise: History records, Periodic tasks, Tasks) have dependant role from objects listed above, so they does not have their own permissions, but permissions of parent objects is applicable to them. For example to see PeriodicTasks of project you must have access to project itself.

Currently we support such permission levels:

  • EXECUTOR - can see object in objects list, view details and execute (in case of object is executable like Template, Inventory or something).
  • EDITOR - same as above + right to edit.
  • MASTER - same as above + can work with permissions list for this object (add/delete other users and teams).
  • OWNER - same as above + ability to change owner.

Warning: if you granting somebody EXECUTOR permission to object, he also automatically get EXECUTOR rights to all other objects, which required to use this one. Example: if you give User1 EDITOR right to Inventory1, he also got EXECUTOR to all hosts and groups, which currently listed in Inventory1.

Also there is two types of users: regular and superuser. Regular users have access only to objects, where they listed in permissions. Superusers have access to all objects in system. See Users for detailed information about user management api.

Polemarch+ have such methods to control ownership and permissions information:

GET /api/v1/{object_kind}/{id}/permissions/

Get permissions to object.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.

Results:

[
   {
      "member":1,
      "role":"EDITOR",
      "member_type":"user"
   },
   {
      "member":2,
      "role":"MASTER",
      "member_type":"user"
   }
]
Response JSON Object:
 
POST /api/v1/{object_kind}/{id}/permissions/

Add those permissions to object.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.
Request JSON Array of Objects:
 
  • member (number) – id of user or team for which role should applies.
  • role (string) – either EXECUTOR, EDITOR or MASTER.
  • member_type (string) – either user or team (how to interpret id)

Example request:

POST /api/v1/hosts/123/permissions/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

  [
     {
        "member":1,
        "role":"EDITOR",
        "member_type":"user"
     },
     {
        "member":2,
        "role":"MASTER",
        "member_type":"user"
     }
  ]

Results:

[
   {
      "member":1,
      "role":"EDITOR",
      "member_type":"user"
   },
   {
      "member":2,
      "role":"MASTER",
      "member_type":"user"
   }
]
Response JSON Object:
 
  • permissions (array) – list of actual object permissions after operation. Every permission is same object as in request, so you can look request fields explanation for details.
PUT /api/v1/{object_kind}/{id}/permissions/

Replace permissions to object with provided.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.
Request JSON Object:
 
PUT /api/v1/hosts/123/permissions/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

  [
     {
        "member":1,
        "role":"EDITOR",
        "member_type":"user"
     },
     {
        "member":2,
        "role":"MASTER",
        "member_type":"user"
     }
  ]

Results:

[
   {
      "member":1,
      "role":"EDITOR",
      "member_type":"user"
   },
   {
      "member":2,
      "role":"MASTER",
      "member_type":"user"
   }
]
Response JSON Object:
 
DELETE /api/v1/{object_kind}/{id}/permissions/

Remove access to object for users, who listed in json array in body of request.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.
Request JSON Object:
 

Example request:

DELETE /api/v1/hosts/123/permissions/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

  [
     {
        "member":1,
        "role":"EDITOR",
        "member_type":"user"
     },
     {
        "member":2,
        "role":"MASTER",
        "member_type":"user"
     }
  ]
[]
Response JSON Object:
 
PUT /api/v1/{object_kind}/{id}/owner/

Change owner of object.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.
JSON Parameters:
 
  • id (number) – id of user.
PUT /api/v1/hosts/123/owner/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

  2

Results:

Owner changed
GET /api/v1/{object_kind}/{id}/owner/

Get owner of object.

Parameters:
  • object_kind – Kind of objects to perform operation. It can be any present objects type in system: hosts, groups, inventories, projects, templates.
  • id – Id of object.

Results:

2
Response JSON Object:
 
  • id (number) – id of owner.

License (Polemarch+ only)

GET /api/v1/license/

Get details about your license.

Example request:

GET /api/v1/license/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

Results:

{
    "expiry": null,
    "users": 5,
    "organization": "VST Consulting",
    "contacts": "sergey.k@vstconsulting.net",
    "hosts": null,
    "actual_hosts": 3,
    "actual_users": 2
}
Response JSON Object:
 
  • expiry (string) – date, when license will be (or was) expired. If null license is endless.
  • users (number) – number of users available with this license. If null - unlimited.
  • organization (string) – to whom this license is provided.
  • contacts (string) – contatc information of license owner.
  • hosts (number) – number of hosts available with this license. If null - unlimited.
  • actual_hosts (number) – how many hosts (RANGE calculates appropriately) currently in system.
  • actual_users (number) – how many users currently in system.