Fork me on GitHub
Toggle navigation
  • DOCS NAVIGATION
  • Contents:

    • Installation and quick start
    • Run from source distribution
    • Configuration manual
    • GUI workflow
    • Rest API
      • Pagination
      • Hosts
      • Groups
      • Inventories
      • Projects
      • Tasks
      • Periodic tasks
      • Templates
      • History records
      • Ansible
      • Statistic list
      • Variables
      • Sublists
      • Hooks
      • Token
      • Users
      • Teams (Polemarch+ only)
      • ACL system (Polemarch+ only)
      • License (Polemarch+ only)
    • How to participate
    • VST Consulting contributor agreement

Watch us on GitHub

Quick search

Polemarch documentation

Rest API¶

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

All urls methods are stated with /api/v1/ for first API version. With other versions number will be changed. Current documentation is writen for version 1. In this documentation all methods are placed with this prefix to simplify copy & pasting.

Pagination¶

For all kinds of objects in Polemarch pagination is used. So for every list of objects of every kind result will look like:

GET /api/v1/{something}/¶

Gets list of something.

Results:

{
   "count":40,
   "next":"http://localhost:8080/api/v1/hosts/?limit=5&offset=10",
   "previous":"http://localhost:8080/api/v1/hosts/?limit=5",
   "results":[
      // list of objects goes here
   ]
}
Response JSON Object:
 
  • count (number) – how many objects exist at all.
  • next (string) – link to next page with objects (null if we at last).
  • previous (string) – link to previous page with objects (null if we at first).
  • results (array) – array of objects at current page.

Hosts¶

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

Gets 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",
   "notes":"some notes about this host",
   "type":"HOST",
   "vars":{

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "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 on context of using this host during playbooks running).
  • notes (string) – not required field for some user’s notes, for example, for what purpose this host was created or something like this.
  • 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.
  • owner (object) – owner of host. Supported fields could be seen in GET /api/v1/users/{id}/.
  • url (string) – url to this specific host.
GET /api/v1/hosts/¶

Gets 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.
  • type – type 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 are the same as in GET /api/v1/hosts/{id}/.

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

Deletes host.

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

Creates host.

Request JSON Object:
 
  • name (string) – either human-readable name or hostname/IP or range of them (it is depends on context of using this host during playbooks running).
  • notes (string) – not required field for some user’s notes, for example, for what purpose this host was created or something like this.
  • 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",
   "notes":"",
   "type":"HOST",
   "vars":{

   }
}

Results:

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

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/hosts/12/?format=json"
}

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

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

Updates 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 are the 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"
}

Results:

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

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/hosts/12/?format=json"
}

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

Groups¶

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

Gets 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",
   "notes":"some notes about this group",
   "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,
   "owner": {
         "id": 1,
         "username": "admin",
         "is_active": true,
         "is_staff": true,
         "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/groups/1/"
}
Response JSON Object:
 
  • id (number) – id of group.
  • name (string) – name of group.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this group was created or something like this.
  • 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.
  • owner (object) – owner of group. Supported fields could be seen in GET /api/v1/users/{id}/.
  • url (string) – url to this specific group.
GET /api/v1/groups/¶

Gets 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 are the same as in GET /api/v1/groups/{id}/.

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

Deletes group.

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

Creates group.

Request JSON Object:
 
  • name (string) – name of new group.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this group was created or something like this.
  • 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",
   "notes": "",
   "children":true,
   "vars":{

   }
}

Results:

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

   ],
   "groups":[

   ],
   "vars":{

   },
   "children":true,
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/groups/3/"
}

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

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

Updates 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 are the 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"
}

Results:

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

   ],
   "groups":[

   ],
   "vars":{

   },
   "children":true,
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/groups/3/"
}

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

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

Adds hosts to group. See Sublists for details.

Status Codes:
  • 409 Conflict – attempt to work with hosts list of children group (children=true). This kind of groups is only for storing other groups within itself.
PUT /api/v1/groups/{group_id}/hosts/¶

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

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

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

Removes those hosts from group. See Sublists for details.

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

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

Adds subgroups to group. See Sublists for details.

Status Codes:
  • 409 Conflict – attempt to work with group list of not children group (children=false). This kind of groups is only for storing hosts within itself.
PUT /api/v1/groups/{group_id}/groups/¶

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

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

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

Removes those subgroups from group. See Sublists for details.

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

Inventories¶

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

Gets 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",
   "notes": "some notes about this inventory",
   "hosts":[
      {
          "id": 7,
          "name": "test-host-0",
          "type": "HOST",
          "url": "http://localhost:8080/api/v1/hosts/7/"
      }
   ],
   "all_hosts": [
      {
          "id": 7,
          "name": "test-host-0",
          "type": "HOST",
          "url": "http://localhost:8080/api/v1/hosts/7/"
      },
      {
          "id": 8,
          "name": "test-host-from-test-group-1",
          "type": "HOST",
          "url": "http://localhost:8080/api/v1/hosts/8/"
      },
      {
          "id": 9,
          "name": "test-host-from-test-group-2",
          "type": "HOST",
          "url": "http://localhost:8080/api/v1/hosts/9/"
      }
   ],
   "groups":[
      {
          "id": 6,
          "name": "test-group",
          "children": false,
          "url": "http://localhost:8080/api/v1/groups/6/"
      }
   ],
   "vars":{

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/inventories/8/"
}
Response JSON Object:
 
  • id (number) – id of inventory.
  • name (string) – name of inventory.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this inventory was created or something like this.
  • hosts (array) – list of hosts in inventory. See Hosts for fields explanation.
  • all_hosts (array) – list of all hosts in inventory(includes also hosts from this inventory’s groups) . 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.
  • owner (object) – owner of inventory. Supported fields could be seen in GET /api/v1/users/{id}/.
  • url (string) – url to this specific inventory.
GET /api/v1/inventories/¶

Gets 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":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":8,
         "name":"Inventory1",
         "url":"http://localhost:8080/api/v1/inventories/8/"
      },
      {
         "id":9,
         "name":"Inventory2",
         "url":"http://localhost:8080/api/v1/inventories/9/"
      }
   ]
}

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

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

Deletes inventory.

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

Creates inventory.

Request JSON Object:
 
  • name (string) – name of new inventory.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this inventory was created or something like this.
  • 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",
   "notes":"",
   "vars":{

   }
}

Results:

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

   ],
   "all_hosts":[

   ]
   "groups":[

   ],
   "vars":{

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/inventories/9/"
}

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

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

Updates 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 are the 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":"New test servers"
}

Results:

{
   "id":9,
   "name":"New test servers",
   "notes":"",
   "hosts":[

   ],
   "all_hosts":[

   ]
   "groups":[

   ],
   "vars":{

   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "url":"http://localhost:8080/api/v1/inventories/9/"
}

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

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

Adds hosts to inventory. See Sublists for details.

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

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

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

Removes those hosts from inventory. See Sublists for details.

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

Adds groups to inventory. See Sublists for details.

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

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

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

Removes those groups from inventory. See Sublists for details.

Projects¶

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

Gets 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",
   "notes":"some notes about this project",
   "status":"WAIT_SYNC",
   "repository":"git@ex.us:dir/rep1.git",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_branch": "other",
      "repo_password":"forgetit",
      "repo_type":"GIT"
   },
   "owner": {
      "id": 1,
      "username": "admin",
      "is_active": true,
      "is_staff": true,
      "url": "http://localhost:8080/api/v1/users/1/"
   },
   "revision": "5471aeb916ee7f8754d55f159e532592b995b0ec",
   "branch": "master",
   "readme_content": null,
   "readme_ext": null,
   "url":"http://localhost:8080/api/v1/projects/7/"
}
Response JSON Object:
 
  • id (number) – id of project.
  • name (string) – name of project.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this project was created or something like this.
  • repository (string) – URL of repository (repo-specific URL). For TAR it is just HTTP-link to archive.
  • status (string) – current status of project. Possible values are: NEW - newly created project, WAIT_SYNC - repository synchronization has been scheduled, but has not started to perform yet, SYNC - synchronization is 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 variable repo_type always exists to store type of repository. Currently implemented types are GIT - for Git repositories, TAR - for uploading tar archive with project files and MANUAL - for creating empty project or for uploading project files from server ‘manually’. For GIT projects such variables, as repo_password and repo_branch, are also available. repo_password is needed to store password for repository(if it exists) and repo_branch means a branch of git project with which next synchronization will be done.
  • owner (object) – owner of project. Supported fields could be seen in GET /api/v1/users/{id}/.
  • revision (string) – GIT revision
  • branch (string) – current branch of project, to which project has been synced last time.
  • readme_content (string) – if project has “readme.md” or “readme.rst” file in it’s project directory, this field will contain content of readme file parsed to html
  • readme_ext (string) – if project has “readme.md” or “readme.rst” file in it’s project directory, this field will contain extension of readme file
  • url (string) – url to this specific inventory.
GET /api/v1/projects/¶

Gets 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.
  • status – status of projects to show in list
  • status__not – status 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}/¶

Deletes project.

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

Creates 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.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this project was created or something like this.
  • vars (object) – dictionary of variables associated with this object. See Variables for details. In this special case variable repo_type always exists to store type of repository. Currently implemented types are GIT - for Git repositories, TAR - for uploading tar archive with project files and MANUAL - for creating empty project or for uploading project files from server ‘manually’. For GIT projects such variables, as repo_password and repo_branch, are also available. repo_password is needed to store password for repository(if it exists) and repo_branch means a branch of git project with which next synchronization will be done.
  • 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",
   "notes":"",
   "repository":"http://example.com/project.tar",
   "vars":{
      "repo_type":"TAR"
   }
}

Results:

{
   "id":9,
   "name":"project_owl",
   "notes":"",
   "status":"WAIT_SYNC",
   "repository":"http://example.com/project.tar",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_type":"TAR"
   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "revision": "NO VCS",
   "branch": "NO VCS",
   "readme_content": null,
   "readme_ext": null,
   "url":"http://localhost:8080/api/v1/projects/9/"
}

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

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

Updates project. Operation does not start synchronization again. If you want to synchronize, you should 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 are the 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_tar"
}

Results:

{
   "id":9,
   "name":"project_tar",
   "notes":"",
   "status":"WAIT_SYNC",
   "repository":"http://example.com/project.tar",
   "hosts":[

   ],
   "groups":[

   ],
   "inventories":[

   ],
   "vars":{
      "repo_type":"TAR"
   },
   "owner": {
       "id": 1,
       "username": "admin",
       "is_active": true,
       "is_staff": true,
       "url": "http://localhost:8080/api/v1/users/1/"
   },
   "revision": "NO VCS",
   "branch": "NO VCS",
   "readme_content": null,
   "readme_ext": null,
   "url":"http://localhost:8080/api/v1/projects/9/"
}

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

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

Adds hosts to project. See Sublists for details.

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

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

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

Removes those hosts from project. See Sublists for details.

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

Adds groups to project. See Sublists for details.

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

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

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

Removes those groups from project. See Sublists for details.

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

Adds inventories to project. See Sublists for details.

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

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

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

Removes those inventories from project. See Sublists for details.

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

Returns list of supported repository types.

Results:

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

Starts synchronization. During this process project files are 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 rewriting of old files.

Parameters:
  • id – id of project.

Results:

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

Executes 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 pass as additional command line arguments to ansible-playbook utility during execution, so you can use this feature for wide customization of ansible behaviour. For any key:value in command line there will be --key value. If you want to post 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/¶

Executes ansible module. It is just like running ansible -m {something} by hands. Instead of boring and time consuming dealing with playbooks you can do something quickly using ansible.

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. It is just string raw 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 pass as additional command line arguments to ansible-playbook utility during execution, so you can use this feature to wide customization of ansible behaviour. For any key:value in command line there will be --key value. If you want to post 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}/¶

Gets 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/¶

Gets list of 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":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "id":5,
         "name":"Ruin my environment",
         "playbook":"ruin_my_env.yml",
         "project":13
         "url":"http://localhost:8080/api/v1/tasks/5/"
      },
      {
         "id":6,
         "name":"Build my environment",
         "playbook":"build_my_env.yml",
         "project":13
         "url":"http://localhost:8080/api/v1/tasks/6/"
      }
   ]
}

Periodic tasks¶

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

Gets 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,
   "name":"periodic-test",
   "notes":"some notes about this periodic task",
   "type":"CRONTAB",
   "schedule":"60* */2 sun,fri 1-15 *",
   "mode":"collect_data.yml",
   "kind":"PLAYBOOK",
   "project":7,
   "inventory":8,
   "save_result": true,
   "template": null,
   "template_opt": null,
   "enabled": true,
   "vars":{

   },
   "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/?format=json"
}
Response JSON Object:
 
  • id (number) – id of periodic task.
  • name (string) – name of periodic task.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this periodic task was created or something like this.
  • type (string) – type of periodic task. Either INTERVAL for tasks that run every N seconds or CRONTAB for tasks, which run according to 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 expects string without year, because year format 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) – PLAYBOOK (if this task runs playbook), MODULE (if this task runs module) or TEMPLATE (if this task runs template).
  • project (number) – id of project, which this task belongs to.
  • inventory (number) – id of inventory for which must execute_playbook playbook.
  • save_result (boolean) – if save_result is true, the result will be saved.
  • template (number) – id of template (if kind is PLAYBOOK or MODULE, this field will be equal to null).
  • template_opt (string) – name of template option (if kind is PLAYBOOK or MODULE of if this periodic task executes template without option, this field will be equal to null).
  • enabled (boolean) – if enabled is true, the periodic task will be enabled.
  • vars (object) – those vars have special meaning. All those parameters just pass as additional command line arguments to ansible-playbook utility during execution, so you can use this feature for wide customization of ansible behaviour. For any key:value in command line there will be --key value. If you want to post only key without a value (--become option for example), just pass null as value. In all other cases 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/¶

Gets 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,
         "name":"periodic-test",
         "type":"CRONTAB",
         "schedule":"60* */2 sun,fri 1-15 *",
         "mode":"collect_data.yml",
         "kind":"PLAYBOOK",
         "project":7,
         "inventory":8,
         "save_result": true,
         "template": null,
         "template_opt": null,
         "enabled": true,
         "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/10/"
      },
      {
         "id":11,
         "name":"periodic-test2",
         "type":"INTERVAL",
         "schedule":"20",
         "mode":"",
         "kind":"TEMPLATE",
         "project":7,
         "inventory":8,
         "save_result": true,
         "template": 1,
         "template_opt": "some-vars",
         "enabled": true,
         "url":"http://127.0.0.1:8080/api/v1/periodic-tasks/11/"
      }
   ]
}

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

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

Deletes periodic task.

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

Creates periodic task

Example request:

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

{
    "name":"new-periodic-test",
    "notes":"",
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "save_result": true,
    "template": null,
    "template_opt": null,
    "enabled": true,
    "vars":{

     },
}

Results:

{
    "id": 14,
    "name":"new-periodic-test",
    "notes":"",
    "type": "INTERVAL",
    "schedule": "25",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "save_result": true,
    "template": null,
    "template_opt": null,
    "enabled": true,
    "vars":{

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

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

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

Updates 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 are the 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": "60"
}

Results:

{
    "id": 14,
    "name":"new-periodic-test",
    "notes":"",
    "type": "INTERVAL",
    "schedule": "60",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "save_result": true,
    "template": null,
    "template_opt": null,
    "enabled": true,
    "vars":{

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

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

POST /api/v1/periodic-tasks/{id}/execute/¶

Executes periodic task.

Parameters:
  • id – id of periodic task.

Example request:

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

{
    "name":"new-periodic-test",
    "notes":"",
    "type": "INTERVAL",
    "schedule": "60",
    "mode": "touch_the_clouds.yml",
    "kind": "PLAYBOOK",
    "project": 7,
    "inventory": 8,
    "save_result": true,
    "template": null,
    "template_opt": null,
    "enabled": true,
    "vars":{

    }
}

Results:

{
    "history_id": 158,
    "detail": "Started at inventory 8."
}

Request JSON Object: request json fields are the same as in GET /api/v1/periodic-tasks/{id}/ .

Templates¶

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

Gets 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",
    "notes": "some notes about this template",
    "kind": "Task",
    "owner": {
        "id": 1,
        "username": "admin",
        "is_active": true,
        "is_staff": true,
        "url": "http://localhost:8080/api/v1/users/1/"
    },
    "data": {
        "project": 1,
        "inventory": 10,
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    },
     "options": {
         "only-local": {
             "playbook": "other.yml",
         },
         "only-server": {
             "vars": {
                 "forks": "10",
                 "limit": "Test-server"
             }
         }
     },
     "options_list": [
         "only-local",
         "only-server"
     ]
}
Response JSON Object:
 
  • id (number) – id of template.
  • name (string) – name of template.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this template was created or something like this.
  • kind (string) – kind of template. Supported kinds could be seen in GET /api/v1/templates/supported-kinds/.
  • owner (object) – owner of template. Supported fields could be seen in GET /api/v1/users/{id}/.
  • data (string) – JSON structure of template. Supported fields could see in GET /api/v1/templates/supported-kinds/.
  • options (object) – tepmlate options, which can update some template’s settings before new execution.
  • options_list (array) – list of options’ names for this template.
GET /api/v1/templates/¶

Gets 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": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "test_tmplt",
            "kind": "Task",
            "options_list": [
                 "only-local",
                 "only-server"
            ]
        },
        {
            "id": 2,
            "name": "test_tmplm",
            "kind": "Module",
            "options_list": [

            ]
        }
    ]
}

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

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

Deletes periodic task.

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

Creates template

Request JSON Object:
 
  • name (string) – template name.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this template was created or something like this.
  • kind (string) – kind of template. Supported kinds could be seen in GET /api/v1/templates/supported-kinds/.
  • data (string) – JSON structure of template. Supported fields could see in GET /api/v1/templates/supported-kinds/.
  • options (string) – template options, which can update some template’s settings before new execution.

Example request:

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

{
   "name": "test",
   "notes":"",
   "kind": "Task",
   "data": {
      "project": 1,
      "inventory": 10,
      "playbook": "test.yml",
      "vars": {
            "connection": "paramiko"
      }
   },
   "options": {
      "playbook": "other.yml"
  }
}

Results:

{
    "id": 3,
    "name": "test",
    "notes":"",
    "kind": "Task",
    "data": {
        "project": 1,
        "inventory": 10,
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    },
    "options": {
        "playbook": "other.yml"
    }
}

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

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

Updates template. If you want to update data, you 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 are the 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": 3,
    "name": "test_new_name",
    "notes":"",
    "kind": "Task",
    "data": {
        "project": 1,
        "inventory": 10,
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    },
    "options": {
        "playbook": "other.yml"
    }
}

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

POST /api/v1/templates/{id}/execute/¶

Executes template.

Parameters:
  • id – id of template.

Example request:

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

{
    "name": "test_new_name",
    "kind": "Task",
    "data": {
        "project": 1,
        "inventory": 10,
        "playbook": "test.yml",
        "vars": {
            "connection": "paramiko"
        }
    },
    "options": {
        "option": "playbook"
    }
}

Results:

{
    "history_id": 205,
    "detail": "Started at inventory 10."
}

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

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

Gets list of supported kinds. Pagination is used for this list.

Example request:

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

Results:

{
     "Group": [
         "name",
         "vars",
         "children"
     ],
     "Host": [
         "name",
         "vars"
     ],
     "Task": [
         "playbook",
         "vars",
         "inventory",
         "project"
     ],
     "PeriodicTask": [
         "type",
         "name",
         "schedule",
         "inventory",
         "kind",
         "mode",
         "project",
         "vars"
     ],
     "Module": [
         "inventory",
         "module",
         "group",
         "args",
         "vars",
         "project"
     ]
}

History records¶

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

Gets 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:16.922777Z",
   "execution_time": 5,
   "inventory": 4,
   "raw_inventory":"inventory",
   "raw_args": "ansible-playbook main.yml -i /tmp/tmpvMIwMg -v",
   "raw_stdout":"http://localhost:8080/api/v1/history/1/raw/",
   "initiator": 1,
   "initiator_type": "project",
   "executor": 1,
   "execute_args": {
       "diff": "",
       "become": ""
   },
   "revision": "NO VCS",
   "options": {},
   "url": "http://localhost:8080/api/v1/history/1/"
}
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) – kind of task: PLAYBOOK or MODULE.
  • status (string) – either DELAY, OK, INTERRUPTED, RUN, OFFLINE or ERROR, which indicates different results of execution (scheduled for run, successful run, 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)
  • execution_time (number) – time taken to perform task execution (in seconds).
  • inventory (number) – id of inventory.
  • raw_inventory (string) – ansible inventory, which was used for execution. It was generated from Polemarch’s Inventories
  • raw_args (string) – ansible command line during execution.
  • raw_stdout (string) – what Ansible has written 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.
  • executor (number) – id of user, who executed task.
  • execute_args (object) – arguments, which were used during execution.
  • revision (string) – project revision.
  • options (object) – some additional options, which were used during this task execution. For example, if you execute some template with option, name of this option will be saved to this object.
  • url (string) – url to this specific history record.
POST /api/v1/history/{id}/cancel/¶

Cancels 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/¶

Gets full output of executed task.

Parameters:
  • id – id of history record.
Query Parameters:
 
  • color – Default is no. If it is 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/¶

Gets 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"
        }
    ]
}
DELETE /api/v1/history/{id}/clear/¶

Deletes full output of executed task.

Parameters:
  • id – id of history record.

Example request:

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

Results:

{
    "detail": "Output trancated.\n"
}
Response JSON Object:
 
  • detail (string) – new output for history record’s stdout.
GET /api/v1/history/¶

Gets 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.
  • initiator – filter by initiator.
  • initiator_type – filter by initiator_type.

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",
         "inventory": 6,
         "status": "OK",
         "start_time": "2017-07-24T06:39:52.052504Z",
         "stop_time": "2017-07-24T06:41:06.521813Z",
         "initiator": 1,
         "initiator_type": "project",
         "executor": 1,
         "options": {},
         "url": "http://localhost:8000/api/v1/history/121/"
      },
      {
         "id": 118,
         "project": 4,
         "mode": "ping",
         "kind": "MODULE",
         "inventory": 7,
         "status": "OK",
         "start_time": "2017-07-24T06:27:40.481588Z",
         "stop_time": "2017-07-24T06:27:42.499873Z",
         "initiator": 2,
         "initiator_type": "template",
         "executor": 1,
         "options": {
             "template_option": "some-vars"
         },
         "url": "http://localhost:8000/api/v1/history/118/"
      }
   ]
}

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

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

Deletes history record.

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

Gets 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:
  • 200 OK – no error
  • 404 Not Found – there is no facts. Either incorrect history id or kind not MODULE and/or module is not setup. Facts can be gathered only by running setup module. See POST /api/v1/projects/{id}/execute-module/ for details about modules run.
  • 424 Failed Dependency – facts are still not ready, because module is currently running or only scheduled for run.

Ansible¶

GET /api/v1/ansible/¶

Gets 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/¶

Gets 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 (for exapmle, periodic_playbook or periodic_module).

Example request:

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

Results:

{
    "periodic_playbook": {
        "flush-cache": {
            "shortopts": [],
            "type": "boolean",
            "help": "clear the fact cache"
        },
        "extra-vars": {
            "type": "text",
            "help": "set additional variables as key=value or YAML/JSON"
        },
        // there is much more arguments to type it here
        // ...
    },
    "playbook": {
        "flush-cache": {
            "shortopts": [],
            "type": "boolean",
            "help": "clear the fact cache"
        },
        "extra-vars": {
            "type": "text",
            "help": "set additional variables as key=value or YAML/JSON"
        },
        // there is much more arguments to type it here
        // ...
    },
    "module": {
        "extra-vars": {
            "type": "text",
            "help": "set additional variables as key=value or YAML/JSON"
        },
        "help": {
            "shortopts": [
                "h"
            ],
            "type": "boolean",
            "help": "show this help message and exit"
        },
        // there is much more arguments to type it here
        // ...
    },
    "periodic_module": {
        "extra-vars": {
            "type": "text",
            "help": "set additional variables as key=value or YAML/JSON"
        },
        "help": {
            "shortopts": [
                "h"
            ],
            "type": "boolean",
            "help": "show this help message and exit"
        },
        // there is much more arguments to type it here
        // ...
    }
}
GET /api/v1/ansible/modules/¶

Gets 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:

[
   "source_control.github_hooks",
   "source_control.git_config",
   "source_control.github_issue",
   "source_control.git",
   "source_control.github_deploy_key",
   "source_control.gitlab_project",
   "source_control.github_release",
   "source_control.gitlab_group",
   "source_control.github_key",
   "source_control.gitlab_user"
]

Statistic list¶

Sometimes application needs to provide user with some statistic information like amount of different objects or frequency of executing some tasks and so on. For such kind of work we use our API’s statistic list, which can provide user with information about amount of templates, users, teams, hosts, groups, inventories, projects in system in current moment and to tell him how many tasks of each status have been executed during last days, months and years.

GET /api/v1/stats/¶

Gets statistic list.

Query Parameters:
 
  • last – filter to search statistic information for certain amount of past days (by default the last is 14, this filter is measured in days).

Example request:

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

Results:

{
    "templates": 7,
    "users": 1,
    "teams": 0,
    "hosts": 10,
    "groups": 5,
    "inventories": 4,
    "projects": 3,
    "jobs": {
        "month": [
            {
                "status": "ERROR",
                "sum": 6,
                "all": 47,
                "month": "2018-03-01T00:00:00Z"
            },
            {
                "status": "OFFLINE",
                "sum": 5,
                "all": 47,
                "month": "2018-03-01T00:00:00Z"
            },
            {
                "status": "OK",
                "sum": 36,
                "all": 47,
                "month": "2018-03-01T00:00:00Z"
            }
        ],
        "day": [
            {
                "status": "ERROR",
                "sum": 3,
                "day": "2018-03-05T00:00:00Z",
                "all": 10
            },
            {
                "status": "OK",
                "sum": 7,
                "day": "2018-03-05T00:00:00Z",
                "all": 10
            },
            {
                "status": "ERROR",
                "sum": 2,
                "day": "2018-03-06T00:00:00Z",
                "all": 30
            },
            {
                "status": "OFFLINE",
                "sum": 5,
                "day": "2018-03-06T00:00:00Z",
                "all": 30
            },
            {
                "status": "OK",
                "sum": 23,
                "day": "2018-03-06T00:00:00Z",
                "all": 30
            },
            {
                "status": "ERROR",
                "sum": 1,
                "day": "2018-03-07T00:00:00Z",
                "all": 7
            },
            {
                "status": "OK",
                "sum": 6,
                "day": "2018-03-07T00:00:00Z",
                "all": 7
            }
        ],
        "year": [
            {
                "status": "ERROR",
                "sum": 6,
                "all": 47,
                "year": "2018-01-01T00:00:00Z"
            },
            {
                "status": "OFFLINE",
                "sum": 5,
                "all": 47,
                "year": "2018-01-01T00:00:00Z"
            },
            {
                "status": "OK",
                "sum": 36,
                "all": 47,
                "year": "2018-01-01T00:00:00Z"
            }
        ]
    }
}
Response JSON Object:
 
  • templates (number) – amount of templates in system in current moment.
  • users (number) – amount of users in system in current moment.
  • teams (number) – amount of teams in system in current moment. (Polemarch+ only)
  • hosts (number) – amount of hosts in system in current moment.
  • groups (number) – amount of groups in system in current moment.
  • inventories (number) – amount of inventories in system in current moment.
  • projects (number) – amount of projects in system in current moment.
  • jobs (object) – amount of executed tasks during last days, months, years.

Variables¶

Hosts, groups, inventories and projects in Polemarch may have variables associated with them. Usually (with one exception - variables for additional repository data in Projects) those variables pass to Ansible to customize his behaviour or playbook logic in certain way. In all these kinds of objects variables work in the same way, so there is an 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 by POST request and can be completely owerwritted by PATCH request.

It can be represented in such more formal way:

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

Gets 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}¶

Updates object.

Parameters:
  • id – id of object.
Request JSON Object:
 
  • vars (object) – new dictionary of variables for object. It 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_string2",
          "integer_variable2": 15,
          "float_variable3": 0.5
   }
}

Results:

{
   // object-special data goes here
   "vars":{
        "string_variable1": "some_string2",
        "integer_variable2": 15,
        "float_variable3": 0.5
   },
}

Also for all previously enumerated kinds of objects (which support variables) there is variable filtering, which is available in get requests:

GET /api/v1/{object_kind}/¶

Gets 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

Results:

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

Sublists¶

Many of object 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 are based on the same logic, we have documented here general principles of this logic in order not to duplicate this information for every single method.

There is the list of those methods:

Groups:

  • POST /api/v1/groups/{group_id}/hosts/
  • PUT /api/v1/groups/{group_id}/hosts/
  • DELETE /api/v1/groups/{group_id}/hosts/
  • POST /api/v1/groups/{group_id}/groups/
  • PUT /api/v1/groups/{group_id}/groups/
  • DELETE /api/v1/groups/{group_id}/groups/

Inventories:

  • POST /api/v1/inventories/{inventory_id}/hosts/
  • PUT /api/v1/inventories/{inventory_id}/hosts/
  • DELETE /api/v1/inventories/{inventory_id}/hosts/
  • POST /api/v1/inventories/{inventory_id}/groups/
  • PUT /api/v1/inventories/{inventory_id}/groups/
  • DELETE /api/v1/inventories/{inventory_id}/groups/

Projects:

  • POST /api/v1/projects/{project_id}/hosts/
  • PUT /api/v1/projects/{project_id}/hosts/
  • DELETE /api/v1/projects/{project_id}/hosts/
  • POST /api/v1/projects/{project_id}/groups/
  • PUT /api/v1/projects/{project_id}/groups/
  • DELETE /api/v1/projects/{project_id}/groups/
  • POST /api/v1/projects/{project_id}/inventories/
  • PUT /api/v1/projects/{project_id}/inventories/
  • DELETE /api/v1/projects/{project_id}/inventories/

As you can see there is a plenty of urls and for every url POST, PUT and DELETE methods are presented. Every method takes list of IDs from json request body, but perform different operations with those IDs. PUT method completely rewrites sublist with new list. POST method just appends 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": []
}

Here not_found is a counter for items, which can’t be processed for some reason. operated is a counter for items processed successfully. total is a number of elements which were in initial request. If some items are not operated successfully, they will be added to failed_list. Otherwise failed_list will be empty.

List of IDs means objects’ IDs 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 this list is not exist, method will still return 200 OK, but result’s stats will reflect the fact, that one of the ids can’t be processed successfully.

To clarify information above there is detailed explanation (with request and response examples) of those methods’ logic:

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

Operates with sublist of objects for some concrete object.

  • POST - appends new objects to already existent sublist.
  • DELETE - removes those objects from existent sublist.
  • PUT - rewrites 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/from 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) – number of items processed with error (not exists or no access).
  • operated (number) – number of items processed successfully.
  • total (number) – number of all sent ids.

Hooks¶

Polemarch has his own system of hooks. Polemarch hooks are synchronous and you can appoint them on different events like “after end task”, “before start task” and so on.

More information about hooks types and events ou can find here GET /api/v1/hooks/types/.

WARNING: You should be accurate with hooks appointment, because the more hooks you have, the more time they need for execution and, finally, the more time Ansible needs for task execution.

GET /api/v1/hooks/¶

Gets hooks list.

Parameters:
  • id – filter by id of hook.
  • id__not – filter by id of hook (except this id).
  • name – filter by name of hook.
  • type – filter by type of hook.

Example request:

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

Results:

{
    {
        "id": 1,
        "name": "test hook on user add",
        "type": "HTTP",
        "when": "on_user_add",
        "recipients": "http://localhost:8000/hook_trigger"
    },
    {
        "id": 2,
        "name": "all hooks",
        "type": "HTTP",
        "when": null,
        "recipients": "http://localhost:8000/hook_trigger_another"
    },
    {
        "id": 3,
        "name": "Script hooks",
        "type": "SCRIPT",
        "when": null,
        "recipients": "test.sh"
    }
}
Response JSON Object:
 
  • id (number) – id of hook.
  • name (string) – name of hook.
  • type (string) – type of hook. For more details look GET /api/v1/hooks/types/.
  • when (string) – type of event on which hook will be executed. If when is null, this hook will be executed for every type of event. For more details look GET /api/v1/hooks/types/.
  • recipients (string) – recipients of hook.
GET /api/v1/hooks/{id}/¶

Gets details about one hook.

Parameters:
  • id – id of hook.

Example request:

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

Results:

{
    "id": 1,
    "name": "test hook on user add",
    "type": "HTTP",
    "when": "on_user_add",
    "recipients": "http://localhost:8000/hook_trigger"
}

Response JSON Object: response json fields are the same as in GET /api/v1/hooks/.

POST /api/v1/hooks/¶

Creates new hook.

Example request:

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

{
    "name": "new hook",
    "type": "SCRIPT",
    "when": "on_execution",
    "recipients": "new-test.sh"
}

Results:

{
   "id": 4,
   "name": "new hook",
   "type": "SCRIPT",
   "when": "on_execution",
   "recipients": "new-test.sh"
}

Response JSON Object: response json fields are the same as in GET /api/v1/hooks/.

If type is SCRIPT and there is no 'new-test.sh' in hooks dir, POST request will return 400 Bad Request.

GET /api/v1/hooks/types/¶

Returns list of supported hook’s types and events.

Example request:

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

Results:

{
    "when": {
        "after_execution": "After end task",
        "on_user_add": "When new user register",
        "on_user_del": "When user was removed",
        "on_execution": "Before start task",
        "on_object_add": "When new Polemarch object was added",
        "on_object_upd": "When Polemarch object was updated",
        "on_object_del": "When Polemarch object was removed",
        "on_user_upd": "When user update data"
    },
    "types": [
        "HTTP",
        "SCRIPT"
    ]
}
Response JSON Object:
 
  • when (string) – type of event on which hook will be executed.
  • types (string) – type of hook. If type is HTTP, hook will send JSON by POST request to url, which is in recipients field of hook. If type is SCRIPT, hook will send a temporery file with JSON to script, name of which is in recipients field of hook.

Token¶

POST /api/v1/token/¶

Creates new token.

Example request:

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

{
   "username": "test-user",
   "password": "password"
}

Results:

{
   "token": "f9e983ef5f67725b60f5a4a1aa0f32912ebe05fb"
}
DELETE /api/v1/token/¶

Deletes token.

Example request:

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

{
   "token": "f9e983ef5f67725b60f5a4a1aa0f32912ebe05fb"
}

Results:

{

}

Users¶

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

Gets 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",
   "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) – if it is true, account is enabled.
  • is_staff (boolean) – if it is true, this user is superuser. Superuser has 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/¶

Gets 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,
         "is_staff": true,
         "url":"http://127.0.0.1:8080/api/v1/users/1/"
      },
      {
         "id":3,
         "username":"petya",
         "is_active":true,
         "is_staff": true,
         "url":"http://127.0.0.1:8080/api/v1/users/3/"
      }
   ]
}

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

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

Deletes user.

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

Creates user.

Request JSON Object:
 
  • username (string) – login.
  • password (string) – password.
  • is_active (boolean) – if it is true, account is enabled.
  • is_staff (boolean) – if it is true, this user is 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",
   "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 are the same as in GET /api/v1/users/{id}/.

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

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

Parameters:
  • id – id of user.

Request JSON Object: request json fields are the 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

{
   "username":"petrusha"
}

Results:

{
   "id":3,
   "username":"petrusha",
   "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 are the same as in GET /api/v1/users/{id}/.

POST /api/v1/users/{id}/settings/¶

Creates user’s view settings of Dashboard’s widgets.

Parameters:
  • id – id of user.

Example request:

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

{
    "chartLineSettings": {
        "ok": {
            "active": true
        },
        "all_tasks": {
            "active": true
        },
        "interrupted": {
            "active": true
        },
        "delay": {
            "active": true
        },
        "error": {
            "active": true
        },
        "offline": {
            "active": true
        }
    },
    "widgetSettings": {
        "pmwTasksTemplatesWidget": {
            "active": false,
            "sortNum": 8,
            "collapse": false
        },
        "pmwUsersCounter": {
            "active": true,
            "sortNum": 5,
            "collapse": false
        },
        "pmwProjectsCounter": {
            "active": true,
            "sortNum": 3,
            "collapse": false
        },
        "pmwHostsCounter": {
            "active": true,
            "sortNum": 0,
            "collapse": false
        },
        "pmwInventoriesCounter": {
            "active": true,
            "sortNum": 2,
            "collapse": false
        },
        "pmwGroupsCounter": {
            "active": true,
            "sortNum": 1,
            "collapse": false
        },
        "pmwChartWidget": {
            "active": true,
            "sortNum": 6,
            "collapse": false
        },
        "pmwModulesTemplatesWidget": {
            "active": false,
            "sortNum": 9,
            "collapse": false
        },
        "pmwTemplatesCounter": {
            "active": true,
            "sortNum": 4,
            "collapse": false
        },
        "pmwAnsibleModuleWidget": {
            "active": true,
            "sortNum": 7,
            "collapse": true
        }
    }
}

Results:

{
     "chartLineSettings": {
         "ok": {
             "active": true
         },
         "all_tasks": {
             "active": true
         },
         "interrupted": {
             "active": true
         },
         "delay": {
             "active": true
         },
         "error": {
             "active": true
         },
         "offline": {
             "active": true
         }
     },
     "widgetSettings": {
         "pmwTasksTemplatesWidget": {
             "active": false,
             "sortNum": 8,
             "collapse": false
         },
         "pmwUsersCounter": {
             "active": true,
             "sortNum": 5,
             "collapse": false
         },
         "pmwProjectsCounter": {
             "active": true,
             "sortNum": 3,
             "collapse": false
         },
         "pmwHostsCounter": {
             "active": true,
             "sortNum": 0,
             "collapse": false
         },
         "pmwInventoriesCounter": {
             "active": true,
             "sortNum": 2,
             "collapse": false
         },
         "pmwGroupsCounter": {
             "active": true,
             "sortNum": 1,
             "collapse": false
         },
         "pmwChartWidget": {
             "active": true,
             "sortNum": 6,
             "collapse": false
         },
         "pmwModulesTemplatesWidget": {
             "active": false,
             "sortNum": 9,
             "collapse": false
         },
         "pmwTemplatesCounter": {
             "active": true,
             "sortNum": 4,
             "collapse": false
         },
         "pmwAnsibleModuleWidget": {
             "active": true,
             "sortNum": 7,
             "collapse": true
         }
     }
}
Response JSON Object:
 
  • chartLineSettings (object) – object with Dashboard chart line settings.
  • active (boolean) – one of Dashboard chart line settings, if active is true, this line will be visible on Dashboard.
  • widgetSettings (object) – object with Dashboard widgets settings.
  • pmw{widget_Name} (string) – widget name.
  • active – one of widget’s settings, if active is true, this widget will be visible on Dashboard.
  • sortNum (number) – one of widget’s settings, it means order number of widget on Dashboard.
  • collapse (boolean) – one of widget’s settings, if collapse is true, this widget will be collapsed on Dashboard.
GET /api/v1/users/{id}/settings/¶

Gets user’s view settings of Dashboard’s widgets.

Parameters:
  • id – id of user.

Example request:

GET /api/v1/users/{id}/settings/ HTTP/1.1
Host: example.com
Accept: application/json, text/javascript

{

}

Results:

{
     "chartLineSettings": {
         "ok": {
             "active": true
         },
         "all_tasks": {
             "active": true
         },
         "interrupted": {
             "active": true
         },
         "delay": {
             "active": true
         },
         "error": {
             "active": true
         },
         "offline": {
             "active": true
         }
     },
     "widgetSettings": {
         "pmwTasksTemplatesWidget": {
             "active": false,
             "sortNum": 8,
             "collapse": false
         },
         "pmwUsersCounter": {
             "active": true,
             "sortNum": 5,
             "collapse": false
         },
         "pmwProjectsCounter": {
             "active": true,
             "sortNum": 3,
             "collapse": false
         },
         "pmwHostsCounter": {
             "active": true,
             "sortNum": 0,
             "collapse": false
         },
         "pmwInventoriesCounter": {
             "active": true,
             "sortNum": 2,
             "collapse": false
         },
         "pmwGroupsCounter": {
             "active": true,
             "sortNum": 1,
             "collapse": false
         },
         "pmwChartWidget": {
             "active": true,
             "sortNum": 6,
             "collapse": false
         },
         "pmwModulesTemplatesWidget": {
             "active": false,
             "sortNum": 9,
             "collapse": false
         },
         "pmwTemplatesCounter": {
             "active": true,
             "sortNum": 4,
             "collapse": false
         },
         "pmwAnsibleModuleWidget": {
             "active": true,
             "sortNum": 7,
             "collapse": true
         }
     }
}
Response JSON Object:
 
  • chartLineSettings (object) – object with Dashboard chart line settings.
  • active (boolean) – one of Dashboard chart line settings, if active is true, this line will be visible on Dashboard.
  • widgetSettings (object) – object with Dashboard widgets settings.
  • pmw{widget_Name} (string) – widget name.
  • active – one of widget’s settings, if active is true, this widget will be visible on Dashboard.
  • sortNum (number) – one of widget’s settings, it means order number of widget on Dashboard.
  • collapse (boolean) – one of widget’s settings, if collapse is true, this widget will be collapsed on Dashboard.
DELETE /api/v1/users/{id}/settings/¶

Deletes user’s view settings of Dashboard’s widgets.

Parameters:
  • id – id of user.

Teams (Polemarch+ only)¶

Team is a group of users to which you can collectively assign rights to objects in ACL system.

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

Gets 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",
    "notes": "some notes about this team",
    "users": [
        {
            "id": 1,
            "username": "admin",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/1/"
        },
        {
            "id": 2,
            "username": "test-user",
            "is_active": true,
            "is_staff": false,
            "url": "http://localhost:8081/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/1/"
}
Response JSON Object:
 
  • id (number) – id of team.
  • name (string) – name of team.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this team was created or something like this.
  • 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/¶

Gets 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 are the same as in GET /api/v1/teams/{id}/.

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

Deletes team.

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

Creates team.

Request JSON Object:
 
  • name (string) – name of new team.
  • notes (string) – not required field for some user’s notes, for example, for what purpose this team was created or something like this.

Example request:

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

{
   "name":"another_team",
   "notes":""
}

Results:

{
    "id": 2,
    "name": "another_team",
    "notes":"",
    "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 are the same as in GET /api/v1/teams/{id}/.

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

Updates 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, 3]
}

Results:

{
    "id": 2,
    "name": "another_team",
    "notes":"",
    "users": [
        {
            "id": 1,
            "username": "admin",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/1/"
        },
        {
            "id": 3,
            "username": "max",
            "is_active": true,
            "is_staff": true,
            "url": "http://localhost:8000/api/v1/users/3/"
        }
    ],
    "users_list": [
        1,
        3
    ],
    "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 are the same as in GET /api/v1/teams/{id}/.

ACL system (Polemarch+ only)¶

Because Polemarch supports multiple users it has access rights for every kind of objects. Most kinds of objects (if to be precise: Hosts, Groups, Inventories, Projects, Templates, Teams (Polemarch+ only) ) 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 have not their own permissions, but permissions of parent objects are 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 - is the same as above + right to edit.
  • MASTER - is the same as above + can work with permissions list for this object (add/delete other users and teams).
  • OWNER - is the same as above + ability to change owner.

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

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

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

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

Gets permissions to object.

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

Example request:

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

Results:

[
   {
      "member":2,
      "role":"EXECUTOR",
      "member_type":"user"
   }
]
Response JSON Object:
 
  • permissions (array) – list of permissions. Permission JSON Object: json fields are the same as in POST /api/v1/{object_kind}/{id}/permissions/.
POST /api/v1/{object_kind}/{id}/permissions/¶

Adds those permissions to object.

Parameters:
  • object_kind – kind of objects to perform operation. It can be one of any presented object type in system: hosts, groups, inventories, projects, templates, teams.
  • 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/teams/1/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 the same object as in request, so you can look request fields explanation for details.
PUT /api/v1/{object_kind}/{id}/permissions/¶

Replaces permissions to object with provided.

Parameters:
  • object_kind – kind of objects to perform operation. It can be one of any presented object type in system: hosts, groups, inventories, projects, templates, teams.
  • id – Id of object.
Request JSON Object:
 
  • permissions (array) – new permissions list. Permission JSON Object: json fields are the same as in POST /api/v1/{object_kind}/{id}/permissions/.
PUT /api/v1/teams/1/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. Permission JSON Object: json fields are the same as in POST /api/v1/{object_kind}/{id}/permissions/.
DELETE /api/v1/{object_kind}/{id}/permissions/¶

Removes access to object for users, which are listed in json array in request’s body.

Parameters:
  • object_kind – kind of objects to perform operation. It can be one of any presented object type in system: hosts, groups, inventories, projects, templates, teams.
  • id – id of object.
Request JSON Object:
 
  • permissions (array) – which permissions should be removed. You can use PUT with empty list if you want to remove all permissions. Permission JSON Object: json fields are the same as in POST /api/v1/{object_kind}/{id}/permissions/.

Example request:

DELETE /api/v1/teams/1/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:

[]
Response JSON Object:
 
  • permissions (array) – list of actual object permissions after operation. Permission JSON Object: json fields are the same as in POST /api/v1/{object_kind}/{id}/permissions/.
PUT /api/v1/{object_kind}/{id}/owner/¶

Changes owner of object.

Parameters:
  • object_kind – kind of objects to perform operation. It can be one of any presented object type in system: hosts, groups, inventories, projects, templates, teams.
  • id – Id of object.
JSON Parameters:
 
  • id (number) – id of user.

Example request:

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

  2

Results:

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

Gets owner of object.

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

Example request:

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

Results:

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

License (Polemarch+ only)¶

GET /api/v1/license/¶

Gets 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 are available with this license. If null - unlimited.
  • organization (string) – to whom this license is provided.
  • contacts (string) – license owner’s contact information .
  • hosts (number) – number of hosts which are available with this license. If null - unlimited.
  • actual_hosts (number) – how many hosts are (RANGE calculates appropriately) currently in system.
  • actual_users (number) – how many users are currently in system.
© 2018, VST Consulting