insert.mdx

title	Insert Document
description	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

The name of the collection to insert into (e.g., `posts`, `orders`).

Request body

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

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`.

Response fields

The endpoint returns the created document object directly.

The assigned unique MongoDB ObjectId string. Always `false` for new documents. Always `null` for new documents. ISO date string of when the document was created. ISO date string of when the document was last updated. Other fields returned depend on your collection schema and the data sent.

Code examples

// Use sk_live from your server — never expose it in frontend code
const res = await fetch('https://api.urbackend.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

// 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.urbackend.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

curl -X POST "https://api.urbackend.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"
  }'

Success response

{
  "_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