Data Access

Reading Data

Read items from your collections via REST or SDK.

Get All Items

Returns a list of items from a collection. By default, results are limited to 100 items and the API response is wrapped in a { data: [...] } envelope (the SDK unwraps this automatically).

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://example.monospace.io/api/blog/items/articles?fields=id,title,status', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

By default, results are limited to 100 items. Use limit and offset to paginate — see Sorting & Pagination.

Get a Single Item by ID

Fetches a single item by its primary key. Append the key value to the collection URL in REST, or pass it as the key property in the SDK.

const article = await client.Articles.readOne({
  key: 1,
  fields: ['id', 'title', 'content'],
});

curl -g "https://example.monospace.io/api/blog/items/articles/1?fields=id,title,content" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://example.monospace.io/api/blog/items/articles/1?fields=id,title,content', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Combine limit=1 with a filter and sort to return a single matching item. In REST you must extract the first element from the returned array. The SDK provides a dedicated readFirst() method that returns T | null directly.

const latest = await client.Articles.readFirst({
  fields: ['id', 'title'],
  filter: { status: { _eq: 'published' } },
  sort: [{ created_at: { direction: 'desc' } }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title&filter[status][_eq]=published&sort[0][created_at][direction]=desc&limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  'fields': 'id,title',
  'filter[status][_eq]': 'published',
  'sort[0][created_at][direction]': 'desc',
  limit: '1',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();
const latest = data[0] ?? null;

The SDK provides readFirst() as a convenience for this pattern, returning T | null directly. It accepts the same parameters as readMany but automatically sets limit: 1 and unwraps the single result.

Choose Which Fields to Return

Use the fields parameter to select only the fields you need. This reduces payload size and improves performance. Omitting fields returns all top-level primitive fields by default.

Use fields=* (REST) or fields: ['*'] (SDK) to explicitly request all top-level primitive fields:

const articles = await client.Articles.readMany({
  fields: ['*'],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=*" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/articles?fields=*',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

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

Or select specific fields:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', 'status'],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

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

See Field Selection for nested fields, wildcards, and advanced patterns.

Request fields from related collections using dot notation in REST or object syntax in the SDK.

Shorthand Syntax

In REST, use dot notation within the fields parameter. In the SDK, use an object mapping the relation name to an array of fields:

const articles = await client.Articles.readMany({
  fields: ['id', 'title', { author: ['first_name', 'last_name'] }],
});

curl -g "https://example.monospace.io/api/blog/items/articles?fields=id,title,author.first_name,author.last_name" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  fields: 'id,title,author.first_name,author.last_name',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/articles?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

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

When you request fields from a to-many relation, the related items are wrapped in a { data: [...] } envelope — they are not returned as a bare array. This applies to both REST and SDK responses (before unwrapping).For example, requesting an author with their articles returns:

{
  "data": {
    "id": 1,
    "name": "Alice",
    "articles": {
      "data": [
        { "title": "First Post", "status": "published" },
        { "title": "Second Post", "status": "draft" }
      ]
    }
  }
}

This envelope structure allows future non-breaking additions such as inline pagination metadata (e.g., total count) on related collections.

Expanded Syntax

To filter, sort, or limit related items, REST and the SDK use different approaches that are functionally equivalent:

REST — use fields with dot notation for the nested fields, plus the deep parameter for filtering, sorting, and limiting the relation.
SDK — use an expanded object with fields, filter, sort, limit, and offset co-located under the relation key.

const authors = await client.Authors.readMany({
  fields: [
    'id',
    'name',
    {
      posts: {
        fields: ['id', 'title'],
        filter: { status: { _eq: 'published' } },
        sort: [{ created_at: { direction: 'desc' } }],
        limit: 5,
      },
    },
  ],
});

curl -g "https://example.monospace.io/api/blog/items/authors?fields=id,name,posts.id,posts.title&deep[posts][_filter][status][_eq]=published&deep[posts][_sort][0][created_at][direction]=desc&deep[posts][_limit]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  'fields': 'id,name,posts.id,posts.title',
  'deep[posts][_filter][status][_eq]': 'published',
  'deep[posts][_sort][0][created_at][direction]': 'desc',
  'deep[posts][_limit]': '5',
});

const response = await fetch(
  `https://example.monospace.io/api/blog/items/authors?${params}`,
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

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

This is a brief example. See Field Selection for wildcards, deep nesting, and advanced patterns.

The SDK unwraps the { data } envelope automatically. See Client Setup for the unwrapEnvelope option.