Data Access

Field Selection

Choose which fields to return and query included relations.

Select Specific Fields

Request only the fields you need. This reduces response size and improves performance.

Return only id, title, and status from articles:

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

fields selects primitive fields only. Use include alongside fields to select relations, as shown in the next section.

Tip

In REST requests, omitting fields selects no primitive fields; pass fields=* to select them all. The SDK defaults fields to ['*'] at the top level and inside every include.

Include Fields from a To-One Relation

Select a relation with include and use its fields parameter to choose which fields to return.

Return each article's id and title along with the author's name and email:

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

curl -g "https://example.monospace.io/api/blog/items/Articles?fields=id,title&include[author][fields]=name,email" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/blog/items/Articles?fields=id,title&include[author][fields]=name,email',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

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

In REST, each key under include names a relation, and its fields parameter lists the related item's primitive fields. In the SDK, place the include object alongside fields. Naming a relation in include selects it; do not also list it in fields.

Include Fields from a To-Many Relation

Select a collection of related items. The syntax is the same as to-one relations.

Return each author's id and name along with their articles' title and status:

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

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

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

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

Use Wildcards Inside an Include

The * wildcard selects every primitive field at that level, including inside an include. Wildcards do not select relations; add each relation to include.

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

curl -g "https://example.monospace.io/api/blog/items/Articles?fields=*&include[author][fields]=*" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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

Note

Fields selected by a wildcard appear in alphabetical order, after any fields you name explicitly.

Select Fields Across Multiple Relation Levels

To query relations at multiple levels, add a nested include for each level.

Return each author with their articles, each article's comments, and each comment's author name:

const authors = await client.Authors.readMany({
  fields: ['id', 'name'],
  include: {
    articles: {
      fields: ['title'],
      include: {
        comments: {
          fields: ['body', 'created_at'],
          include: {
            author: { fields: ['name'] },
          },
        },
      },
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title&include[articles][include][comments][fields]=body,created_at&include[articles][include][comments][include][author][fields]=name" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  fields: 'id,name',
  'include[articles][fields]': 'title',
  'include[articles][include][comments][fields]': 'body,created_at',
  'include[articles][include][comments][include][author][fields]': 'name',
});

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

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

Warning

Deeply nested queries can be expensive. Set limit on a to-many include to keep response times predictable.

Filter an Included Relation

Add filter alongside fields inside the include. Relation parameters have no underscore prefix; filter operators such as _eq keep theirs.

Filter a To-Many Relation

Return each author with only their published articles:

const authors = await client.Authors.readMany({
  fields: ['id', 'name'],
  include: {
    articles: {
      fields: ['title', 'status'],
      filter: { status: { _eq: 'published' } },
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title,status&include[articles][filter][status][_eq]=published" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title,status');
url.searchParams.set('include[articles][filter][status][_eq]', 'published');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Filter a To-One Relation

Return each article, including author details only when the author is active. A nullable to-one relation accepts filter alongside its field and relation selections.

const articles = await client.Articles.readMany({
  fields: ['id', 'title'],
  include: {
    author: {
      fields: ['name', 'email'],
      filter: { active: { _eq: true } },
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Articles?fields=id,title&include[author][fields]=name,email&include[author][filter][active][_eq]=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Articles');
url.searchParams.set('fields', 'id,title');
url.searchParams.set('include[author][fields]', 'name,email');
url.searchParams.set('include[author][filter][active][_eq]', 'true');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

The available parameters depend on the relation type:

Relation	Parameters beyond `fields` and `include`
To-many	`filter`, `sort`, `limit`, `offset`
Nullable to-one	`filter`
Required to-one	None

Passing a parameter the relation does not accept returns HTTP 422.

Sort an Included Relation

Add sort inside the include to order the related items.

Return each author with their articles sorted by created_at descending:

const authors = await client.Authors.readMany({
  fields: ['id', 'name'],
  include: {
    articles: {
      fields: ['title', 'created_at'],
      sort: [{ created_at: { direction: 'desc' } }],
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title,created_at&include[articles][sort][0][created_at][direction]=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title,created_at');
url.searchParams.set('include[articles][sort][0][created_at][direction]', 'desc');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Paginate an Included Relation

Add limit and offset inside the include to page through the related items.

Return each author with their 5 most recent articles:

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

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title,created_at&include[articles][sort][0][created_at][direction]=desc&include[articles][limit]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title,created_at');
url.searchParams.set('include[articles][sort][0][created_at][direction]', 'desc');
url.searchParams.set('include[articles][limit]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Skip the first 5 articles and return the next 5:

const authors = await client.Authors.readMany({
  fields: ['id', 'name'],
  include: {
    articles: {
      fields: ['title'],
      limit: 5,
      offset: 5,
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title&include[articles][limit]=5&include[articles][offset]=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title');
url.searchParams.set('include[articles][limit]', '5');
url.searchParams.set('include[articles][offset]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Combine Filter, Sort, and Pagination

Apply filter, sort, limit, and offset together on one include.

Return each author with their 5 most recent published articles:

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

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

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title,status,created_at');
url.searchParams.set('include[articles][filter][status][_eq]', 'published');
url.searchParams.set('include[articles][sort][0][created_at][direction]', 'desc');
url.searchParams.set('include[articles][limit]', '5');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

Apply Arguments at Multiple Levels

Set parameters separately for each included relation, at any nesting level.

Return each author with their published articles, and each article with only approved comments:

const authors = await client.Authors.readMany({
  fields: ['id', 'name'],
  include: {
    articles: {
      fields: ['title'],
      filter: { status: { _eq: 'published' } },
      include: {
        comments: {
          fields: ['body', 'created_at'],
          filter: { approved: { _eq: true } },
        },
      },
    },
  },
});

curl -g "https://example.monospace.io/api/blog/items/Authors?fields=id,name&include[articles][fields]=title&include[articles][filter][status][_eq]=published&include[articles][include][comments][fields]=body,created_at&include[articles][include][comments][filter][approved][_eq]=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const url = new URL('https://example.monospace.io/api/blog/items/Authors');
url.searchParams.set('fields', 'id,name');
url.searchParams.set('include[articles][fields]', 'title');
url.searchParams.set('include[articles][filter][status][_eq]', 'published');
url.searchParams.set('include[articles][include][comments][fields]', 'body,created_at');
url.searchParams.set('include[articles][include][comments][filter][approved][_eq]', 'true');

const response = await fetch(url, {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});

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

In REST, repeat include at each nesting level: include[articles][include][comments][filter]. The shorter form include[articles][comments] does not select a nested relation. In the SDK, nest an include object at each level.

SDK

The SDK serializes nested include objects into include[...] query parameters automatically. See Type System.