Browse the REST API

Ensure that any special characters in the specified value are URL-encoded. For example:

?field=value%20xyz

Fields can also span relations, only for fields and relationships defined in the database:

?other__field=value

To exclude results matching certain criteria, prefix the field parameter with not__:

?not__field=value

By default, all query string filters are AND’ed together, so only the results matching all filters are returned. To combine results matching any one of multiple criteria, prefix each query string parameter with or__:

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

The default AND filtering applies all filters simultaneously to each related object being filtered across database relationships. The chain filter instead applies filters separately for each related object. To use this, prefix the query string parameter with chain__:

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

If you write the first query as ?relatedfield=value&relatedfield2=othervalue, it returns only the primary objects where the same related object satisfied both conditions. As written by using the chain filter, it would return the intersection of primary objects matching each condition.

?field__lookup=value

The following field lookups are supported:

• exact: Exact match (default lookup if not specified, see the following note for more information).
• iexact: Case-insensitive version of exact.
• contains: Field contains value.
• icontains: Case-insensitive version of contains.
• startswith: Field starts with value.
• istartswith: Case-insensitive version of startswith.
• endswith: Field ends with value.
• iendswith: Case-insensitive version of endswith.
• regex: Field matches the given regular expression.
• iregex: Case-insensitive version of regular expression.
• gt: Greater than comparison.
• gte: Greater than or equal to comparison.
• lt: Less than comparison.
• lte: Less than or equal to comparison.
• isnull: Check whether the given field or related object is null; expects a boolean value.
• in: Check whether the given field’s value is present in the list provided; expects a list of items.
• You can specify boolean values as True or 1 for true, False or 0 for false (both case-insensitive).

For example, ?created__gte=2023-01-01 provides a list of items created after 1/1/2023.

You can specify null values as None or Null (both case-insensitive), though we recommend using the isnull lookup to explicitly check for null values.

You can specify lists (for the in lookup) as a comma-separated list of values. Filtering based on the requesting user’s level of access by query string parameter:

• role_level: Level of role to filter on, such as admin_role

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...

NAMED_URL_FORMATS is a read only key-value pair list of all available named URL identifier formats. The following shows an example NAMED_URL_FORMATS:

"NAMED_URL_FORMATS": {
"organizations": "<name>",
"teams": "<name>++<organization.name>",
"credential_types": "<name>+<kind>",
"credentials": "<name>++<credential_type.name>+<credential_type.kind>++<organization.name>",
"notification_templates": "<name>++<organization.name>",
"job_templates": "<name>++<organization.name>",
"projects": "<name>++<organization.name>",
"inventories": "<name>++<organization.name>",
"hosts": "<name>++<inventory.name>++<organization.name>",
"groups": "<name>++<inventory.name>++<organization.name>",
"inventory_sources": "<name>++<inventory.name>++<organization.name>",
"inventory_scripts": "<name>++<organization.name>",
"instance_groups": "<name>",
"labels": "<name>++<organization.name>",
"workflow_job_templates": "<name>++<organization.name>",
"workflow_job_template_nodes": "<identifier>++<workflow_job_template.name>++<organization.name>",
"applications": "<name>++<organization.name>",
"users": "<username>",
"instances": "<hostname>"
}

For each item in NAMED_URL_FORMATS, the key is the API name of the resource to have named URL. The value is a string indicating how to form a human-readable unique identifier for that resource. NAMED_URL_FORMATS only lists the resources that can have named URL, any resource not listed there has no named URL. If a resource can have named URL, its objects must have a named_url field that represents the object-specific named URL. That field is only visible under detail view, not list view. You can access specified resource objects by using accurately generated named URL. This the object and its related URLs. For example, if /api/controller/v2/res_name/obj_slug/ is valid, /api/controller/v2/res_name/obj_slug/related_res_name/ is also valid.

NAMED_URL_FORMATS are instructive enough to compose human-readable unique identifiers and named URLs themselves. For ease-of-use, every object of a resource that can have named URL has a related field named_url that displays that object’s named URL. You can copy and paste that field for your own custom use. For more information, see the help text of the API browser if a resource object has named URL.

You can manually decide the named URL label, for example with ID 5. To compose a named URL for this specific resource object by using NAMED_URL_FORMATS, first look up the labels field of NAMED_URL_FORMATS to get the identifier format <name>++<organization.name>:

• The first part of the URL format is <name>, which indicates that you can find the label resource detail in /api/controller/v2/labels/5/, and look for name field in returned JSON. If you have the name field with value Foo, then the first part of the unique identifier is Foo.
• The second part of the format is double plus sign ++. That is the delimiter that separates different parts of a unique identifier. Append them to the unique identifier to get Foo++.
• The third part of the format is <organization.name>, which indicates that the field is not in the current label object under investigation, but in an organization that the label object points to. As the format indicates, look up the organization in the related field of the current returned JSON. That field might not exist. If it exists, follow the URL given in that field, for example, /api/gateway/v1/organizations/3/, to get the details of the specific organization, extract its name field, for example, "Default", and append it to the current unique identifier. Since <organizations.name> is the last part of the format, it generates the following named URL: /api/controller/v2/labels/Foo++Default/.

  In the case where an organization does not exist in the related field of the label object detail, append an empty string instead. This does not alter the current identifier. Therefore, Foo++ becomes the final unique identifier and the resulting generated named URL becomes /api/controller/v2/labels/Foo++/.

An important aspect of generating a unique identifier for named URL has to do with reserved characters. As the identifier is part of a URL, the following reserved characters by URL standard are encoded by percentage symbols: ;/?:@=&[]. For example, if an organization is named ;/?:@=&[], its unique identifier should be %3B%2F%3F%3A%40%3D%26%5B%5D. Another special reserved character is `, which is not reserved by URL standard but used by named URL to link different parts of an identifier. It is encoded by `[]. For example, if an organization is named []`, its unique identifier is `%5B[]%5D, where original [ and ] are percent encoded and ` is converted to `[].

Although you cannot manually change NAMED_URL_FORMATS, modifications do occur automatically and expand over time, reflecting underlying resource modification and expansion. Consult the NAMED_URL_FORMATS on the same cluster where you want to use the named URL feature.

NAMED_URL_GRAPH_NODES is another read-only list of key-value pairs that exposes the internal graph data structure used to manage named URLs. This is not intended to be human-readable but must be used for programmatically generating named URLs. An example script for generating named URL given the primary key of arbitrary resource objects that can have a named URL, using info provided by NAMED_URL_GRAPH_NODES, can be found in GitHub.