Jump to

• Request
• Response

List Projects

get

/api/v2/projects/

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

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)
• 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. The output for some objects may be limited for performance reasons. (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
  • svn: Subversion
  • insights: Red Hat Insights
  • archive: Remote Archive
• scm_url: The location where the project is stored. (string)
• scm_branch: Specific branch, tag or commit to checkout. (string)
• scm_refspec: For git projects, an additional refspec to fetch. (string)
• scm_clean: Discard any local changes before syncing the project. (boolean)
• scm_track_submodules: Track submodules latest commits on defined branch. (boolean)
• scm_delete_on_update: Delete the project before syncing. (boolean)
• credential: (id)
• timeout: The amount of time (in seconds) to run before the task is canceled. (integer)
• scm_revision: The last revision fetched by a project update (string)
• 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: The organization used to determine access to this template. (id)
• 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)
• allow_override: Allow changing the SCM branch or revision in a job template that uses this project. (boolean)
• custom_virtualenv: Local absolute file path containing a custom Python virtualenv to use (string)
• default_environment: The default execution environment for jobs run using this project. (id)
• signature_validation_credential: An optional credential used for validating files in the project against unexpected changes. (id)
• 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

Pagination

Use the page_size query string parameter to change the number of results returned for each request. Use the page query string parameter to retrieve a particular page of results.

?page_size=100&page=2

The previous and next links returned with the results will set these query string parameters automatically.

Searching

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

?search=findme

(Added in Ansible Tower 3.1.0) Search across related fields:

?related__search=findme

Request

Supported Media Types

• application/json

Query Parameters

• page: integer
  A page number within the paginated result set.
• page_size: integer
  Number of results to return per page.
• search: string
  A search term.

Back to Top

Response

Supported Media Types

• application/json

200 Response

Body ()

Root Schema : schema

Type: object

Show Source

• count(required): integer
• next: string(uri)
• previous: string(uri)
• results(required): array results

{
    "properties":{
        "count":{
            "type":"integer"
        },
        "next":{
            "format":"uri",
            "type":"string",
            "x-nullable":true
        },
        "previous":{
            "format":"uri",
            "type":"string",
            "x-nullable":true
        },
        "results":{
            "items":{
                "$ref":"#/definitions/Project"
            },
            "type":"array"
        }
    },
    "required":[
        "count",
        "results"
    ],
    "type":"object"
}

Nested Schema : results

Type: array

Show Source

• Array of: object Project

{
    "items":{
        "$ref":"#/definitions/Project"
    },
    "type":"array"
}

Nested Schema : Project

Type: object

Show Source

• allow_override: boolean
  Title: Allow override

  Allow changing the SCM branch or revision in a job template that uses this project.
• created: string
  Title: Created

  Read Only: true
• credential: integer
  Title: Credential
• custom_virtualenv: string
  Title: Custom virtualenv

  Read Only: true

  Minimum Length: 1

  Local absolute file path containing a custom Python virtualenv to use
• default_environment: integer
  Title: Default environment

  The default execution environment for jobs run using this project.
• description: string
  Title: Description
• id: integer
  Title: ID

  Read Only: true
• last_job_failed: boolean
  Title: Last job failed

  Read Only: true
• last_job_run: string(date-time)
  Title: Last job run

  Read Only: true
• last_update_failed: boolean
  Title: Last update failed

  Read Only: true
• last_updated: string(date-time)
  Title: Last updated

  Read Only: true
• local_path: string
  Title: Local path

  Maximum Length: 1024

  Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.
• modified: string
  Title: Modified

  Read Only: true
• name(required): string
  Title: Name

  Minimum Length: 1

  Maximum Length: 512
• next_job_run: string(date-time)
  Title: Next job run

  Read Only: true
• organization: integer
  Title: Organization

  The organization used to determine access to this template.
• related: string
  Title: Related

  Read Only: true
• scm_branch: string
  Title: SCM Branch

  Maximum Length: 256

  Specific branch, tag or commit to checkout.
• scm_clean: boolean
  Title: Scm clean

  Discard any local changes before syncing the project.
• scm_delete_on_update: boolean
  Title: Scm delete on update

  Delete the project before syncing.
• scm_refspec: string
  Title: SCM refspec

  Maximum Length: 1024

  For git projects, an additional refspec to fetch.
• scm_revision: string
  Title: SCM Revision

  Read Only: true

  Minimum Length: 1

  The last revision fetched by a project update
• scm_track_submodules: boolean
  Title: Scm track submodules

  Track submodules latest commits on defined branch.
• scm_type: string
  Title: SCM Type

  Allowed Values: [ "", "git", "svn", "insights", "archive" ]

  Specifies the source control system used to store the project.
• scm_update_cache_timeout: integer
  Title: Scm update cache timeout

  Minimum Value: 0

  The number of seconds after the last project update ran that a new project update will be launched as a job dependency.
• scm_update_on_launch: boolean
  Title: Scm update on launch

  Update the project when a job is launched that uses the project.
• scm_url: string
  Title: SCM URL

  Maximum Length: 1024

  The location where the project is stored.
• signature_validation_credential: integer
  Title: Signature validation credential

  An optional credential used for validating files in the project against unexpected changes.
• status: string
  Title: Status

  Read Only: true

  Allowed Values: [ "new", "pending", "waiting", "running", "successful", "failed", "error", "canceled", "never updated", "ok", "missing" ]
• summary_fields: string
  Title: Summary fields

  Read Only: true
• timeout: integer
  Title: Timeout

  The amount of time (in seconds) to run before the task is canceled.
• type: string
  Title: Type

  Read Only: true
• url: string
  Title: Url

  Read Only: true

{
    "properties":{
        "allow_override":{
            "description":"Allow changing the SCM branch or revision in a job template that uses this project.",
            "title":"Allow override",
            "type":"boolean",
            "x-nullable":true
        },
        "created":{
            "readOnly":true,
            "title":"Created",
            "type":"string"
        },
        "credential":{
            "title":"Credential",
            "type":"integer",
            "x-nullable":true
        },
        "custom_virtualenv":{
            "description":"Local absolute file path containing a custom Python virtualenv to use",
            "minLength":"1",
            "readOnly":true,
            "title":"Custom virtualenv",
            "type":"string",
            "x-nullable":true
        },
        "default_environment":{
            "description":"The default execution environment for jobs run using this project.",
            "title":"Default environment",
            "type":"integer",
            "x-nullable":true
        },
        "description":{
            "title":"Description",
            "type":"string",
            "x-nullable":true
        },
        "id":{
            "readOnly":true,
            "title":"ID",
            "type":"integer"
        },
        "last_job_failed":{
            "readOnly":true,
            "title":"Last job failed",
            "type":"boolean"
        },
        "last_job_run":{
            "format":"date-time",
            "readOnly":true,
            "title":"Last job run",
            "type":"string",
            "x-nullable":true
        },
        "last_update_failed":{
            "readOnly":true,
            "title":"Last update failed",
            "type":"boolean"
        },
        "last_updated":{
            "format":"date-time",
            "readOnly":true,
            "title":"Last updated",
            "type":"string"
        },
        "local_path":{
            "description":"Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.",
            "maxLength":"1024",
            "title":"Local path",
            "type":"string",
            "x-nullable":true
        },
        "modified":{
            "readOnly":true,
            "title":"Modified",
            "type":"string"
        },
        "name":{
            "maxLength":"512",
            "minLength":"1",
            "title":"Name",
            "type":"string",
            "x-nullable":true
        },
        "next_job_run":{
            "format":"date-time",
            "readOnly":true,
            "title":"Next job run",
            "type":"string",
            "x-nullable":true
        },
        "organization":{
            "description":"The organization used to determine access to this template.",
            "title":"Organization",
            "type":"integer",
            "x-nullable":true
        },
        "related":{
            "readOnly":true,
            "title":"Related",
            "type":"string"
        },
        "scm_branch":{
            "description":"Specific branch, tag or commit to checkout.",
            "maxLength":"256",
            "title":"SCM Branch",
            "type":"string",
            "x-nullable":true
        },
        "scm_clean":{
            "description":"Discard any local changes before syncing the project.",
            "title":"Scm clean",
            "type":"boolean",
            "x-nullable":true
        },
        "scm_delete_on_update":{
            "description":"Delete the project before syncing.",
            "title":"Scm delete on update",
            "type":"boolean",
            "x-nullable":true
        },
        "scm_refspec":{
            "description":"For git projects, an additional refspec to fetch.",
            "maxLength":"1024",
            "title":"SCM refspec",
            "type":"string",
            "x-nullable":true
        },
        "scm_revision":{
            "description":"The last revision fetched by a project update",
            "minLength":"1",
            "readOnly":true,
            "title":"SCM Revision",
            "type":"string"
        },
        "scm_track_submodules":{
            "description":"Track submodules latest commits on defined branch.",
            "title":"Scm track submodules",
            "type":"boolean",
            "x-nullable":true
        },
        "scm_type":{
            "description":"Specifies the source control system used to store the project.",
            "enum":[
                "",
                "git",
                "svn",
                "insights",
                "archive"
            ],
            "title":"SCM Type",
            "type":"string",
            "x-nullable":true
        },
        "scm_update_cache_timeout":{
            "description":"The number of seconds after the last project update ran that a new project update will be launched as a job dependency.",
            "minimum":"0",
            "title":"Scm update cache timeout",
            "type":"integer"
        },
        "scm_update_on_launch":{
            "description":"Update the project when a job is launched that uses the project.",
            "title":"Scm update on launch",
            "type":"boolean",
            "x-nullable":true
        },
        "scm_url":{
            "description":"The location where the project is stored.",
            "maxLength":"1024",
            "title":"SCM URL",
            "type":"string",
            "x-nullable":true
        },
        "signature_validation_credential":{
            "description":"An optional credential used for validating files in the project against unexpected changes.",
            "title":"Signature validation credential",
            "type":"integer",
            "x-nullable":true
        },
        "status":{
            "enum":[
                "new",
                "pending",
                "waiting",
                "running",
                "successful",
                "failed",
                "error",
                "canceled",
                "never updated",
                "ok",
                "missing"
            ],
            "readOnly":true,
            "title":"Status",
            "type":"string"
        },
        "summary_fields":{
            "readOnly":true,
            "title":"Summary fields",
            "type":"string"
        },
        "timeout":{
            "description":"The amount of time (in seconds) to run before the task is canceled.",
            "title":"Timeout",
            "type":"integer"
        },
        "type":{
            "readOnly":true,
            "title":"Type",
            "type":"string"
        },
        "url":{
            "readOnly":true,
            "title":"Url",
            "type":"string"
        }
    },
    "required":[
        "name"
    ],
    "type":"object"
}

Back to Top