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. 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. Returns no content on success.

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',
  },
});

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.

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();

Create related items inline — see Relational Data.