Skip to content

Commit 06a4e17

Browse files
yash-pouranikyash-pouranik
authored
Merge pull request #198 from MdTowfikomer/docs/soft-delete
docs: update documentation for soft-delete system
2 parents 594e2e6 + 67f58eb commit 06a4e17

10 files changed

Lines changed: 324 additions & 114 deletions

File tree

‎mintlify/docs/api-reference/data/aggregate.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: "Aggregate Data"
3+
description: "Execute MongoDB aggregation pipelines on your collection."
4+
---
5+
6+
## POST `/api/data/:collectionName/aggregate`
7+
8+
Runs a MongoDB aggregation pipeline on the specified collection. This allows for complex data processing, grouping, and transformations.
9+
10+
### Required header
11+
12+
`x-api-key`: your `pk_live_…` or `sk_live_…` key.
13+
14+
### Path parameters
15+
16+
<ParamField path="collectionName" type="string" required>
17+
The name of the collection to aggregate.
18+
</ParamField>
19+
20+
### Query parameters
21+
22+
<ParamField query="include_deleted" type="boolean">
23+
If `true`, includes soft-deleted documents (where `isDeleted: true`) in the aggregation. Defaults to `false`.
24+
</ParamField>
25+
26+
### Request body
27+
28+
<ParamField body="pipeline" type="array" required>
29+
An array of aggregation stages following the standard MongoDB aggregation pipeline syntax.
30+
</ParamField>
31+
32+
<Note>
33+
For security reasons, certain stages like `$out` and `$merge` are blocked.
34+
</Note>
35+
36+
### RLS behavior
37+
38+
If Row-Level Security (RLS) is enabled, your backend automatically injects a `$match` stage at the beginning of your pipeline (or after `$geoNear` / `$search` if present). This ensures users only aggregate data they have access to.
39+
40+
### Response fields
41+
42+
<ResponseField name="success" type="boolean">
43+
`true` when the aggregation was executed successfully.
44+
</ResponseField>
45+
46+
<ResponseField name="data" type="array">
47+
The results of the aggregation pipeline.
48+
</ResponseField>
49+
50+
<ResponseField name="message" type="string">
51+
Human-readable status message.
52+
</ResponseField>
53+
54+
### Code examples
55+
56+
<CodeGroup>
57+
58+
```javascript fetch
59+
const res = await fetch(
60+
'https://api.ub.bitbros.in/api/data/orders/aggregate',
61+
{
62+
method: 'POST',
63+
headers: {
64+
'Content-Type': 'application/json',
65+
'x-api-key': 'pk_live_YOUR_KEY'
66+
},
67+
body: JSON.stringify({
68+
pipeline: [
69+
{ $match: { status: 'completed' } },
70+
{ $group: { _id: '$customerId', totalAmount: { $sum: '$amount' } } },
71+
{ $sort: { totalAmount: -1 } }
72+
]
73+
})
74+
}
75+
);
76+
77+
const { success, data } = await res.json();
78+
```
79+
80+
```bash curl
81+
curl -X POST "https://api.ub.bitbros.in/api/data/orders/aggregate?include_deleted=false" \
82+
-H "Content-Type: application/json" \
83+
-H "x-api-key: pk_live_YOUR_KEY" \
84+
-d '{
85+
"pipeline": [
86+
{ "$group": { "_id": "$category", "count": { "$sum": 1 } } }
87+
]
88+
}'
89+
```
90+
91+
</CodeGroup>
92+
93+
### Success response
94+
95+
```json
96+
{
97+
"success": true,
98+
"data": [
99+
{ "_id": "electronics", "count": 42 },
100+
{ "_id": "books", "count": 12 }
101+
],
102+
"message": "Aggregation executed successfully."
103+
}
104+
```
105+
106+
### Errors
107+
108+
| Status | Cause |
109+
| :--- | :--- |
110+
| `400 Bad Request` | Invalid pipeline syntax or blocked stage used |
111+
| `401 Unauthorized` | Missing or invalid API key |
112+
| `404 Not Found` | Collection does not exist |

‎mintlify/docs/api-reference/data/delete.mdx‎

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
---
22
title: "Delete Document"
3-
description: "Permanently delete a document from a collection by its ID."
3+
description: "Soft delete a document from a collection by its ID. Moves it to the trash."
44
---
55

66
## DELETE `/api/data/:collectionName/:id`
77

8-
Permanently removes the document with the given ID from the collection. This operation cannot be undone.
8+
Moves the document with the given ID to the trash by setting `isDeleted: true` and recording the `deletedAt` timestamp. The document remains recoverable for a **30-day grace period**, after which it is permanently deleted by a background cleanup worker. See the [Database Guide](/guides/database#soft-delete-trash) for more details.
99

10-
### Required Header
10+
### Required header
1111

1212
`x-api-key`: `sk_live_…` by default. `pk_live_…` is accepted only when the collection has **RLS enabled** and the request includes `Authorization: Bearer <accessToken>`.
1313

14-
### Path Parameters
14+
### Path parameters
1515

1616
<ParamField path="collectionName" type="string" required>
1717
The name of the collection containing the document.
@@ -21,21 +21,25 @@ Permanently removes the document with the given ID from the collection. This ope
2121
The MongoDB ObjectId string of the document to delete.
2222
</ParamField>
2323

24-
### RLS Ownership Check
24+
### RLS ownership check
2525

26-
When using `pk_live` with RLS enabled, urBackend compares the existing document's owner field against the authenticated user's ID. Users can only delete their own documents — attempting to delete another user's document returns `403`.
26+
When using `pk_live` with RLS enabled, urBackend compares the existing document's owner field against the authenticated user's ID. You can only delete your own documents; attempting to delete another user's document returns `403`.
2727

28-
### Response Fields
28+
### Response fields
2929

3030
<ResponseField name="success" type="boolean">
31-
`true` when the document was deleted.
31+
`true` when the document was moved to trash.
32+
</ResponseField>
33+
34+
<ResponseField name="data" type="object">
35+
Object containing the `id` of the deleted document.
3236
</ResponseField>
3337

3438
<ResponseField name="message" type="string">
3539
Human-readable confirmation message.
3640
</ResponseField>
3741

38-
### Code Examples
42+
### Code examples
3943

4044
<CodeGroup>
4145

@@ -52,7 +56,7 @@ const res = await fetch(
5256
}
5357
);
5458

55-
const { success, message } = await res.json();
59+
const { success, data, message } = await res.json();
5660
```
5761

5862
```javascript fetch (pk_live + RLS)
@@ -77,13 +81,15 @@ curl -X DELETE "https://api.ub.bitbros.in/api/data/posts/64fd1234abcd5678ef90123
7781

7882
</CodeGroup>
7983

80-
### Success Response
84+
### Success response
8185

8286
```json
8387
{
8488
"success": true,
85-
"data": {},
86-
"message": "Document deleted successfully"
89+
"data": {
90+
"id": "64fd1234abcd5678ef901234"
91+
},
92+
"message": "Document moved to trash"
8793
}
8894
```
8995

‎mintlify/docs/api-reference/data/get-all.mdx‎

Lines changed: 63 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -11,17 +11,17 @@ Returns a list of documents from the specified collection. Supports pagination,
1111
`/api/data/users*` is blocked for all keys. Use `/api/userAuth/*` for user management.
1212
</Warning>
1313

14-
### Required Header
14+
### Required header
1515

1616
`x-api-key`: your `pk_live_…` or `sk_live_…` key.
1717

18-
### Path Parameters
18+
### Path parameters
1919

2020
<ParamField path="collectionName" type="string" required>
2121
The name of the collection to query (e.g., `posts`, `comments`, `inventory`).
2222
</ParamField>
2323

24-
### Query Parameters
24+
### Query parameters
2525

2626
<ParamField query="page" type="number">
2727
Page number for pagination. Defaults to `1`.
@@ -41,28 +41,52 @@ Returns a list of documents from the specified collection. Supports pagination,
4141
a comparison operator. Example: `filter[status][eq]=published&filter[views][gt]=100`
4242
</ParamField>
4343

44-
### RLS Behavior
44+
<ParamField query="include_deleted" type="boolean">
45+
Setting `include_deleted` to `true` includes soft-deleted documents; it defaults to `false`
46+
</ParamField>
47+
48+
### RLS behavior
4549

4650
If the collection has **RLS** enabled:
4751

4852
- `public-read` mode: anyone can read all documents with a valid `x-api-key`.
4953
- `private` mode: requires `Authorization: Bearer <accessToken>` — only the owner's documents are returned.
5054

51-
### Response Fields
55+
### Response fields
5256

5357
<ResponseField name="success" type="boolean">
5458
`true` when the request succeeded.
5559
</ResponseField>
5660

57-
<ResponseField name="data" type="array">
58-
Array of document objects matching the query. Each document includes its `_id` and all stored fields.
61+
<ResponseField name="data" type="object">
62+
Object containing the results and pagination metadata.
63+
<Expandable title="properties">
64+
<ResponseField name="items" type="array">
65+
Array of document objects matching the query.
66+
</ResponseField>
67+
<ResponseField name="total" type="number">
68+
Total number of documents matching the query (ignoring pagination).
69+
</ResponseField>
70+
<ResponseField name="page" type="number">
71+
Current page number (present in offset-based pagination).
72+
</ResponseField>
73+
<ResponseField name="cursor" type="string">
74+
Current cursor (present in cursor-based pagination).
75+
</ResponseField>
76+
<ResponseField name="nextCursor" type="string">
77+
Cursor for the next page, or `null`.
78+
</ResponseField>
79+
<ResponseField name="limit" type="number">
80+
Number of results per page.
81+
</ResponseField>
82+
</Expandable>
5983
</ResponseField>
6084

6185
<ResponseField name="message" type="string">
6286
Human-readable status message.
6387
</ResponseField>
6488

65-
### Code Examples
89+
### Code examples
6690

6791
<CodeGroup>
6892

@@ -71,7 +95,8 @@ const params = new URLSearchParams({
7195
page: '1',
7296
limit: '10',
7397
sort: '-createdAt',
74-
'filter[status][eq]': 'published'
98+
'filter[status][eq]': 'published',
99+
include_deleted: 'true'
75100
});
76101

77102
const res = await fetch(
@@ -83,12 +108,13 @@ const res = await fetch(
83108
}
84109
);
85110

86-
const { success, data, message } = await res.json();
87-
// data is an array of matching documents
111+
const { data } = await res.json();
112+
// data.items contains the array of matching documents
113+
// data.total contains the total count
88114
```
89115

90116
```bash curl
91-
curl "https://api.ub.bitbros.in/api/data/posts?page=1&limit=10&sort=-createdAt&filter[status][eq]=published" \
117+
curl "https://api.ub.bitbros.in/api/data/posts?page=1&limit=10&sort=-createdAt&filter[status][eq]=published&include_deleted=true" \
92118
-H "x-api-key: pk_live_YOUR_KEY"
93119
```
94120

@@ -103,26 +129,35 @@ const res = await fetch('https://api.ub.bitbros.in/api/data/notes', {
103129

104130
</CodeGroup>
105131

106-
### Success Response
132+
### Success response
107133

108134
```json
109135
{
110136
"success": true,
111-
"data": [
112-
{
113-
"_id": "64fd1234abcd5678ef901234",
114-
"title": "Why BaaS is the future",
115-
"status": "published",
116-
"createdAt": "2024-01-15T10:30:00.000Z"
117-
},
118-
{
119-
"_id": "64fd5678abcd1234ef905678",
120-
"title": "Getting started with urBackend",
121-
"status": "published",
122-
"createdAt": "2024-01-14T08:00:00.000Z"
123-
}
124-
],
125-
"message": "Documents fetched successfully"
137+
"data": {
138+
"items": [
139+
{
140+
"_id": "64fd1234abcd5678ef901234",
141+
"title": "Why BaaS is the future",
142+
"status": "published",
143+
"isDeleted": false,
144+
"deletedAt": null,
145+
"createdAt": "2024-01-15T10:30:00.000Z"
146+
},
147+
{
148+
"_id": "64fd5678abcd1234ef905678",
149+
"title": "Getting started with urBackend",
150+
"status": "published",
151+
"isDeleted": true,
152+
"deletedAt": "2026-05-20T10:30:00.000Z",
153+
"createdAt": "2024-01-14T08:00:00.000Z"
154+
}
155+
],
156+
"total": 42,
157+
"page": 1,
158+
"limit": 10
159+
},
160+
"message": "Data fetched successfully"
126161
}
127162
```
128163

0 commit comments

Comments
 (0)