Documentation

9. Project List API Endpoint

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

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

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.

9.1. Results

Each project data structure includes the following fields:

  • id: Database ID for this project. (integer)
  • type: Data type for this project. (multiple 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: (string)
  • description: (string)
  • local_path: Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project. (string)
  • scm_type: (multiple choice)
    • "": Manual
    • git: Git
    • hg: Mercurial
    • svn: Subversion
  • scm_url: (string)
  • scm_branch: Specific branch, tag or commit to checkout. (string)
  • scm_clean: (boolean)
  • scm_delete_on_update: (boolean)
  • credential: (field)
  • last_job_run: (datetime)
  • last_job_failed: (boolean)
  • has_schedules: (boolean)
  • next_job_run: (datetime)
  • status: (multiple 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
  • scm_delete_on_next_update: (boolean)
  • scm_update_on_launch: (boolean)
  • scm_update_cache_timeout: (integer)
  • last_update_failed: (boolean)
  • last_updated: (datetime)

9.2. 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: (multiple 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)
  • scm_update_on_launch: (boolean, default=False)
  • scm_update_cache_timeout: (integer, default=0)

9.3. 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
description
type string
required
false
label description
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
default (Empty Text)
scm_type
type multiple choice
required
false
label SCM Type
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
scm_url
type string
required
false
label SCM URL
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
default
false
scm_delete_on_update
type boolean
required
false
label scm delete on update
default
false
credential
type field
required
false
default null
scm_update_on_launch
type boolean
required
false
label scm update on launch
default
false
scm_update_cache_timeout
type integer
required
false
label scm update cache timeout
default 0
GET
id
type integer
label ID
help_text Database ID for this project.
type
type multiple choice
help_text Data type for this project.
choices
0
0 project
1 Project
url
type string
help_text URL for this project.
related
type object
help_text Data structure with URLs of related resources.
summary_fields
type object
help_text Data structure with name/description for related resources.
created
type datetime
help_text Timestamp when this project was created.
modified
type datetime
help_text Timestamp when this project was last modified.
name
type string
label name
description
type string
label description
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 multiple 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
scm_url
type string
label SCM URL
scm_branch
type string
label SCM Branch
help_text Specific branch, tag or commit to checkout.
scm_clean
type boolean
label scm clean
scm_delete_on_update
type boolean
label scm delete on update
credential
type field
last_job_run
type datetime
label last job run
last_job_failed
type boolean
label last job failed
has_schedules
type boolean
label has schedules
next_job_run
type datetime
label next job run
status
type multiple choice
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
scm_delete_on_next_update
type boolean
scm_update_on_launch
type boolean
label scm update on launch
scm_update_cache_timeout
type integer
label scm update cache timeout
last_update_failed
type boolean
last_updated
type datetime
types
0 project
search_fields
0 description
1 name