> ## Documentation Index > Fetch the complete documentation index at: https://docs.hq.zone/llms.txt > Use this file to discover all available pages before exploring further. # Create a new workspace > Greenfield-creates a brand-new tenant owned by the caller and switches the session into it - the authenticated, in-product counterpart to the public magic-link `/v1/auth/signup` funnel. Shares the exact same atomic provisioning (`signup::provision_email_tenant`), so the new workspace gets the identical onboarding flow; the only differences are that the owner is taken from the caller's verified session email (no re-entry, no magic-link round-trip) and the session cookie is re-minted for the new tenant on the way out. Still invite-gated: an `invite_code` is required and consumed single-use, so an authenticated member can't mint workspaces freely. Web-session only - a PAT / OAuth token is pinned to one workspace and can't create another. Idempotency: the single-use invite row is the HARD guard (no double-create even under concurrency or a cache outage). An optional `Idempotency-Key` header adds soft lost-response replay - a retry with the same key returns the already-created workspace instead of a spurious "invite already used". ## OpenAPI ````yaml POST /v1/api/me/workspaces openapi: 3.1.0 info: title: HQ API description: >- Public HTTP API for HQ. Authenticate with a Personal Access Token (`Authorization: Bearer hq_pat_...`) for server-side integrations, or an OAuth 2.1 authorization-code + PKCE flow for browser apps acting on a user's behalf. Both grant from the same resource:action scope vocabulary; an endpoint's required scope is listed under its `security`. license: name: Apache-2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://api.hq.zone description: HQ API (production) security: [] tags: - name: me description: The signed-in user's own account - name: conversations description: Conversations and their messages - name: documents description: The content-addressed documents library - name: schedules description: Scheduled prompts and recurring tasks - name: agents description: Agents, their skills and integrations - name: memory description: What the assistant remembers (L5 governance) - name: tokens description: Personal Access Token management - name: billing description: Usage and billing - name: notifications description: In-app notification center - name: admin description: Workspace administration - name: integrations description: Workspace integrations (Slack, MCP, skills) - name: onboarding description: New-workspace onboarding wizard - name: auth description: Sign-in, sessions, and OAuth paths: /v1/api/me/workspaces: post: tags: - me summary: Create a new workspace description: >- Greenfield-creates a brand-new tenant owned by the caller and switches the session into it - the authenticated, in-product counterpart to the public magic-link `/v1/auth/signup` funnel. Shares the exact same atomic provisioning (`signup::provision_email_tenant`), so the new workspace gets the identical onboarding flow; the only differences are that the owner is taken from the caller's verified session email (no re-entry, no magic-link round-trip) and the session cookie is re-minted for the new tenant on the way out. Still invite-gated: an `invite_code` is required and consumed single-use, so an authenticated member can't mint workspaces freely. Web-session only - a PAT / OAuth token is pinned to one workspace and can't create another. Idempotency: the single-use invite row is the HARD guard (no double-create even under concurrency or a cache outage). An optional `Idempotency-Key` header adds soft lost-response replay - a retry with the same key returns the already-created workspace instead of a spurious "invite already used". operationId: create_workspace requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceReq' required: true responses: '200': description: Workspace created; session re-scoped to it (fresh cookie set) content: application/json: schema: $ref: '#/components/schemas/CreateWorkspaceResp' '400': description: >- Web-session-only, or the caller has no verified email to own a workspace '403': description: >- Missing / invalid / used invite, or the account is over its workspace quota '409': description: A create with this Idempotency-Key is already in flight security: - cookie_session: [] components: schemas: CreateWorkspaceReq: type: object required: - workspace_name - invite_code properties: invite_code: type: string description: >- Invite code (`inv-…`). Required and consumed single-use - creating a workspace is invite-gated even for an already-authenticated member, so a signed-in user can't mint workspaces without an invite to spend. website: type: - string - 'null' description: >- Optional company website / domain; seeds the brand-style crawl. Falls back to the caller's email domain (unless free-mail) when omitted. workspace_name: type: string description: Display name for the new workspace; the URL slug derives from it. CreateWorkspaceResp: type: object required: - slug - name - onboarded properties: name: type: string description: Display name. onboarded: type: boolean description: >- `false` for a fresh create (the SPA lands the owner on `/onboarding`); on an idempotent replay it reflects the tenant's real onboarding state. slug: type: string description: Slug of the freshly created workspace. securitySchemes: cookie_session: type: apiKey in: cookie name: hq-session description: >- Browser session cookie set by sign-in. Web SPA only; not for PAT/OAuth integrators. ````