# Edara API v3: Document Manual Links

Read the [guide](../guide.md) first: authentication, paging, errors, rate limits and the shared `PagedResult`, `BatchResult` and `*Reference` shapes.

- `GET /v3/documents/{code}/manual-links`: Gets manual links for a document.
- `POST /v3/documents/{code}/manual-links`: Adds manual links to a document.
- `DELETE /v3/documents/{code}/manual-links/{linkedCode}`: Deletes a manual link between two documents.

## Endpoints

### `GET /v3/documents/{code}/manual-links`: Gets manual links for a document.

Operation `GetDocumentManualLinks` · permission `read:common-utility`

> An empty list is a valid response when no manual links exist.

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `code` | route | `string` |  | The document code. |

**Responses**: OK `IReadOnlyCollection<string>`: Manual links for the document.

**Notes**

- A manual link is a group of document codes that users have linked together. Documents of any type can be in a group.
- The response is a plain list of the other document codes in the same group as `code`. The code you asked about is not included.
- A `code` that is unknown or has no links returns `200` with an empty list, never `404`.
- `code` is trimmed but not normalised the way the add and delete endpoints normalise codes. Send it exactly as it is stored, including letter case.
- There is no paging. All linked codes come back in one response.

---

### `POST /v3/documents/{code}/manual-links`: Adds manual links to a document.

Operation `AddDocumentManualLinks` · permission `create:common-utility`

> Returns the normalized codes that were processed. Self-links and codes without a dash separator are silently skipped.

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `code` | route | `string` |  | The document code. |

**Body**: `List<string>` (JSON array)

**Responses**: OK `IReadOnlyCollection<string>`: Links added. · NotFound `ProblemDetails`: Document not found.

**Notes**

- Codes are trimmed and their document type prefix (the part before the hyphen) is normalised before they are stored, so a stored code can differ in letter case from what you sent.
- These entries are skipped without an error: blank entries, codes without a hyphen, the document's own code, and codes repeated in the same request.
- An empty or missing body returns `200` with an empty list.
- Links work as groups. If one of the two documents is already in a group, the other one joins it. If neither is in a group, a new group is created with both.
- If both documents are already in a group, nothing is written, even when the groups are different. Two existing groups cannot be merged through the API.
- Links are transitive: linking A to B when B is already linked to C also links A to C.
- Each code is saved separately, not as one unit, so a failure part way through can leave earlier links saved.
- The response lists the normalised codes that were processed, including those where nothing was written.

---

### `DELETE /v3/documents/{code}/manual-links/{linkedCode}`: Deletes a manual link between two documents.

Operation `DeleteDocumentManualLink` · permission `create:common-utility`

> Always returns 204 even when the linked code was not found.

**Parameters**

| name | in | type | default | description |
|---|---|---|---|---|
| `code` | route | `string` |  | The document code. |
| `linkedCode` | route | `string` |  | The linked document code. |

**Responses**: NoContent: (not declared; read from the method body)

**Notes**

- The delete is permanent. `linkedCode` is removed from its link group, so it is no longer linked to any document in that group.
- If only one document would remain in the group, the whole group is removed. A link between just two documents disappears completely.
- `linkedCode` is normalised the same way as in the add endpoint before the lookup.
- The call returns `204` even when `linkedCode` is not linked to anything, so `204` does not confirm that a link was removed.