Data Access

Writing Data

Create, update, and delete items in your collections.

The fields parameter on write operations controls which fields are included in the response — it does not affect which data is written. All fields in data are always persisted.

Use include alongside fields to return related data, using the same syntax as read requests. See Field Selection for syntax details.

Create a Single Item

Creates a single item in the collection and returns it. Send a POST request with the item data in the request body.

const newArticle = await client.Articles.createOne({
  data: { title: 'Getting Started with Monospace', status: 'draft' },
  fields: ['id', 'title', 'status'],
});

curl -X POST "https://example.monospace.io/api/blog/items/Articles?fields=id,title,status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started with Monospace",
    "status": "draft"
  }'

const params = new URLSearchParams({ fields: 'id,title,status' });

const response = await fetch(
  `https://example.monospace.io/api/blog/items/Articles?${params}`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([{
      title: 'Getting Started with Monospace',
      status: 'draft',
    }]),
  },
);

const { data } = await response.json();

Create Multiple Items at Once

Creates several items in a single request. The request body is always an array of objects.

const newTags = await client.Tags.createMany({
  data: [{ name: 'TypeScript' }, { name: 'GraphQL' }, { name: 'REST' }],
  fields: ['id', 'name'],
});

curl -X POST "https://example.monospace.io/api/blog/items/Tags?fields=id,name" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "TypeScript" },
    { "name": "GraphQL" },
    { "name": "REST" }
  ]'

const params = new URLSearchParams({ fields: 'id,name' });

const response = await fetch(
  `https://example.monospace.io/api/blog/items/Tags?${params}`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([
      { name: 'TypeScript' },
      { name: 'GraphQL' },
      { name: 'REST' },
    ]),
  },
);

const { data } = await response.json();

Update a Single Item by ID

Patches a single item identified by its primary key. Only the provided fields are modified — all other fields remain unchanged. Send a PATCH request with the fields you want to change.

const updated = await client.Articles.updateOne({
  key: 1,
  data: { status: 'published', published_at: '2026-02-25T12:00:00Z' },
  fields: ['id', 'status', 'published_at'],
});

curl -X PATCH "https://example.monospace.io/api/blog/items/Articles/1?fields=id,status,published_at" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "published",
    "published_at": "2026-02-25T12:00:00Z"
  }'

const params = new URLSearchParams({ fields: 'id,status,published_at' });

const response = await fetch(
  `https://example.monospace.io/api/blog/items/Articles/1?${params}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      status: 'published',
      published_at: '2026-02-25T12:00:00Z',
    }),
  },
);

const { data } = await response.json();

Update Multiple Items by Filter

Updates all items matching a filter. The same changes are applied to every matched item.

const archived = await client.Articles.updateMany({
  filter: { status: { _eq: 'draft' }, created_at: { _lt: '2025-01-01' } },
  data: { status: 'archived' },
  fields: ['id', 'status'],
});

curl -X PATCH -g "https://example.monospace.io/api/blog/items/Articles?filter[status][_eq]=draft&filter[created_at][_lt]=2025-01-01&fields=id,status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "archived" }'

const params = new URLSearchParams({
  'filter[status][_eq]': 'draft',
  'filter[created_at][_lt]': '2025-01-01',
  fields: 'id,status',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/Articles?${params}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'archived' }),
  },
);

const { data } = await response.json();

Delete a Single Item by ID

Permanently removes a single item identified by its primary key. The response is a { data } envelope. Add fields to return the deleted item in data.

await client.Comments.deleteOne({ key: 99 });

curl -X DELETE https://example.monospace.io/api/blog/items/Comments/99 \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch('https://example.monospace.io/api/blog/items/Comments/99', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

Delete Multiple Items by Filter

Permanently removes all items matching a filter in a single request.

await client.Comments.deleteMany({
  filter: { flagged: { _eq: true } },
});

curl -X DELETE -g "https://example.monospace.io/api/blog/items/Comments?filter[flagged][_eq]=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  'filter[flagged][_eq]': 'true',
});

await fetch(`https://example.monospace.io/api/blog/items/Comments?${params}`, {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

Warning

Bulk deletes are irreversible. Double-check your filter before executing.

Return the Result After Writing

Add the fields parameter to any create or update request to return the written data in the response. This saves a follow-up read request. To return related data, add include alongside fields, using the same syntax as read requests.

const article = await client.Articles.createOne({
  data: { title: 'Return Fields on Write', status: 'draft' },
  fields: ['id', 'title', 'status', 'created_at'],
});

curl -X POST "https://example.monospace.io/api/blog/items/Articles?fields=id,title,status,created_at" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "title": "Return Fields on Write",
    "status": "draft"
  }]'

const params = new URLSearchParams({
  fields: 'id,title,status,created_at',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/Articles?${params}`,
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify([{
      title: 'Return Fields on Write',
      status: 'draft',
    }]),
  },
);

const { data } = await response.json();

Tip

Create related items inline — see Relational Data.