# Docs

Endpoints under /v1/docs.

Source: https://sourceloop.ai/help/api/docs/

---

| Endpoint | Method | Path | Permission |
| --- | --- | --- | --- |
| List docs | GET | `/v1/docs` | any key |
| Create doc | POST | `/v1/docs` | any key |
| Get doc | GET | `/v1/docs/{id}` | any key |
| Edit doc | POST | `/v1/docs/{id}/blocks` | any key |
| Share doc | POST | `/v1/docs/{id}/shares` | any key |

Base URL: `https://app.sourceloop.ai/api/v1`

## List docs

`GET /v1/docs`

List docs

Requires: any valid API key.

Workspace docs (reports, dashboards, plans) and the templates a new doc can start from. Private docs are never listed.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string | no | Website domain, e.g. acme.com. Required only when the key covers more than one. |

### Responses

- `200` Docs and templates

### Example (cURL)

```bash
curl -s -X GET "https://app.sourceloop.ai/api/v1/docs?website=acme.com" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/docs?website=acme.com",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.get(
    "https://app.sourceloop.ai/api/v1/docs?website=acme.com",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```

## Create doc

`POST /v1/docs`

Create a doc

Requires: any valid API key.

From a `template` key or from `markdown`. Markdown may hold ```sourceloop-widget fences with widget JSON, the format GET /docs/{id} returns. Needs the docs:write scope.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string | no |  |
| `title` | string | no |  |
| `template` | string | no |  |
| `markdown` | string | no |  |

### Responses

- `200` The new doc id and URL
- `400` Something was wrong with the request or the credential.

### Example (cURL)

```bash
curl -s -X POST "https://app.sourceloop.ai/api/v1/docs" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/docs",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.post(
    "https://app.sourceloop.ai/api/v1/docs",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```

## Get doc

`GET /v1/docs/{id}`

Read a doc

Requires: any valid API key.

The doc as Markdown, every block with its id, type, text and widget spec, and the doc's controls.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |

### Responses

- `200` The doc
- `404` Something was wrong with the request or the credential.

### Example (cURL)

```bash
curl -s -X GET "https://app.sourceloop.ai/api/v1/docs/{id}" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/docs/{id}",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.get(
    "https://app.sourceloop.ai/api/v1/docs/{id}",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```

## Edit doc

`POST /v1/docs/{id}/blocks`

Edit a doc block by block

Requires: any valid API key.

Ops: append, insert_after, insert_before, replace, remove, move_after. Applied as one change that merges with live editing; a restore point is saved first. There is no whole-document replace.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ops` | object[] | no |  |

### Responses

- `200` Ids of inserted blocks
- `400` Something was wrong with the request or the credential.

### Example (cURL)

```bash
curl -s -X POST "https://app.sourceloop.ai/api/v1/docs/{id}/blocks" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/docs/{id}/blocks",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.post(
    "https://app.sourceloop.ai/api/v1/docs/{id}/blocks",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```

## Share doc

`POST /v1/docs/{id}/shares`

Create a share link

Requires: any valid API key.

A link that opens the doc in the workspace brand without signing in. The URL is returned once. Needs the docs:share scope.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fixed_window` | string | no | The period the link always shows: "previous month" (moves forward each month) or "2026-10-01..2026-10-31". Omit to follow the doc. |
| `allow_date_change` | boolean | no | Whether viewers may change the date range. Defaults to false with fixed_window, true without. |
| `title` | string | no | What the shared page is called for its viewers. Defaults to the doc title. |
| `password` | string | no |  |
| `show_contact_details` | boolean | no | Full emails and phone numbers in lists of people. Needs a password. Off by default; masked otherwise. |
| `expires_at` | string (date-time) | no |  |

### Responses

- `200` The share URL
- `400` An invalid period, password or expiry, with a message saying which

### Example (cURL)

```bash
curl -s -X POST "https://app.sourceloop.ai/api/v1/docs/{id}/shares" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/docs/{id}/shares",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.post(
    "https://app.sourceloop.ai/api/v1/docs/{id}/shares",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```