Workspaces & organizations

This documents the v1 product. It is kept for integrations already running on it. If you are building something new, start with the Quickstart.

A workspace holds assistants and telephony numbers and belongs to an organization. The workspace _id you get here is the workspace header value for every workspace-scoped call afterwards.

Onboard a custom workspace

POST /v2/workspace/onboard/custom

The recommended path for every non-Shopify integration.

Field	Type	Required	Description
`name`	string	yes	Display name; a unique slug is derived from it.
`currencyCode`	string(3)	yes	ISO 4217, uppercased. `INR`, `USD`.
`timezone`	string	yes	IANA identifier, e.g. `Asia/Kolkata`.
`supportContacts.phoneNumber`	string	yes	E.164.
`supportContacts.email`	string	no
`trustSignals.valuePropositionOneLiner`	string	yes	One line used to ground the assistant.

curl -X POST https://api.voice-agents.miraiminds.co/v2/workspace/onboard/custom \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Support Line",
    "currencyCode": "INR",
    "timezone": "Asia/Kolkata",
    "supportContacts": { "phoneNumber": "+919876543210", "email": "support@acme.com" },
    "trustSignals": { "valuePropositionOneLiner": "Premium 24x7 support for Acme customers." }
  }'

200 OK

{
  "message": "Workspace onboarded successfully.",
  "data": {
    "_id": "6690a1b2c3d4e5f600000002",
    "name": "Acme Support Line",
    "variant": "custom"
  }
}

Keep data._id — it is your workspace header from now on.

Auto-assigned numberIn production a default telephony number is assigned to every new workspace. List it through the Telephony APIs before buying another.

Status	Cause
`400`	Validation error, or the organization is archived
`403`	Stand-alone organizations cannot create new workspaces
`409`	A workspace with this name already exists

Onboard a Shopify store

POST /v2/workspace/onboard/shopify

Shopify merchants only — creates the workspace and configures billing in one step. Returns 201 with workspace, status and a billing block:

201 Created

{
  "workspace": "6690a1b2c3d4e5f600000002",
  "status": "active",
  "billing": {
    "type": "prepaid",
    "creditBalance": 100,
    "negativeCreditAllowance": 100
  }
}

negativeCreditAllowance is an overdraft: calls keep running that far past zero before the workspace is suspended.

Archive

POST /v1/admin/organization/archive

Requires an admin or organization_admin role.

curl -X POST https://api.voice-agents.miraiminds.co/v1/admin/organization/archive \
  -H "x-public-key: pk_1234567890abcdef1234567890abcdef" \
  -H "x-private-key: sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "type": "workspace", "id": "6690a1b2c3d4e5f600000002" }'

Field	Values
`type`	`organization` \| `workspace`
`id`	ObjectId of the target

200 OK

{ "status_code": 200, "message": "Workspace archived successfully.", "data": null }

Archiving cascades: archiving an organization archives its workspaces, assistants and campaigns; archiving a workspace archives its assistants and campaigns. Archived assistants cannot be updated (400) and cannot place calls.

Unarchive

POST /v1/admin/organization/unarchive

Same body. Unarchiving also cascades. A workspace cannot be unarchived while its parent organization is still archived:

400 Bad Request

{ "code": 400, "message": "Cannot unarchive workspace. Parent Organization is archived." }

Unarchive the organization first.

Start

Developer guides

API v1 reference

Endpoints

Guides

Integrations

Use cases

Workspaces & organizations

Onboard a custom workspace

Onboard a Shopify store

Archive

Unarchive

​Onboard a custom workspace

​Onboard a Shopify store

​Archive

​Unarchive

Onboard a custom workspace

Onboard a Shopify store

Archive

Unarchive