Workspaces

A workspace is a division inside an organization with its own API keys, limits, spend and data. Teams typically create one workspace per environment (production, staging) or per product or customer, so that a test script cannot use production’s budget and a key from one product cannot see another’s files or agents.

What belongs to a workspace

Usage and cost are recorded per workspace, so the usage and cost reports can be grouped by workspace_id.

Endpoints

Authenticate with an admin key and send syntic-beta: admin-2026-11-01. Owners and Administrators can manage every workspace.

The workspace object

{
  "id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
  "type": "workspace",
  "name": "production",
  "description": "Customer-facing traffic.",
  "is_default": false,
  "data_region": "us",
  "allowed_ips": [],
  "spend_limit_usd": "2000.00",
  "rate_limits": [{ "model": "Amara S1.2", "requests_per_minute": 800 }],
  "archived_at": null,
  "created_at": "2026-11-01T09:00:00Z"
}

Create a workspace

POST /v1/organizations/workspaces with name (required), description, data_region (default us) and allowed_ips.

curl -sS https://app.syntic.ai/v1/organizations/workspaces \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: admin-2026-11-01" \
  -H "Idempotency-Key: ws-staging-2026-11" \
  -d '{"name": "staging", "description": "Pre-release testing."}'

const res = await fetch('https://app.syntic.ai/v1/organizations/workspaces', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_ADMIN_KEY}`,
    'Content-Type': 'application/json',
    'syntic-beta': 'admin-2026-11-01',
    'Idempotency-Key': 'ws-staging-2026-11',
  },
  body: JSON.stringify({ name: 'staging', description: 'Pre-release testing.' }),
})
const ws = await res.json()
console.log(ws.id)

import os, requests
 
ws = requests.post(
    "https://app.syntic.ai/v1/organizations/workspaces",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_ADMIN_KEY']}",
        "syntic-beta": "admin-2026-11-01",
        "Idempotency-Key": "ws-staging-2026-11",
    },
    json={"name": "staging", "description": "Pre-release testing."},
).json()
print(ws["id"])

List workspaces

GET /v1/organizations/workspaces?limit=20&include_archived=false returns the standard list shape.

Archive

Archiving is how you shut a workspace down safely:

• Every inference key in it fails with 403 permission, code workspace_archived, at once.
• Running agent sessions are interrupted; deployments are paused.
• Files, sessions, memory and other data are kept, subject to retention, and can be read again after unarchiving.
• The workspace’s name stays reserved until it is unarchived or an Owner deletes it in the Console.

Workspace members and roles

An organization member can be added to any number of workspaces. Owners and Administrators can act in every workspace without being added.

Add a member: POST .../members with {"user_id": "user_...", "role": "workspace_developer"}. Change it: PATCH .../members/{user_id} with {"role": "..."}. Remove: DELETE .../members/{user_id}; their keys in the workspace stop working.

{
  "type": "workspace_member",
  "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
  "user_id": "user_01J9Y0A2C4E6G8J0L2N4",
  "role": "workspace_developer",
  "added_at": "2026-11-02T10:00:00Z"
}

Errors

Errors use the error envelope.

Limits

Workspaces are free.

Build notes for the platform team

• Design the workspace schema before the Files and Batches tables are final, so those tables are born with workspace_id.
• Migration: create Default for every organization, set workspace_id on every key and usage row, then make the column required.
• The auth step resolves key → workspace → organization once and passes both ids down; every query filters on workspace_id.

Related

• Members
• API key management
• Spend limits
• Data residency