Chapter 2. Reference Guide
2.1. Authentication
| Type | Mechanism |
|---|---|
| Basic Authentication | Basic HTTP Authorization with user and password |
| Token Based Authentication | |
| - Acquiring Token | /api/auth with Basic Authentication |
| - Authenticating with Token | X-Auth-Token Header |
2.2. HTTP Headers
| Header | Value |
|---|---|
| Authorization | Basic base64_encoded(user:password) |
| X-Auth-Token | Token provided by /api/auth |
| Accept | application/json |
| Content-Type | application/json |
2.3. Listing and Querying Collections and Sub-Collections
| Feature | Path |
|---|---|
| Listing Available Collections | /api |
| Listing Collections | /api/<collection> |
| Listing Sub-Collections | /api/<collection>/<id>/<sub-collection> |
| Querying Capability | Query Parameters |
|---|---|
| Paging | offset, limit |
| Sorting | sort_by=attr, sort_order=asc|desc |
| Filtering | filter[]="…" |
| Querying by Tag | i.e. by_tag=/department/finance |
| Expanding Results | expand=<what>, i.e. expand=resources,tags,service_templates,… |
| Selecting Attributes | attributes=<attr1>,<attr2>,… i.e. attributes=id,name,type,… |
| Attributes can be: | |
| Database columns | |
| Virtual attributes | |
| Relationships |
2.4. Collection Queries
| Collection | URL |
|---|---|
| Automation Requests | /api/automation_requests |
| Availability Zones | /api/availability_zones |
| Clusters | /api/clusters |
| Conditions | /api/conditions |
| Datastores | /api/data_stores |
| Events | /api/events |
| Flavors | /api/flavors |
| Groups | /api/groups |
| Hosts | /api/hosts |
| Policies | /api/policies |
| Actions | /api/policy_actions |
| Policy Profiles | /api/policy_profiles |
| Providers | /api/providers |
| Provision Requests | /api/provision_requests |
| Request Tasks | /api/request_tasks |
| Requests | /api/requests |
| Resource Pools | /api/resource_pools |
| Roles | /api/roles |
| Security Groups | /api/security_groups |
| EVM Servers | /api/servers |
| Service Catalogs | /api/service_catalogs |
| Service Requests | /api/service_requests |
| Service Templates | /api/service_templates |
| Services | /api/services |
| Tags | /api/tags |
| Tasks | /api/tasks |
| Templates | /api/templates |
| Users | /api/users |
| Vms | /api/vms |
| Zones | /api/zones |
For example queries, see "Queries".
2.5. Sub-Collection Queries
| Sub-Collection | URL |
|---|---|
| Tagging | /api/<collection>/:id/tags |
| Policies | /api/<collection>/:id/policies |
| Policy Profiles | /api/<collection>/:id/policy_profiles |
| Service Requests | /api/service_templates/:id/service_requests |
| Request Tasks | |
| /api/service_requests/:id/request_tasks | |
| /api/automation_requests/:id/request_tasks | |
| /api/provision_requests/:id/request_tasks | |
| Request Tasks can also be accessed via the tasks alias | |
| /api/service_requests/:id/tasks | |
| /api/automation_requests/:id/tasks | |
| /api/provision_requests/:id/tasks |
2.6. Available Actions
| Action | Method | URL | Example |
|---|---|---|---|
| Add Service Catalog | POST | /api/service_catalogs | |
| Add Service Catalogs | POST | /api/service_catalogs | |
| Edit Service Catalog | POST | /api/service_catalogs/<replaceable>id</replaceable> | |
| Edit Service Catalogs | POST | /api/service_catalogs | |
| Automation Request | POST | /api/automation_requests | |
| Automation Requests | POST | /api/automation_requests | |
| Edit Service | POST | /api/services/<replaceable>id</replaceable> | |
| Edit Service via PUT | PUT | /api/services/<replaceable>id</replaceable> | |
| Edit Service via PATCH | PATCH | /api/services/<replaceable>id</replaceable> | |
| Edit Services | POST | /api/services/ | |
| Assign Tags to a Service | POST | /api/services/<replaceable>id</replaceable>/tags | |
| Assign a Tag by Name to a Service | POST | /api/services/<replaceable>id</replaceable>/tags | |
| Assign a Tag by Name to a Service | POST | /api/services/<replaceable>id</replaceable>/tags | |
| Unassign Tags from Service | POST | /api/services/<replaceable>id</replaceable>/tags | |
| Retire Service Now | POST | /api/services/<replaceable>id</replaceable> | |
| Retire Service in Future | POST | /api/services/<replaceable>id</replaceable> | |
| Retire Services | POST | /api/services | |
| Delete Service | DELETE | /api/services/<replaceable>id</replaceable> | |
| Delete Services | POST | /api/services | |
| Edit Service Template | POST | /api/service_templates/<replaceable>id</replaceable> | |
| Edit Service Templates | POST | /api/service_templates | |
| Assign Tags to Service Template | POST | /api/service_templates/<replaceable>id</replaceable>/tags | |
| Unassign Tags from Service Template | POST | /api/service_templates/<replaceable>id</replaceable>/tags | |
| Delete Service Template | DELETE | /api/service_templates/<replaceable>id</replaceable> | |
| Delete Service Templates | POST | /api/service_templates | |
| Assign Service Templates | POST | /api/service_catalogs/<replaceable>id</replaceable>/service_templates | |
| Unassign Service Templates | POST | /api/service_catalogs/<replaceable>id</replaceable>/service_templates | |
| Order Service | POST | /api/service_catalogs/<replaceable>id</replaceable>/service_templates | |
| Order Services | POST | /api/service_catalogs/<replaceable>id</replaceable>/service_templates | |
| Delete Service Catalog | DELETE | /api/service_catalogs/<replaceable>id</replaceable> | |
| Delete Service Catalogs | POST | /api/service_catalogs | |
| Provision Request | POST | /api/provision_requests | |
| Provision Requests | POST | /api/provision_requests | |
| Create a Provider | POST | /api/providers | |
| Create a Provider with Compound Credentials | POST | /api/providers | |
| Edit a Provider | POST | /api/providers | |
| Update a Provider | POST | /api/providers | |
| Delete a Provider | POST | /api/providers | |
| Delete Multiple Providers | POST | /api/providers | |
| Refresh a Provider | POST | /api/providers | |
| Scan a VM | POST | /api/vms | |
| Set Owner of a VM | POST | /api/vms | |
| Add a Lifecycle Event to a VM | POST | /api/vms | |
| Add an Event to a VM | POST | /api/vms | |
| Start a VM | POST | /api/vms | |
| Stop a VM | POST | /api/vms | |
| Suspend a VM | POST | /api/vms | |
| Delete VMs | DELETE | /api/vms |
2.7. Provisioning Request Attributes
2.7.1. Provisioning Request Attribute Groups
| Attribute Group | Type | Description |
|---|---|---|
| version | string | Interface version. Defaults to 1.1 |
| template_fields | hash | Fields used to find the template virtual machine. Provide any or all fields. Supply a guid or ems_guid to protect against matching same-named templates on different Providers within the appliance. Supported fields are: name=[VM Template Name] Example: template_1 guid=[guid value from vms resource] ems_guid=[uid_ems value from vms resource] |
| vm_fields | hash | Allows for setting properties on the Service Catalog, Hardware, Network, Customize, and Schedule tabs in the Provisioning dialog. |
| requester | hash | Allows for the setting of properties on the Requester tab in the Provisioning dialog. |
| tags | hash | Tags to apply to newly created virtual machine. Example: network_location=Internal cc=001 |
| additional_values | hash | Additional values are name-value pairs stored with a provision request, but not used by the core provisioning code. These values are usually referenced from automate methods for custom processing. Example: Store a request_id from an external system so the system can be notified during the provisioning process. |
| ems_custom_attributes | hash | Custom attributes applied to the virtual machine through the Provider as part of provisioning. |
| miq_custom_attributes | hash | Custom attributes applied to the virtual machine and stored in the database as part of provisioning. |
2.7.2. Service Catalog Attributes
These attributes are used in the vm_fields attribute group:
| Attribute | Type | Description | Default |
|---|---|---|---|
| number_of_vms | integer | Number of virtual machines - maximum 50 | 1 |
| vm_description | string | Virtual machine description - maximum 100 characters | |
| vm_prefix | string | Virtual machine name prefix or suffix | |
| src_vm_id | integer | Name | |
| vm_name | string | Virtual machine name | |
| pxe_image_id | string | Image | |
| pxe_server_id | integer | Server | |
| host_name | string | Host name | |
| provision_type | string | Provision type | vmware |
| linked_clone | boolean | Linked clone | false |
| snapshot | string | Snapshot | |
| vm_filter | integer | Filter |
2.7.3. Hardware Attributes
These attributes are used in the vm_fields attribute group:
| Attribute | Type | Description | Values | Default |
|---|---|---|---|---|
| disk_format | string | Disk format | thick, thin, unchanged | unchanged |
| cpu_limit | integer | CPU (MHz) | ||
| memory_limit | integer | Memory (MB) | ||
| number_of_sockets | integer | Number of sockets | 1, 2, 4, 8 | 1 |
| cores_per_socket | integer | Cores per socket | 1, 2, 4, 8 | 1 |
| cpu_reserve | integer | CPU (MHz) | ||
| vm_memory | string | Memory (MB) | 1024, 2048, 4096 | 1024 |
| memory_reserve | integer | Memory (MB) | ||
| network_adapters | integer | Network adapters | 1, 2, 3, 4 | 1 |
2.7.4. Network Attributes
These attributes are used in the vm_fields attribute group:
| Attribute | Type | Description |
|---|---|---|
| vlan | string | vLAN |
| mac_address | string | MAC address |
2.7.5. Custom Attributes
These attributes are used in the vm_fields attribute group:
| Attribute | Type | Description | Values | Default |
|---|---|---|---|---|
| dns_servers | string | DNS server list | ||
| sysprep_organization | string | Organization | ||
| sysprep_password | string | New administrator password | ||
| sysprep_custom_spec | string | Name | ||
| sysprep_server_license_mode | string | Identification | perServer, perSeat | |
| ldap_ous | string | LDAP group | ||
| sysprep_timezone | string | Timezone | ||
| dns_suffixes | string | DNS suffix list | ||
| sysprep_product_id | string | ProductID | ||
| sysprep_identification | string | Identification | domain, workgroup | |
| sysprep_per_server_max_connections | string | Maximum connections | 5 | |
| sysprep_computer_name | string | Computer name | ||
| sysprep_workgroup_name | string | Workgroup name | WORKGROUP | |
| sysprep_spec_override | boolean | Override specification | false | |
| addr_mode | string | Address mode | static, dhcp | dhcp |
| linux_host_name | string | Computer name | ||
| sysprep_domain_admin | string | Domain admin | ||
| sysprep_change_sid | boolean | Change SID | true | |
| sysprep_domain_name | string | Domain name | ||
| sysprep_upload_file | string | Upload | ||
| gateway | string | Gateway | ||
| ip_addr | string | IP address | ||
| linux_domain_name | string | Domain name | ||
| sysprep_domain_password | string | Domain password | ||
| sysprep_auto_logon | boolean | Auto Logon | true | |
| sysprep_enabled | string | Customize | disabled | |
| sysprep_delete_accounts | boolean | Delete accounts | false | |
| sysprep_upload_text | string | Sysprep text | ||
| wins_servers | string | WINS server list | ||
| subnet_mask | string | Subnet mask | ||
| sysprep_full_name | string | Full name | ||
| sysprep_auto_logon_count | integer | Auto logon count | 1, 2, 3 | 1 |
| customization_template_id | integer | Script name | ||
| root_password | string | Root password | ||
| hostname | string | Host name | ||
| customization_template_script | string | Script text |
2.7.6. Schedule Attributes
These attributes are used in the vm_fields attribute group:
| Attribute | Type | Description | Values | Default |
|---|---|---|---|---|
| schedule_type | string | When to provision | schedule, immediately (On Approval) | immediately |
| vm_auto_start | boolean | Power on virtual machines after creation | true | |
| schedule_time | time | Time to provision on | ||
| retirement | integer | Time until retirement | 0 (Indefinite), 1.month, 3.months, 6.months | 0 |
| retirement_warn | integer | Retirement warning | 1.week, 2.weeks, 30.days | 1.week |
2.7.7. Requester Attributes
These attributes are used in the requester attribute group:
| Attribute | Type | Description |
|---|---|---|
| owner_phone | string | Phone |
| owner_country | string | Country/Region |
| owner_phone_mobile | string | Mobile phone |
| owner_title | string | Title |
| owner_first_name | string | First name |
| owner_manager | string | Manager name |
| owner_address | string | Address |
| owner_company | string | Company |
| owner_last_name | string | Last name |
| owner_manager_email | string | Manager e-mail address |
| owner_city | string | City |
| owner_department | string | Department |
| owner_load_ldap | button | Look up LDAP e-mail address |
| owner_manager_phone | string | Manager phone |
| owner_state | string | State |
| owner_office | string | Office |
| owner_zip | string | Zip code |
| owner_email | string | |
| request_notes | string | Notes |
2.7.8. Environment Attributes
These attributes cannot be passed directly. To use these attributes, provide additional_values and allow customization methods to use these attributes, then modify the request accordingly.
| Attribute | Type | Description | Values | Default |
|---|---|---|---|---|
| new_datastore_grow_increment | integer | Grow increment (GB) | ||
| new_datastore_create | boolean | Create datastore | false | |
| placement_cluster_name | integer | Name | ||
| new_datastore_aggregate | string | Aggregate | ||
| new_datastore_max_size | integer | Max size (GB) | ||
| new_datastore_storage_controller | string | Controller | ||
| cluster_filter | integer | Filter | ||
| host_filter | integer | Filter | ||
| ds_filter | integer | Filter | ||
| new_datastore_volume | string | Volume | ||
| placement_host_name | integer | Name | ||
| placement_ds_name | integer | Name | ||
| new_datastore_fs_type | string | FS Type | NFS, VMFS | NFS |
| rp_filter | integer | Filter | ||
| new_datastore_thin_provision | string | Thin provision | ||
| placement_auto | boolean | Choose automatically | false | |
| new_datastore_size | integer | Size (GB) | ||
| new_datastore_autogrow | string | Autogrow | false | |
| placement_folder_name | integer | Name | ||
| new_datastore_name | string | Name | ||
| placement_rp_name | integer | Name | ||
| placement_dc_name | integer | Name |

Where did the comment section go?
Red Hat's documentation publication system recently went through an upgrade to enable speedier, more mobile-friendly content. We decided to re-evaluate our commenting platform to ensure that it meets your expectations and serves as an optimal feedback mechanism. During this redesign, we invite your input on providing feedback on Red Hat documentation via the discussion platform.