Calling conventions

The call primitive is the workhorse on every surface. It substitutes path placeholders, builds the query string, attaches Cloudpath authentication, and returns the response. This page covers the conventions that apply to every call.

The return shape

call always resolves to the same object:

{ ok, status, statusText, headers, body, durationMs, url, retried }

Caution

HTTP errors are never thrown. A 404 or 500 from Cloudpath comes back as a resolved result with ok: false and the status code — always inspect ok and status rather than relying on a thrown exception.

async () => {
  const r = await core.call({ method: 'GET', path: '/authServers' });
  if (!r.ok) return { error: r.status, body: r.body };
  return { total: r.body?.page?.totalCount };
}

Path parameters

Path templates use {paramName} placeholders. Pass values via pathParams:

await core.call({
  method: 'GET',
  path: '/dpskPools/{guid}/dpsks',
  pathParams: { guid: 'pool-guid-here' },
});

Pagination

Cloudpath list responses use a pagination envelope:

{ page: { page, pageSize, totalCount }, contents: [ /* ... */ ] }

Request a page with ?page=N via the query parameter. pageSize is server-controlled (up to 1000 records), so read it back from the response rather than setting it.

async () => {
  const all = [];
  for (let page = 1; page <= 10; page++) {
    const r = await core.call({ method: 'GET', path: '/registrationLists', query: { page } });
    if (!r.ok) return { error: r.status, body: r.body };
    const contents = r.body?.contents ?? [];
    all.push(...contents);
    const info = r.body?.page ?? {};
    const pageSize = info.pageSize ?? contents.length;
    const totalPages = pageSize > 0 ? Math.ceil((info.totalCount ?? 0) / pageSize) : 1;
    if (page >= totalPages || contents.length === 0) break;
  }
  return { count: all.length };
}

Filtering and sorting

Both are query-string conventions on Cloudpath list endpoints:

	Syntax	Notes
Filter	?filter=prop(op:val),prop2(op:val2)	Operators: like, eq, in. For in, the value is underscore-separated: val1_val2_val3
Sort	?orderBy=prop:desc,prop2:asc	Comma-separated prop:direction pairs

Authentication and the automatic retry

Authentication is handled for you. CP-MCP mints a short-lived Cloudpath JWT from your saved credentials, caches it, and attaches it to every request as the raw Authorization header (Cloudpath does not accept a Bearer prefix).

If Cloudpath returns 401 or 406, CP-MCP mints a fresh token once and retries the call exactly one time. The retried field in the response is 1 when that happened. Persistent auth failures surface to the model as ok: false. See the full lifecycle in Security model.

Sending a body

For JSON, pass a plain object/array/string/number/boolean as body. For binary uploads (multipart image uploads), you must base64-encode the raw request bytes and pass them as bodyBase64 instead — the isolate marshals tool arguments through JSON.stringify, which silently destroys Uint8Array, FormData, and Blob. Passing both body and bodyBase64 returns an invalid_body error. See Generating portal images for the worked multipart pattern.