Tools

list_elements

Paginated element list with category filter, BM25 search, projection, and locale filtering.

list_elements

The workhorse read. Default projection is ["id","title","category_id"]; pass fields: "all" for the full element shape.

Summary

Returns elements in a schema version. Supports filtering by category_id, BM25 search via query, locale filtering, field projection, and opaque-cursor pagination.

Input

Field	Type	Required	Default	Description
`version`	`string`	yes	—	Schema version.
`category_id`	`string`	no	—	Restrict to one category.
`locale`	`string`	no	`"en"`	Locale used for the `query` search.
`locales`	`string[]`	no	—	Locales retained in localized strings.
`query`	`string`	no	—	BM25 search across title (boost 3) + description.
`fields`	`string[] \| "all"`	no	`["id","title","category_id"]`	Field projection.
`limit`	`integer`	no	`50`	Page size (1–200).
`cursor`	`string`	no	—	Opaque cursor from a previous call.

Output

{
  "ok": true,
  "data": {
    "version": "ai@2026-04-16-beta",
    "elements": [
      { "id": "purpose.example", "title": [{"locale":"en","value":"Example purpose"}], "category_id": "purpose" }
    ],
    "total": 127,
    "returned": 50
  },
  "meta": {
    "content_hash": "sha256-…",
    "version": "ai@2026-04-16-beta",
    "next_cursor": "eyJvZmZzZXQiOjUwfQ=="
  }
}

When meta.next_cursor is null, you reached the end.

Errors

Code	Meaning	Fix
`invalid_arguments`	Bad argument types (e.g. `limit` out of `[1,200]`, non-string `cursor`).	Fix the call.
`bad_request`	Malformed `cursor` value.	Discard the cursor and re-issue without it.
`unknown_version`	Version is not registered.	Call `list_schema_versions`.

Example: paginate through every element

# first page
curl -s https://api.dtpr.io/mcp \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{
      "name":"list_elements",
      "arguments":{
        "version":"ai@2026-04-16-beta",
        "fields":"all",
        "limit":50
      }
    }
  }'

# follow-up page (pass meta.next_cursor from the first response)
curl -s https://api.dtpr.io/mcp \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc":"2.0","id":2,
    "method":"tools/call",
    "params":{
      "name":"list_elements",
      "arguments":{
        "version":"ai@2026-04-16-beta",
        "fields":"all",
        "limit":50,
        "cursor":"eyJvZmZzZXQiOjUwfQ=="
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_elements",
    "arguments": {
      "version": "ai@2026-04-16-beta",
      "category_id": "purpose",
      "query": "camera",
      "locales": ["en"],
      "limit": 25
    }
  }
}

list_elements

list_elements

Summary

Input

Output

Errors

Example: paginate through every element

See also