# /api/v3/work_packages/{id}/relations
---
post:
  summary: Create relation
  operationId: create_relation
  tags:
    - Relations
  description: |-
    Create a work package relation on the given work package. A successful creation will result in a relation between
    two work packages, thus appearing on both involved work package resources.
  parameters:
    - name: id
      description: Work package id
      example: '1'
      in: path
      required: true
      schema:
        type: integer
  requestBody:
    content:
      application/json:
        schema:
          $ref: '../components/schemas/relation_write_model.yml'
        examples:
          request:
            $ref: '../components/examples/relation_create_request.yml'
  responses:
    '201':
      description: Created
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/relation_read_model.yml'
          examples:
            'Simple response':
              $ref: '../components/examples/relation_response.yml'
    '400':
      $ref: '../components/responses/invalid_request_body.yml'
    '403':
      description: |-
        Returned if the client does not have sufficient permissions.

        **Required permission:** manage work package relations
      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 allowed to create a relation.
    '409':
      description: |-
        Returned if there already exists a relation between the given work packages of **any** type
        or if the relation is not allowed.
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          examples:
            response:
              value:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:UpdateConflict
                message: Couldn't update the resource because of conflicting modifications.
    '406':
      $ref: '../components/responses/missing_content_type.yml'
    '415':
      $ref: '../components/responses/unsupported_media_type.yml'
    '422':
      description: |-
        Returned if:

        - the client tries to write a read-only property (`PropertyIsReadOnly`)
        - a constraint for a property was violated (`PropertyConstraintViolation`)
        - the client provides a link to an invalid resource (`ResourceTypeMismatch`)
      content:
        application/hal+json:
          schema:
            $ref: '../components/schemas/error_response.yml'
          examples:
            response:
              value:
                _embedded:
                  details:
                    attribute: lag
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                message: Lag must be a number greater than or equal to 0
