Skip to main content

Class: AIGatewayWorkspacesClient

Defined in: src/ai-gateway/workspaces-client.ts:42

Client for AI Gateway workspaces.

The only sub-client spanning both planes: reads default to the data plane but can be routed to the admin plane, and every write is admin-only. Each of the other sub-clients is wired to exactly one plane.

Constructors​

Constructor​

new AIGatewayWorkspacesClient(opts): AIGatewayWorkspacesClient;

Defined in: src/ai-gateway/workspaces-client.ts:49

Parameters​

ParameterType
optsAIGatewayWorkspacesClientOptions

Returns​

AIGatewayWorkspacesClient

Methods​

list()​

list(options?): Promise<objectOutputType<{
  object: ZodString;
  total: ZodNumber;
  success: ZodOptional<ZodBoolean>;
  has_more: ZodOptional<ZodBoolean>;
  data: ZodArray<ZodObject<{
     id: ZodString;
     slug: ZodString;
     name: ZodString;
     icon: ZodNullable<ZodString>;
     description: ZodNullable<ZodString>;
     created_at: ZodString;
     last_updated_at: ZodString;
     is_default: ZodNumber;
     status: ZodString;
     scope_name: ZodString;
     object: ZodString;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     id: ZodString;
     slug: ZodString;
     name: ZodString;
     icon: ZodNullable<ZodString>;
     description: ZodNullable<ZodString>;
     created_at: ZodString;
     last_updated_at: ZodString;
     is_default: ZodNumber;
     status: ZodString;
     scope_name: ZodString;
     object: ZodString;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     id: ZodString;
     slug: ZodString;
     name: ZodString;
     icon: ZodNullable<ZodString>;
     description: ZodNullable<ZodString>;
     created_at: ZodString;
     last_updated_at: ZodString;
     is_default: ZodNumber;
     status: ZodString;
     scope_name: ZodString;
     object: ZodString;
  }, ZodTypeAny, "passthrough">>, "many">;
}, ZodTypeAny, "passthrough">>;

Defined in: src/ai-gateway/workspaces-client.ts:86

List workspaces.

Two defaults worth knowing, because each one hides rows:

  1. Active only. Without status, archived workspaces are omitted. Pass { status: 'archived' } to see them — that is where AIGatewayWorkspacesClient.delete leaves a workspace.
  2. Your scope only. The data plane returns just the workspaces your service account holds a workspace-scope grant on. Pass { plane: 'admin' } to enumerate the whole tenant.

Parameters​

ParameterTypeDescription
optionsAIGatewayWorkspaceListOptionsOptional status filter and plane selection.

Returns​

Promise<objectOutputType<{ object: ZodString; total: ZodNumber; success: ZodOptional<ZodBoolean>; has_more: ZodOptional<ZodBoolean>; data: ZodArray<ZodObject<{ id: ZodString; slug: ZodString; name: ZodString; icon: ZodNullable<ZodString>; description: ZodNullable<ZodString>; created_at: ZodString; last_updated_at: ZodString; is_default: ZodNumber; status: ZodString; scope_name: ZodString; object: ZodString; }, "passthrough", ZodTypeAny, objectOutputType<{ id: ZodString; slug: ZodString; name: ZodString; icon: ZodNullable<ZodString>; description: ZodNullable<ZodString>; created_at: ZodString; last_updated_at: ZodString; is_default: ZodNumber; status: ZodString; scope_name: ZodString; object: ZodString; }, ZodTypeAny, "passthrough">, objectInputType<{ id: ZodString; slug: ZodString; name: ZodString; icon: ZodNullable<ZodString>; description: ZodNullable<ZodString>; created_at: ZodString; last_updated_at: ZodString; is_default: ZodNumber; status: ZodString; scope_name: ZodString; object: ZodString; }, ZodTypeAny, "passthrough">>, "many">; }, ZodTypeAny, "passthrough">>

Workspaces, each with the scope_name that grants data-plane access to it.

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const mine = await gw.workspaces.list();
// mine.data[0] => { slug: 'ws-main-a-349e0e', scope_name: 'main_airs_workspace_1852583913', ... }

const everything = await gw.workspaces.list({ plane: 'admin' });
const archived = await gw.workspaces.list({ plane: 'admin', status: 'archived' });

get()​

get(workspaceRef, options?): Promise<objectOutputType<{
  id: ZodString;
  name: ZodString;
  description: ZodNullable<ZodString>;
  created_at: ZodString;
  last_updated_at: ZodString;
  is_default: ZodNumber;
  slug: ZodString;
  icon: ZodNullable<ZodString>;
  defaults: ZodNullable<ZodRecord<ZodString, ZodUnknown>>;
  usage_limits: ZodNullable<ZodUnion<[ZodArray<ZodObject<{
     credit_limit: ZodOptional<ZodNumber>;
     type: ZodOptional<ZodString>;
     alert_threshold: ZodOptional<ZodNumber>;
     periodic_reset: ZodOptional<ZodNullable<...>>;
     periodic_reset_days: ZodOptional<ZodNullable<...>>;
     next_usage_reset_at: ZodOptional<ZodNullable<...>>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     credit_limit: ZodOptional<...>;
     type: ZodOptional<...>;
     alert_threshold: ZodOptional<...>;
     periodic_reset: ZodOptional<...>;
     periodic_reset_days: ZodOptional<...>;
     next_usage_reset_at: ZodOptional<...>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     credit_limit: ZodOptional<...>;
     type: ZodOptional<...>;
     alert_threshold: ZodOptional<...>;
     periodic_reset: ZodOptional<...>;
     periodic_reset_days: ZodOptional<...>;
     next_usage_reset_at: ZodOptional<...>;
  }, ZodTypeAny, "passthrough">>, "many">, ZodRecord<ZodString, ZodUnknown>]>>;
  rate_limits: ZodNullable<ZodUnion<[ZodArray<ZodObject<{
     type: ZodOptional<ZodString>;
     unit: ZodOptional<ZodString>;
     value: ZodOptional<ZodNumber>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     type: ZodOptional<...>;
     unit: ZodOptional<...>;
     value: ZodOptional<...>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     type: ZodOptional<...>;
     unit: ZodOptional<...>;
     value: ZodOptional<...>;
  }, ZodTypeAny, "passthrough">>, "many">, ZodRecord<ZodString, ZodUnknown>]>>;
  security_settings: ZodOptional<ZodRecord<ZodString, ZodBoolean>>;
  data_plane_security_settings: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
  settings: ZodOptional<ZodRecord<ZodString, ZodUnknown>>;
  status: ZodOptional<ZodNullable<ZodString>>;
}, ZodTypeAny, "passthrough">>;

Defined in: src/ai-gateway/workspaces-client.ts:123

Fetch one workspace, including its security and rate-limit settings.

Parameters​

ParameterTypeDescription
workspaceRefstringWorkspace UUID or slug; the API accepts both.
optionsAIGatewayWorkspaceGetOptionsPlane selection. A workspace outside your workspace scope answers 403 AB03 on the data plane, not 404; re-read it with { plane: 'admin' }. Archived workspaces are not retrievable here. Once AIGatewayWorkspacesClient.delete has archived a workspace, this returns 404 AB08 for both its UUID and its slug, on either plane (verified live 2026-08-01) — even though the row is still listed by list({ status: 'archived' }). Treat a 404 after a delete as expected, and use the list filter to inspect archived workspaces.

Returns​

Promise<objectOutputType<{ id: ZodString; name: ZodString; description: ZodNullable<ZodString>; created_at: ZodString; last_updated_at: ZodString; is_default: ZodNumber; slug: ZodString; icon: ZodNullable<ZodString>; defaults: ZodNullable<ZodRecord<ZodString, ZodUnknown>>; usage_limits: ZodNullable<ZodUnion<[ZodArray<ZodObject<{ credit_limit: ZodOptional<ZodNumber>; type: ZodOptional<ZodString>; alert_threshold: ZodOptional<ZodNumber>; periodic_reset: ZodOptional<ZodNullable<...>>; periodic_reset_days: ZodOptional<ZodNullable<...>>; next_usage_reset_at: ZodOptional<ZodNullable<...>>; }, "passthrough", ZodTypeAny, objectOutputType<{ credit_limit: ZodOptional<...>; type: ZodOptional<...>; alert_threshold: ZodOptional<...>; periodic_reset: ZodOptional<...>; periodic_reset_days: ZodOptional<...>; next_usage_reset_at: ZodOptional<...>; }, ZodTypeAny, "passthrough">, objectInputType<{ credit_limit: ZodOptional<...>; type: ZodOptional<...>; alert_threshold: ZodOptional<...>; periodic_reset: ZodOptional<...>; periodic_reset_days: ZodOptional<...>; next_usage_reset_at: ZodOptional<...>; }, ZodTypeAny, "passthrough">>, "many">, ZodRecord<ZodString, ZodUnknown>]>>; rate_limits: ZodNullable<ZodUnion<[ZodArray<ZodObject<{ type: ZodOptional<ZodString>; unit: ZodOptional<ZodString>; value: ZodOptional<ZodNumber>; }, "passthrough", ZodTypeAny, objectOutputType<{ type: ZodOptional<...>; unit: ZodOptional<...>; value: ZodOptional<...>; }, ZodTypeAny, "passthrough">, objectInputType<{ type: ZodOptional<...>; unit: ZodOptional<...>; value: ZodOptional<...>; }, ZodTypeAny, "passthrough">>, "many">, ZodRecord<ZodString, ZodUnknown>]>>; security_settings: ZodOptional<ZodRecord<ZodString, ZodBoolean>>; data_plane_security_settings: ZodOptional<ZodRecord<ZodString, ZodUnknown>>; settings: ZodOptional<ZodRecord<ZodString, ZodUnknown>>; status: ZodOptional<ZodNullable<ZodString>>; }, ZodTypeAny, "passthrough">>

Workspace detail; list rows do not carry the settings blocks.

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const ws = await gw.workspaces.get('16f7e90d-382a-4e78-b577-1b01eb5f8297');
// ws.security_settings?.membersViewLogs => true

// Slugs work too, and the admin plane reaches workspaces you aren't scoped to:
const other = await gw.workspaces.get('ws-produc-985697', { plane: 'admin' });

create()​

create(body): Promise<objectOutputType<{
  id: ZodString;
  name: ZodString;
  slug: ZodString;
  description: ZodNullable<ZodString>;
  created_at: ZodString;
  last_updated_at: ZodString;
  scope_name: ZodString;
  object: ZodString;
  defaults: ZodOptional<ZodNullable<ZodRecord<ZodString, ZodUnknown>>>;
  users: ZodOptional<ZodArray<ZodUnknown, "many">>;
}, ZodTypeAny, "passthrough">>;

Defined in: src/ai-gateway/workspaces-client.ts:167

Create a workspace. Admin plane — needs a tenant-root admin role.

scope_name must name an IAM scope that already exists. The 2026-09-06 revalidation's 400 AB01 for synthetic scope names was this prerequisite, not a contract change: SCM's own UI (captured 2026-09-11) first POSTs /iam/v1/scopes, then creates the workspace, then PUTs the scope back with the new workspace slug bound. Use AIGatewayWorkspacesClient.provision for the whole sequence, or run gw.iamScopes.create() yourself before calling this.

Parameters​

ParameterTypeDescription
body{ name: string; scope_name: string; description?: string; icon?: string; defaults?: { metadata?: Record<string, GatewayJsonValue>; config_id?: string; allow_config_override?: boolean; }; users?: string[]; usage_limits?: { [key: string]: any; }[]; rate_limits?: { type: GatewayOpenValue<"requests" | "tokens">; unit: GatewayOpenValue<"rpd" | "rph" | "rpm" | "rps" | "rpw">; value: number; }[]; }name and scope_name are both required; the API rejects a body missing either.
body.namestring-
body.scope_namestring-
body.description?string-
body.icon?string-
body.defaults?{ metadata?: Record<string, GatewayJsonValue>; config_id?: string; allow_config_override?: boolean; }-
body.defaults.metadata?Record<string, GatewayJsonValue>-
body.defaults.config_id?string-
body.defaults.allow_config_override?boolean-
body.users?string[]-
body.usage_limits?{ [key: string]: any; }[]-
body.rate_limits?{ type: GatewayOpenValue<"requests" | "tokens">; unit: GatewayOpenValue<"rpd" | "rph" | "rpm" | "rps" | "rpw">; value: number; }[]-

Returns​

Promise<objectOutputType<{ id: ZodString; name: ZodString; slug: ZodString; description: ZodNullable<ZodString>; created_at: ZodString; last_updated_at: ZodString; scope_name: ZodString; object: ZodString; defaults: ZodOptional<ZodNullable<ZodRecord<ZodString, ZodUnknown>>>; users: ZodOptional<ZodArray<ZodUnknown, "many">>; }, ZodTypeAny, "passthrough">>

The created workspace. Unlike configs/guardrails/providers/deployments, which return short receipts, this returns most of the record — but not status, is_default, icon, usage_limits, rate_limits, or the settings blocks. Call AIGatewayWorkspacesClient.get when you need those.

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const created = await gw.workspaces.create({
  name: 'Production',
  scope_name: 'ws_production_bx7qw0', // the SCM scope, not derived from name
  description: 'All production applications',
  defaults: { metadata: { env: 'production' } },
  rate_limits: [{ type: 'requests', unit: 'rpm', value: 100 }],
});

provision()​

provision(request, options?): Promise<GatewayWorkspaceProvisionResult>;

Defined in: src/ai-gateway/workspaces-client.ts:223

Provision a workspace the way Strata Cloud Manager's UI does — three calls, in order:

  1. iamScopes.create({ name: scope_name }) — the IAM scope must exist first; creating the workspace against a missing scope fails with 400 AB01. Skipped with existingScope.
  2. workspaces.create({ ...request, scope_name }) — returns the workspace slug.
  3. iamScopes.bindWorkspace(scope_name, slug) — PUTs the scope back with { resource_type: 'workspace', resource_id: slug }, which is what actually grants data-plane access to the new workspace.

Sequence captured from SCM on 2026-09-11. Admin plane; needs a tenant-root admin role.

Partial failures are reported, not hidden. If step 2 fails after this call created the scope, the scope is deleted again (best effort) and the error says whether that rollback succeeded. If step 3 fails, the workspace exists but is unbound; the error names both the workspace slug and the scope so you can finish with gw.iamScopes.bindWorkspace(scope, slug).

Parameters​

ParameterTypeDescription
requestGatewayWorkspaceProvisionRequestA workspace create request whose scope_name is optional. When omitted, one is generated with generateWorkspaceScopeName (ws_<name>_<6 random chars>, matching SCM's own naming).
optionsAIGatewayWorkspaceProvisionOptionsexistingScope: true binds to a scope that already exists instead of creating one; scope_name is then required.

Returns​

Promise<GatewayWorkspaceProvisionResult>

The bound scope, the create response, and whether a scope was created.

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

const { scope, workspace } = await gw.workspaces.provision({
  name: 'truffles',
  description: 'Online recipe generation application',
});
// scope.name            => 'ws_truffles_ggolfu'   (generated)
// workspace.slug        => 'ws-truffl-03e7d9'
// scope.resources[0]    => { resource_type: 'workspace', resource_id: 'ws-truffl-03e7d9', metadata: [] }

// Reuse a scope you already created (bindings on it are preserved):
await gw.workspaces.provision(
  { name: 'Staging', scope_name: 'ws_staging_q1x8mz' },
  { existingScope: true },
);

update()​

update(workspaceRef, body): Promise<objectOutputType<{
  id: ZodOptional<ZodString>;
  slug: ZodOptional<ZodString>;
  version_id: ZodOptional<ZodString>;
  success: ZodOptional<ZodBoolean>;
  data: ZodOptional<ZodUnion<[ZodObject<{
     id: ZodOptional<ZodString>;
     slug: ZodOptional<ZodString>;
     version_id: ZodOptional<ZodString>;
   }, "passthrough", ZodTypeAny, objectOutputType<{
     id: ZodOptional<ZodString>;
     slug: ZodOptional<ZodString>;
     version_id: ZodOptional<ZodString>;
   }, ZodTypeAny, "passthrough">, objectInputType<{
     id: ZodOptional<ZodString>;
     slug: ZodOptional<ZodString>;
     version_id: ZodOptional<ZodString>;
  }, ZodTypeAny, "passthrough">>, ZodString, ZodNumber]>>;
}, ZodTypeAny, "passthrough">>;

Defined in: src/ai-gateway/workspaces-client.ts:303

Update a workspace. Admin plane. Partial patch — send only the fields that change.

Parameters​

ParameterTypeDescription
workspaceRefstringWorkspace UUID or slug.
body{ [key: string]: any; }At least one field. An empty patch is rejected locally, mirroring the API's own "No update fields provided" rejection, so a typo'd caller fails without a round trip.

Returns​

Promise<objectOutputType<{ id: ZodOptional<ZodString>; slug: ZodOptional<ZodString>; version_id: ZodOptional<ZodString>; success: ZodOptional<ZodBoolean>; data: ZodOptional<ZodUnion<[ZodObject<{ id: ZodOptional<ZodString>; slug: ZodOptional<ZodString>; version_id: ZodOptional<ZodString>; }, "passthrough", ZodTypeAny, objectOutputType<{ id: ZodOptional<ZodString>; slug: ZodOptional<ZodString>; version_id: ZodOptional<ZodString>; }, ZodTypeAny, "passthrough">, objectInputType<{ id: ZodOptional<ZodString>; slug: ZodOptional<ZodString>; version_id: ZodOptional<ZodString>; }, ZodTypeAny, "passthrough">>, ZodString, ZodNumber]>>; }, ZodTypeAny, "passthrough">>

An empty object — the API acknowledges the write without echoing the record (verified live 2026-08-01). The change does persist; re-read with AIGatewayWorkspacesClient.get to see it.

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

await gw.workspaces.update('ws-produc-985697', {
  description: 'Production workloads, us-east',
});

delete()​

delete(workspaceRef): Promise<void>;

Defined in: src/ai-gateway/workspaces-client.ts:345

Delete a workspace. Admin plane.

This is a soft delete: the workspace is archived, not destroyed. It vanishes from a default AIGatewayWorkspacesClient.list but stays visible via list({ status: 'archived' }). Note that list is the only way to see it afterwards — AIGatewayWorkspacesClient.get answers 404 AB08 for an archived workspace. Same semantics as deployments.delete(), and the opposite of configs/guardrails/providers, which hard delete. There is no hard delete for workspaces.

Takes no query parameters — unlike integrations.delete() and deployments.delete(), which both require organisation_id.

Parameters​

ParameterTypeDescription
workspaceRefstringWorkspace UUID or slug.

Returns​

Promise<void>

Example​

import { AIGatewayClient } from '@cdot65/prisma-airs-sdk';
const gw = new AIGatewayClient();

await gw.workspaces.delete('ws-produc-985697');

// Still there, archived:
const gone = await gw.workspaces.list({ plane: 'admin', status: 'archived' });