# /api/v3/projects
---
get:
  parameters:
  - description: |-
      JSON specifying filter conditions.
      Accepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/) endpoint.
      Currently supported filters are:

      + active: based on the active property of the project

      + ancestor: filters projects by their ancestor. A project is not considered to be it's own ancestor.

      + created_at: based on the time the project was created

      + latest_activity_at: based on the time the last activity was registered on a project.

      + name_and_identifier: based on both the name and the identifier.

      + parent_id: filters projects by their parent.

      + principal: based on members of the project.

      + type_id: based on the types active in a project.

      + user_action: based on the actions the current user has in the project.

      + id: based on projects' id.

      + visible: based on the visibility for the user (id) provided as the filter value. This filter is useful for admins to identify the projects visible to a user.
      There might also be additional filters based on the custom fields that have been configured.
    example: '[{ "ancestor": { "operator": "=", "values": [''1''] }" }]'
    in: query
    name: filters
    required: false
    schema:
      type: string
  - description: |-
      JSON specifying sort criteria.
      Currently supported orders are:

      + id

      + name

      + created_at

      + public

      + latest_activity_at

      + required_disk_space
      There might also be additional orders based on the custom fields that have been configured.
    example: '[["id", "asc"]]'
    in: query
    name: sortBy
    required: false
    schema:
      type: string
  responses:
    '200':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  elements:
                  - _links:
                      categories:
                        href: "/api/v3/projects/6/categories"
                      createWorkPackage:
                        href: "/api/v3/projects/6/work_packages/form"
                        method: post
                      createWorkPackageImmediate:
                        href: "/api/v3/projects/6/work_packages"
                        method: post
                      projects:
                        href: "/api/v3/projects/123"
                      self:
                        href: "/api/v3/projects/6"
                        title: A project
                      status:
                        href: "/api/v3/project_statuses/on_track"
                        title: On track
                      versions:
                        href: "/api/v3/projects/6/versions"
                    _type: Project
                    active: true
                    createdAt: '2015-07-06T13:28:14+00:00'
                    description:
                      format: markdown
                      html: "<p>Lorem <strong>ipsum</strong> dolor sit amet</p>"
                      raw: Lorem **ipsum** dolor sit amet
                    id: 6
                    identifier: a_project
                    name: A project
                    public: false
                    statusExplanation:
                      format: markdown
                      html: "<p>Everything <strong>fine</strong></p>"
                      raw: Everything **fine**
                    type: Customer Project
                    updatedAt: '2015-10-01T09:55:02+00:00'
                  - _links:
                      categories:
                        href: "/api/v3/projects/14/categories"
                      createWorkPackage:
                        href: "/api/v3/projects/14/work_packages/form"
                        method: post
                      createWorkPackageImmediate:
                        href: "/api/v3/projects/14/work_packages"
                        method: post
                      projects:
                        href: 
                      self:
                        href: "/api/v3/projects/14"
                        title: Another project
                      status:
                        href: "/api/v3/project_statuses/off_track"
                        title: Off track
                      versions:
                        href: "/api/v3/projects/14/versions"
                    _type: Project
                    active: false
                    createdAt: '2016-02-29T12:50:20+00:00'
                    description:
                      format: markdown
                      html: ''
                      raw: ''
                    id: 14
                    identifier: another_project
                    name: Another project
                    public: true
                    statusExplanation:
                      format: markdown
                      html: "<p>Uh <strong>oh</strong></p>"
                      raw: Uh **oh**
                    type: 
                    updatedAt: '2016-02-29T12:50:20+00:00'
                _links:
                  self:
                    href: "/api/v3/projects"
                _type: Collection
                count: 2
                total: 2
          schema:
            "$ref": "../components/schemas/list_projects_model.yml"
      description: OK
      headers: {}
  tags:
  - Projects
  description: Returns a collection of projects. The collection can be filtered via
    query parameters similar to how work packages are filtered. In addition to the
    provided filter, the result set is always limited to only contain projects the
    client is allowed to see.
  operationId: List_projects
  summary: List projects
post:
  responses:
    '201':
      content:
        application/hal+json:
          schema:
            "$ref": "../components/schemas/view_project_model.yml"
      description: Created
      headers: {}
    '400':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
                message: The request body was not a single JSON object.
      description: Occurs when the client did not send a valid JSON object in the
        request body.
      headers: {}
    '403':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** add project which is a global permission
      headers: {}
    '422':
      content:
        application/hal+json:
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: name
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Name can't be blank.
      description: |-
        Returned if:

        * a constraint for a property was violated (`PropertyConstraintViolation`)
      headers: {}
  tags:
  - Projects
  description: |-
    Creates a new project, applying the attributes provided in the body.

    You can use the form and schema to be retrieve the valid attribute values and by that be guided towards successful creation.
  operationId: Create_project
  summary: Create project