> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ub.bitbros.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Insert Document

> Create a new document in a collection.

## POST `/api/data/:collectionName`

Inserts a new document into the specified collection and returns the created document on success.

### Required header

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

### Path parameters

<ParamField path="collectionName" type="string" required>
  The name of the collection to insert into (e.g., `posts`, `orders`).
</ParamField>

### Request body

Send a JSON object containing the document fields. The fields must conform to the collection's schema if one is defined.

<Note>
  When using `pk_live` with RLS enabled, the owner field (e.g., `userId`) is automatically
  injected from the authenticated user's JWT if you omit it. If you include the owner field
  but it doesn't match the token's user ID, the request is rejected with `403`.
</Note>

### Response fields

The endpoint returns the created document object directly.

<ResponseField name="_id" type="string">
  The assigned unique MongoDB ObjectId string.
</ResponseField>

<ResponseField name="isDeleted" type="boolean">
  Always `false` for new documents.
</ResponseField>

<ResponseField name="deletedAt" type="string">
  Always `null` for new documents.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO date string of when the document was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO date string of when the document was last updated.
</ResponseField>

<Note>
  Other fields returned depend on your collection schema and the data sent.
</Note>

### Code examples

<CodeGroup>
  ```javascript sk_live (server-side) theme={null}
  // Use sk_live from your server — never expose it in frontend code
  const res = await fetch('https://api.ub.bitbros.in/api/data/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'sk_live_YOUR_SECRET_KEY'
    },
    body: JSON.stringify({
      title: 'Why BaaS is the future',
      body: 'Content goes here...',
      tags: ['tech', 'development'],
      meta: { views: 0, likes: 0 },
      userId: 'USER_ID'
    })
  });

  const doc = await res.json();
  // doc is the created document object
  ```

  ```javascript pk_live + RLS (client-side) theme={null}
  // Use pk_live + user JWT when collection has RLS enabled
  // userId is auto-injected from the JWT — no need to include it
  const res = await fetch('https://api.ub.bitbros.in/api/data/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'pk_live_YOUR_KEY',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      title: 'My first post',
      body: 'Hello world'
    })
  });

  const doc = await res.json();
  // doc.userId is set to the authenticated user's ID automatically
  ```

  ```bash curl (sk_live) theme={null}
  curl -X POST "https://api.ub.bitbros.in/api/data/posts" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk_live_YOUR_SECRET_KEY" \
    -d '{
      "title": "Server-side insert",
      "body": "Content goes here...",
      "userId": "USER_ID"
    }'
  ```
</CodeGroup>

### Success response

```json theme={null}
{
  "_id": "64fd1234abcd5678ef901234",
  "title": "My first post",
  "body": "Hello world",
  "userId": "64fd0000abcd5678ef900001",
  "isDeleted": false,
  "deletedAt": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}
```

### Errors

| Status             | Cause                                                                                   |
| :----------------- | :-------------------------------------------------------------------------------------- |
| `400 Bad Request`  | Schema validation failed — missing required field or wrong type                         |
| `401 Unauthorized` | Missing/invalid API key, or missing Bearer token when using `pk_live` with RLS          |
| `403 Forbidden`    | `pk_live` without RLS enabled, or owner field in body doesn't match the token's user ID |