# /api/v3/projects
---
get:
  summary: List projects
  operationId: list_projects
  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.
  parameters:
    - name: filters
      schema:
        type: string
      in: query
      required: false
      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.
        + available_project_attributes: filters projects based on the activated project project attributes.
        + 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.
        + storage_id: filters projects by linked storages
        + storage_url: filters projects by linked storages identified by the host url
        + 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"] }" }]'
    - name: sortBy
      schema:
        type: string
      in: query
      required: false
      description: |-
        JSON specifying sort criteria.
        Currently supported orders are:

        + id
        + name
        + typeahead (sorting by hierarchy and 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"]]'
    - name: select
      schema:
        type: string
      in: query
      required: false
      description: |-
        Comma separated list of properties to include.
      example: 'total,elements/identifier,elements/name'
  responses:
    '200':
      description: OK
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/project_collection_model.yml'
          examples:
            'simple project collection':
              $ref: '../components/examples/project_collection.yml'
    '400':
      description: Returned if the client sends invalid request parameters e.g. filters
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
            message: Filters Invalid filter does not exist.

post:
  summary: Create project
  operationId: create_project
  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.
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../components/schemas/project_model.yml'
        examples:
          'with custom fields':
            $ref: '../components/examples/project_body.yml'
  responses:
    '201':
      description: Created
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/project_model.yml'
          examples:
            'with custom fields':
              $ref: '../components/examples/project.yml'
    '400':
      $ref: '../components/responses/invalid_request_body.yml'
    '403':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          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
    '406':
      $ref: '../components/responses/missing_content_type.yml'
    '415':
      $ref: '../components/responses/unsupported_media_type.yml'
    '422':
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          example:
            _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`)
