API: Relations

Work packages may be related to each other in different ways.

+--------------+                            +--------------+
|              | 1                        1 |              |
| Work package +-------------+--------------+ Work package |
|              | from        |           to |              |
+--------------+             |              +--------------+
                      +------+-------+
                      |   Relation   |
                      +--------------+
                      | type         |
                      | reverseType  |
                      | description  |
                      | delay        |
                      +--------------+

Actions

Link	Description	Condition
update	Updates the relation between two work packages via a form	Permission: manage work package relations
updateImmediately	Updates the relation between two work packages	Permission: manage work package relations
delete	Destroys the relation between the two work packages	Permission: manage work package relations

Linked Properties

Link	Description	Type	Constraints	Supported operations	Condition
self	This relation	Relation	not null	READ	Permission: view work packages
schema	The schema of this relation	Schema	not null	READ
from	The emanating work package	WorkPackage	not null	READ	Permission: view work packages
to	The work package the relation ends in	WorkPackage	not null	READ	Permission: view work packages

Local Properties

Property	Description	Type	Constraints	Supported operations
id	Relation ID	Integer	x > 0	READ
name	The internationalized name of this kind of relation	String		READ
type	Which kind of relation (blocks, precedes, etc.)	String	in: relates, duplicates, duplicated, blocks, blocked, precedes, follows, includes, partof, requires, required	READ / WRITE
reverseType	The kind of relation from the other WP’s perspective	String	in: relates, duplicates, duplicated, blocks, blocked, precedes, follows, includes, partof, requires, required	READ
description	Short text further describing the relation	String		READ / WRITE
delay*	The delay in days between closing of `from` and start of `to`	Integer	x >= 0	READ / WRITE

* Only applicable for some relation types such as “follows”. You can check using the relation by schema endpoint at /api/v3/relations/schema/{type}.

Methods

List relations

get /api/v3/relations

Lists all relations according to the given (optional, logically conjunctive) filters and ordered by ID. The response only includes relations between work packages which the user is allowed to see.

Parameters

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Valid fields to filter by are:

id - ID of relation
from - ID of work package from which the filtered relations emanates.
to - ID of work package to which this related points.
involved - ID of either the from or the to work package.
type - The type of relation to filter by, e.g. “follows”.

Example:
[{ "from": { "operator": "=", "values": 42 }" }]

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

Example:
[["type", "asc"]]

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "delete": {
            "href": "/api/v3/relations/1",
            "method": "DELETE"
          },
          "from": {
            "href": "/api/v3/work_packages/42",
            "title": "Steel Delivery"
          },
          "self": {
            "href": "/api/v3/relations/1"
          },
          "to": {
            "href": "/api/v3/work_packages/84",
            "title": "Bending the steel"
          },
          "update": {
            "href": "/api/v3/relations/1/form",
            "method": "POST"
          },
          "updateImmediately": {
            "href": "/api/v3/relations/1",
            "method": "PATCH"
          }
        },
        "_type": "Relation",
        "delay": 0,
        "description": "We can't bend the steel before it's been delivered!",
        "id": 1,
        "name": "precedes",
        "reverseType": "follows",
        "type": "precedes"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/relations"
    }
  },
  "_type": "Collection",
  "count": 1,
  "total": 3
}

RelationsModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/relations"
      }
    },
    "total": 3,
    "count": 1,
    "_type": "Collection",
    "_embedded": {
      "elements": [
        {
          "_links": {
            "self": {
              "href": "/api/v3/relations/1"
            },
            "update": {
              "href": "/api/v3/relations/1/form",
              "method": "POST"
            },
            "updateImmediately": {
              "href": "/api/v3/relations/1",
              "method": "PATCH"
            },
            "delete": {
              "href": "/api/v3/relations/1",
              "method": "DELETE"
            },
            "from": {
              "href": "/api/v3/work_packages/42",
              "title": "Steel Delivery"
            },
            "to": {
              "href": "/api/v3/work_packages/84",
              "title": "Bending the steel"
            }
          },
          "_type": "Relation",
          "id": 1,
          "name": "precedes",
          "type": "precedes",
          "reverseType": "follows",
          "description": "We can't bend the steel before it's been delivered!",
          "delay": 0
        }
      ]
    }
  }
}

View relation schema

get /api/v3/relations/schema

No parameters

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_links": {
    "self": {
      "href": "/api/v3/relations/schema"
    }
  },
  "_type": "Schema",
  "delay": {
    "name": "Delay",
    "type": "Integer",
    "writable": true
  },
  "description": {
    "name": "Description",
    "type": "String",
    "writable": true
  },
  "from": {
    "name": "From work package",
    "type": "WorkPackage",
    "writable": false
  },
  "id": {
    "name": "ID",
    "type": "Integer",
    "writable": false
  },
  "reverseType": {
    "name": "Reverse Type",
    "type": "String",
    "writable": false
  },
  "to": {
    "name": "To work package",
    "type": "WorkPackage",
    "writable": false
  },
  "type": {
    "name": "Type",
    "type": "String",
    "writable": true
  }
}

Relation_schemaModel

{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_links": {
      "self": {
        "href": "/api/v3/relations/schema"
      }
    },
    "id": {
      "name": "ID",
      "type": "Integer",
      "writable": false
    },
    "type": {
      "name": "Type",
      "type": "String",
      "writable": true
    },
    "reverseType": {
      "name": "Reverse Type",
      "type": "String",
      "writable": false
    },
    "description": {
      "name": "Description",
      "type": "String",
      "writable": true
    },
    "from": {
      "name": "From work package",
      "type": "WorkPackage",
      "writable": false
    },
    "to": {
      "name": "To work package",
      "type": "WorkPackage",
      "writable": false
    },
    "delay": {
      "name": "Delay",
      "type": "Integer",
      "writable": true
    }
  }
}

View relation schema for type

get /api/v3/relations/schema/{type}

Parameters

type
string

required path

Type of the schema

Example:
follows

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_links": {
    "self": {
      "href": "/api/v3/relations/schema"
    }
  },
  "_type": "Schema",
  "delay": {
    "name": "Delay",
    "type": "Integer",
    "writable": true
  },
  "description": {
    "name": "Description",
    "type": "String",
    "writable": true
  },
  "from": {
    "name": "From work package",
    "type": "WorkPackage",
    "writable": false
  },
  "id": {
    "name": "ID",
    "type": "Integer",
    "writable": false
  },
  "reverseType": {
    "name": "Reverse Type",
    "type": "String",
    "writable": false
  },
  "to": {
    "name": "To work package",
    "type": "WorkPackage",
    "writable": false
  },
  "type": {
    "name": "Type",
    "type": "String",
    "writable": true
  }
}

Relation_schemaModel

{
  "type": "object",
  "example": {
    "_type": "Schema",
    "_links": {
      "self": {
        "href": "/api/v3/relations/schema"
      }
    },
    "id": {
      "name": "ID",
      "type": "Integer",
      "writable": false
    },
    "type": {
      "name": "Type",
      "type": "String",
      "writable": true
    },
    "reverseType": {
      "name": "Reverse Type",
      "type": "String",
      "writable": false
    },
    "description": {
      "name": "Description",
      "type": "String",
      "writable": true
    },
    "from": {
      "name": "From work package",
      "type": "WorkPackage",
      "writable": false
    },
    "to": {
      "name": "To work package",
      "type": "WorkPackage",
      "writable": false
    },
    "delay": {
      "name": "Delay",
      "type": "Integer",
      "writable": true
    }
  }
}

404

Returned if the relation type does not exist or the client does not have sufficient permissions to see it.

Required permission: manage work package relations

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified relation type does not exist."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View relation

get /api/v3/relations/{id}

Parameters

id
integer

required path

Relation id

Example:
1

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_links": {
    "delete": {
      "href": "/api/v3/relations/1",
      "method": "DELETE"
    },
    "from": {
      "href": "/api/v3/work_packages/42",
      "title": "Steel Delivery"
    },
    "self": {
      "href": "/api/v3/relations/1"
    },
    "to": {
      "href": "/api/v3/work_packages/84",
      "title": "Bending the steel"
    },
    "update": {
      "href": "/api/v3/relations/1/form",
      "method": "POST"
    },
    "updateImmediately": {
      "href": "/api/v3/relations/1",
      "method": "PATCH"
    }
  },
  "_type": "Relation",
  "delay": 0,
  "description": "We can't bend the steel before it's been delivered!",
  "id": 1,
  "name": "precedes",
  "reverseType": "follows",
  "type": "precedes"
}

RelationModel

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Relation ID",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "name": {
      "type": "string",
      "description": "The internationalized name of this kind of relation"
    },
    "type": {
      "type": "string",
      "description": "Which kind of relation (blocks, precedes, etc.)"
    },
    "reverseType": {
      "type": "string",
      "description": "The kind of relation from the other WP's perspective",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "Short text further describing the relation"
    },
    "delay*": {
      "type": "integer",
      "description": "The delay in days between closing of `from` and start of `to`",
      "minimum": 0
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "from",
        "to"
      ],
      "properties": {
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the relation between two work packages via a form\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the relation between two work packages\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Destroys the relation between the two work packages\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This relation\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this relation\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "from": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The emanating work package\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "to": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The work package the relation ends in\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/relations/1"
      },
      "update": {
        "href": "/api/v3/relations/1/form",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/relations/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/relations/1",
        "method": "DELETE"
      },
      "from": {
        "href": "/api/v3/work_packages/42",
        "title": "Steel Delivery"
      },
      "to": {
        "href": "/api/v3/work_packages/84",
        "title": "Bending the steel"
      }
    },
    "_type": "Relation",
    "id": 1,
    "name": "precedes",
    "type": "precedes",
    "reverseType": "follows",
    "description": "We can't bend the steel before it's been delivered!",
    "delay": 0
  }
}

404

Returned if the relation does not exist or the client does not have sufficient permissions to see it.

Required permission: view work packages for the involved work packages

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified relation does not exist."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Edit relation

patch /api/v3/relations/{id}

When calling this endpoint the client provides a single object, containing the properties and links that it wants to change, in the body. It is only allowed to provide properties or links supporting the write operation.

Note that changing the type of a relation invariably also changes the respective reverseType as well as the “name” of it. The returned Relation object will reflect that change. For instance if you change a Relation’s type to “follows” then the reverseType will be changed to precedes.

Parameters

id
integer

required path

Relation ID

Example:
1

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_links": {
    "delete": {
      "href": "/api/v3/relations/1",
      "method": "DELETE"
    },
    "from": {
      "href": "/api/v3/work_packages/42",
      "title": "Steel Delivery"
    },
    "self": {
      "href": "/api/v3/relations/1"
    },
    "to": {
      "href": "/api/v3/work_packages/84",
      "title": "Bending the steel"
    },
    "update": {
      "href": "/api/v3/relations/1/form",
      "method": "POST"
    },
    "updateImmediately": {
      "href": "/api/v3/relations/1",
      "method": "PATCH"
    }
  },
  "_type": "Relation",
  "delay": 0,
  "description": "We can't bend the steel before it's been delivered!",
  "id": 1,
  "name": "precedes",
  "reverseType": "follows",
  "type": "precedes"
}

RelationModel

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Relation ID",
      "readOnly": true,
      "minimum": 0,
      "exclusiveMinimum": true
    },
    "name": {
      "type": "string",
      "description": "The internationalized name of this kind of relation"
    },
    "type": {
      "type": "string",
      "description": "Which kind of relation (blocks, precedes, etc.)"
    },
    "reverseType": {
      "type": "string",
      "description": "The kind of relation from the other WP's perspective",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "Short text further describing the relation"
    },
    "delay*": {
      "type": "integer",
      "description": "The delay in days between closing of `from` and start of `to`",
      "minimum": 0
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "from",
        "to"
      ],
      "properties": {
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the relation between two work packages via a form\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Updates the relation between two work packages\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "delete": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "Destroys the relation between the two work packages\n\n# Conditions\n\n**Permission**: manage work package relations",
              "readOnly": true
            }
          ]
        },
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This relation\n\n**Resource**: Relation\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The schema of this relation\n\n**Resource**: Schema",
              "readOnly": true
            }
          ]
        },
        "from": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The emanating work package\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        },
        "to": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The work package the relation ends in\n\n**Resource**: WorkPackage\n\n# Conditions\n\n**Permission**: view work packages",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/relations/1"
      },
      "update": {
        "href": "/api/v3/relations/1/form",
        "method": "POST"
      },
      "updateImmediately": {
        "href": "/api/v3/relations/1",
        "method": "PATCH"
      },
      "delete": {
        "href": "/api/v3/relations/1",
        "method": "DELETE"
      },
      "from": {
        "href": "/api/v3/work_packages/42",
        "title": "Steel Delivery"
      },
      "to": {
        "href": "/api/v3/work_packages/84",
        "title": "Bending the steel"
      }
    },
    "_type": "Relation",
    "id": 1,
    "name": "precedes",
    "type": "precedes",
    "reverseType": "follows",
    "description": "We can't bend the steel before it's been delivered!",
    "delay": 0
  }
}

400

404

Returned if the relation does not exist or the client does not have sufficient permissions to see it.

Required permission: manage work package relations

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified relation does not exist."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

415

422

Returned if:

the client tries to modify a read-only property (PropertyIsReadOnly)
a constraint for a property was violated (PropertyConstraintViolation)
the client provides a link to an invalid resource (ResourceTypeMismatch) or a work package that does not exist or for which the client does not have sufficient permissions to see it (required permissions: view work packages for the involved work packages).

Content-Type: application/hal+json

Example
Schema

{
  "_embedded": {
    "details": {
      "attribute": "delay"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Delay must be a number greater than or equal to 0"
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete relation

delete /api/v3/relations/{id}

Deletes the relation.

Parameters

id
integer

required path

Relation ID

Example:
1

Responses

204

Returned if the relation was deleted successfully. The response body is empty.

403

Returned if the client does not have sufficient permissions.

Required permission: manage work package relations

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete this relation."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the relation does not exist or the client does not have sufficient permissions to see it.

Required permission: manage work package relations

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified relation does not exist."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

415

Relation edit form

post /api/v3/relations/{id}/form

Parameters

id
integer

required path

ID of the relation being modified

Example:
1

Responses

200

Content-Type: application/hal+json

Example
Schema

{
  "_embedded": {
    "payload": {
      "_links": {
        "from": {
          "href": "/api/v3/work_packages/4534"
        },
        "to": {
          "href": "/api/v3/work_packages/3857"
        }
      },
      "_type": "WorkPackage",
      "delay": 3,
      "description": "let it rest for 3 days",
      "type": "follows"
    },
    "schema": {
      "_links": {
        "self": {
          "href": "/api/v3/relations/schema"
        }
      },
      "_type": "Schema",
      "delay": {
        "name": "Delay",
        "type": "Integer",
        "writable": true
      },
      "description": {
        "name": "Description",
        "type": "String",
        "writable": true
      },
      "from": {
        "name": "From work package",
        "type": "WorkPackage",
        "writable": false
      },
      "id": {
        "name": "ID",
        "type": "Integer",
        "writable": false
      },
      "reverseType": {
        "name": "Reverse Type",
        "type": "String",
        "writable": false
      },
      "to": {
        "name": "To work package",
        "type": "WorkPackage",
        "writable": false
      },
      "type": {
        "allowedValues": [
          "relates",
          "duplicates",
          "duplicated",
          "blocks",
          "blocked",
          "precedes",
          "follows",
          "includes",
          "partof",
          "requires",
          "required"
        ],
        "name": "Type",
        "type": "String",
        "writable": true
      }
    },
    "validationErrors": {
      "from": {
        "_type": "Error",
        "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
        "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
      }
    }
  },
  "_links": {
    "commit": {
      "href": "/api/v3/relations",
      "method": "PATCH"
    },
    "self": {
      "href": "/api/v3/relations/form"
    },
    "validate": {
      "href": "/api/v3/relations/form",
      "method": "POST"
    }
  },
  "_type": "Form"
}

Relation_edit_formModel

{
  "type": "object",
  "example": {
    "_links": {
      "self": {
        "href": "/api/v3/relations/form"
      },
      "validate": {
        "href": "/api/v3/relations/form",
        "method": "POST"
      },
      "commit": {
        "href": "/api/v3/relations",
        "method": "PATCH"
      }
    },
    "_type": "Form",
    "_embedded": {
      "payload": {
        "_links": {
          "from": {
            "href": "/api/v3/work_packages/4534"
          },
          "to": {
            "href": "/api/v3/work_packages/3857"
          }
        },
        "_type": "WorkPackage",
        "type": "follows",
        "delay": 3,
        "description": "let it rest for 3 days"
      },
      "schema": {
        "_type": "Schema",
        "_links": {
          "self": {
            "href": "/api/v3/relations/schema"
          }
        },
        "id": {
          "name": "ID",
          "type": "Integer",
          "writable": false
        },
        "type": {
          "name": "Type",
          "type": "String",
          "writable": true,
          "allowedValues": [
            "relates",
            "duplicates",
            "duplicated",
            "blocks",
            "blocked",
            "precedes",
            "follows",
            "includes",
            "partof",
            "requires",
            "required"
          ]
        },
        "reverseType": {
          "name": "Reverse Type",
          "type": "String",
          "writable": false
        },
        "description": {
          "name": "Description",
          "type": "String",
          "writable": true
        },
        "from": {
          "name": "From work package",
          "type": "WorkPackage",
          "writable": false
        },
        "to": {
          "name": "To work package",
          "type": "WorkPackage",
          "writable": false
        },
        "delay": {
          "name": "Delay",
          "type": "Integer",
          "writable": true
        }
      },
      "validationErrors": {
        "from": {
          "_type": "Error",
          "errorIdentifier": "urn:openproject-org:api:v3:errors:BadExampleError",
          "message": "For the purpose of this example we need a validation error. The remainder of the response pretends there were no errors."
        }
      }
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage work package relations

Note that you will only receive this error, if you are at least allowed to see the involved work packages.

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to edit the specified relation."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the relation does not exist or the client does not have sufficient permissions to see it.

Required permission: view (involved) work package(s), manage work package relations

Content-Type: application/hal+json

Example
Schema

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified relation does not exist."
}

ErrorResponse

{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}