Documentation

Project List API Endpoint

Make a GET request to this resource to retrieve the list of projects.

GET /api/v2/projects/
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
X-API-Node: localhost
X-API-Time: 0.149s

The resulting data structure contains:

{
    "count": 99,
    "next": null,
    "previous": null,
    "results": [
        ...
    ]
}

The count field indicates the total number of projects found for the given query. The next and previous fields provides links to additional results if there are more than will fit on a single page. The results list contains zero or more project records.

Results

Each project data structure includes the following fields:

  • id: Database ID for this project. (integer)
  • type: Data type for this project. (choice)
    • project: Project
  • url: URL for this project. (string)
  • related: Data structure with URLs of related resources. (object)
  • summary_fields: Data structure with name/description for related resources. (object)
  • created: Timestamp when this project was created. (datetime)
  • modified: Timestamp when this project was last modified. (datetime)
  • name: Name of this project. (string)
  • description: Optional description of this project. (string)
  • local_path: Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project. (string)
  • scm_type: Specifies the source control system used to store the project. (choice)
    • "": Manual
    • git: Git
    • hg: Mercurial
    • svn: Subversion
    • insights: Red Hat Insights
  • scm_url: The location where the project is stored. (string)
  • scm_branch: Specific branch, tag or commit to checkout. (string)
  • scm_clean: Discard any local changes before syncing the project. (boolean)
  • scm_delete_on_update: Delete the project before syncing. (boolean)
  • credential: (field)
  • timeout: The amount of time (in seconds) to run before the task is canceled. (integer)
  • last_job_run: (datetime)
  • last_job_failed: (boolean)
  • next_job_run: (datetime)
  • status: (choice)
    • new: New
    • pending: Pending
    • waiting: Waiting
    • running: Running
    • successful: Successful
    • failed: Failed
    • error: Error
    • canceled: Canceled
    • never updated: Never Updated
    • ok: OK
    • missing: Missing
  • organization: (field)
  • scm_delete_on_next_update: (boolean)
  • scm_update_on_launch: Update the project when a job is launched that uses the project. (boolean)
  • scm_update_cache_timeout: The number of seconds after the last project update ran that a new project update will be launched as a job dependency. (integer)
  • scm_revision: The last revision fetched by a project update. (string)
  • last_update_failed: (boolean)
  • last_updated: (datetime)

Sorting

To specify that projects are returned in a particular order, use the order_by query string parameter on the GET request.

?order_by=name

Prefix the field name with a dash - to sort in reverse:

?order_by=-name

Multiple sorting fields may be specified by separating the field names with a comma ,:

?order_by=name,some_other_field

Searching

Use the search query string parameter to perform a case-insensitive search within all designated text fields of a model.

?search=findme

Search across related fields (added in AWX 1.4 / Ansible Tower 3.1):

?related__search=findme

Filtering

Any additional query string parameters may be used to filter the list of results returned to those matching a given value. Only fields and relations that exist in the database may be used for filtering. Any special characters in the specified value should be URL-encoded. For example:

?field=value%20xyz

Fields may 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 will be returned (added in AWX 1.4). 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 (added in Ansible Tower 1.4.5). The chain filter instead applies filters separately for each related object. To use, 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 the first query above were written as ?related__field=value&related__field2=othervalue, it would return only the primary objects where the same related object satisfied both conditions. As written using the chain filter, it would return the intersection of primary objects matching each condition.

Field lookups may also be used for more advanced queries, by appending the lookup to the field name:

?field__lookup=value

The following field lookups are supported:

  • exact: Exact match (default lookup if not specified).
  • 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 regex.
  • 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.

Boolean values may be specified as True or 1 for true, False or 0 for false (both case-insensitive).

Null values may be specified as None or Null (both case-insensitive), though it is preferred to use the isnull lookup to explicitly check for null values.

Lists (for the in lookup) may be specified as a comma-separated list of values.

Filtering based on the requesting user’s level of access by query string parameter (added in Ansible Tower 3.1).

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

Create Projects

Make a POST request to this resource with the following project fields to create a new project:

  • name: (string, required)
  • description: (string, default=””)
  • local_path: Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project. (string, default=””)
  • scm_type: (choice)
    • "": Manual (default)
    • git: Git
    • hg: Mercurial
    • svn: Subversion
  • scm_url: (string, default=””)
  • scm_branch: Specific branch, tag or commit to checkout. (string, default=””)
  • scm_clean: (boolean, default=False)
  • scm_delete_on_update: (boolean, default=False)
  • credential: (field, default=None)
  • timeout: The amount of time (in seconds) to run before the task is canceled. (integer, default=0)
  • organization: (field)
  • scm_update_on_launch: (boolean, default=False)
  • scm_update_cache_timeout: (integer, default=0)

Reviewing the Options Endpoint

The Options Endpoint table offers a view of the Options for this endpoint. When viewing the endpoint in the browsable API, clicking the “Options” button gives you the raw JSON for the following:

name Project List
description # List Projects: Make a GET request to this resource to retrieve the list of projects.
renders
0 application/json
1 text/html
parses
0 application/json
added_in_version 1.2
actions
POST
name
type string
required
true
label Name
max_length 512
help_text Name of this project.
description
type string
required
false
label Description
help_text Optional description of this project.
default (Empty Text)
local_path
type string
required
false
label Local path
help_text Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.
max_length 1024
scm_type
type choice
required
false
label SCM Type
help_text Specifies the source control system used to store the project.
default (Empty Text)
choices
0
0 (Empty Text)
1 Manual
1
0 git
1 Git
2
0 hg
1 Mercurial
3
0 svn
1 Subversion
4
0 insights
1 Red Hat Insights
scm_url
type string
required
false
label SCM URL
help_text The location where the project is stored.
max_length 1024
default (Empty Text)
scm_branch
type string
required
false
label SCM Branch
help_text Specific branch, tag or commit to checkout.
max_length 256
default (Empty Text)
scm_clean
type boolean
required
false
label Scm clean
help_text Discard any local changes before syncing the project.
default
false
scm_delete_on_update
type boolean
required
false
label Scm delete on update
help_text Delete the project before syncing.
default
false
credential
type field
required
false
label Credential
timeout
type integer
required
false
label Timeout
help_text The amount of time (in seconds) to run before the task is canceled.
min_value
-2147483648
max_value
2147483647
default
0
organization
type field
required
false
label Organization
scm_update_on_launch
type boolean
required
false
label Scm update on launch
help_text Update the project when a job is launched that uses the project.
default
false
scm_update_cache_timeout
type integer
required
false
label Scm update cache timeout
help_text The number of seconds after the last project update ran that a new project update will be launched as a job dependency.
min_value
0
max_value
2147483647
default 0
GET
id
type integer
label ID
help_text Database ID for this project.
type
type choice
label Type
help_text Data type for this project.
choices
0
0 project
1 Project
url
type string
label Url
help_text URL for this project.
related
type object
label Related
help_text Data structure with URLs of related resources.
summary_fields
type object
label Summary fields
help_text Data structure with name/description for related resources.
created
type datetime
label Created
help_text Timestamp when this project was created.
modified
type datetime
label Modified
help_text Timestamp when this project was last modified.
name
type string
label Name
help_text Name of this project.
description
type string
label Description
help_text Optional description of this project.
local_path
type string
label Local path
help_text Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.
scm_type
type choice
label SCM Type
choices
0
0 (Empty Text)
1 Manual
1
0 git
1 Git
2
0 hg
1 Mercurial
3
0 svn
1 Subversion
4
0 insights
1 Red Hat Insights
scm_url
type string
label SCM URL
help_text The location where the project is stored.
scm_branch
type string
label SCM Branch
help_text Specific branch, tag or commit to checkout.
scm_clean
type boolean
label Scm clean
help_text Discard any local changes before syncing the project.
scm_delete_on_update
type boolean
label Scm delete on update
help_text Delete the project before syncing.
credential
type field
label Credential
timeout
type integer
label Timeout
help_text The amount of time (in seconds) to run before the task is canceled.
min_value
-2147483648
max_value
2147483647
last_job_run
type datetime
label Last job run
last_job_failed
type boolean
label Last job failed
next_job_run
type datetime
label Next job run
status
type choice
label Status
choices
0
0 new
1 New
1
0 pending
1 Pending
2
0 waiting
1 Waiting
3
0 running
1 Running
4
0 successful
1 Successful
5
0 failed
1 Failed
6
0 error
1 Error
7
0 canceled
1 Canceled
8
0 never updated
1 Never Updated
9
0 ok
1 OK
10
0 missing
1 Missing
organization
type field
label Organization
scm_delete_on_next_update
type boolean
label Scm delete on next update
scm_update_on_launch
type boolean
label Scm update on launch
help_text Update the project when a job is launched that uses the project.
scm_update_cache_timeout
type integer
label Scm update cache timeout
help_text The number of seconds after the last project update ran that a new project update will be launched as a job dependency.
min_value
0
max_value
2147483647
scm_revision
type string
label SCM Revision
help_text The last revision fetched by a project update.
last_update_failed
type boolean
label Last update failed
last_updated
type datetime
label Last updated
types
0 project
search_fields
0 description
1 name

Copyright © 2018 Red Hat, Inc.

Red Hat Ansible Tower docs are generated using Sphinx using a theme provided by Read the Docs.