---
title: "Add a link"
description: "A public web page, fetched and read in the background."
url: "https://openemail.uk/docs/api/knowledge/links"
area: "API"
category: "Mailbox"
---

# Add a link

A public web page, fetched and read in the background.

`POST /knowledge/links`

## POST /knowledge/links

A public web page, fetched and read in the background.

## Example

Needs `knowledge:write`. `url` is a public `http` or `https` address of at most 2,048 characters, kept as `https`. Without a `title`, the item is named after the link until the page is read, and then after the page’s own title. Answers 201 with the link, `queued`.

**curl**

```
curl -X POST "$OE/knowledge/links" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "url": "https://acme.com/shipping" }'
```

**Response**

```
{
  "object": "knowledge_item",
  "id": "kb_3e7b1d9a4c2f80e6b5a1c47d",
  "kind": "link",
  "scope": "",
  "level": "workspace",
  "title": "https://acme.com/shipping",
  "url": "https://acme.com/shipping",
  "fileName": null,
  "mimeType": null,
  "sizeBytes": null,
  "pinned": false,
  "status": "queued",
  "failure": null,
  "chunks": 0,
  "chars": 0,
  "origin": "api",
  "createdBy": "usr_5f2a9c71",
  "createdAt": "2026-10-08T09:14:02.000Z",
  "updatedAt": "2026-10-08T09:14:02.000Z",
  "indexedAt": null
}
```

> An address on a private or local host, or one with a user name, a password or a port, is a 422 `invalid_knowledge_url`. The same link at the same level is a 409 `knowledge_link_exists`.

> A page that cannot be fetched ends `failed` with `failure: "fetch_failed"`. At most 5 MB of a page is read.

## Reference

- [`POST /knowledge/links`](https://openemail.uk/docs/api/reference/knowledge#post-knowledge-links): full reference