Create Workspace

post/v1/workspaces

Creates a new workspace (or a sub-workspace when meta.intent is sub-workspace with a parent). Side effect: provisions the workspace plus its owner person, membership, default connectors, Stripe customer, and welcome email. name is required unless candidate_id is supplied, in which case identity is derived from the detected candidate.

Requires a bearer token: Authorization: Bearer <token>.

Request

cURL
curl -X POST https://api.wellapp.ai/v1/workspaces \
  -H "Authorization: Bearer $WELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "type": "workspace",
    "attributes": {
      "name": "Foldspace AI",
      "description": "Production finance workspace for the Foldspace team.",
      "auto_extract_enabled": true
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "people",
          "id": "c4d5e6f7-8a9b-40c1-92d3-e4f5a6b7c8d9",
          "firebase_id": "uid_remy_okafor_01",
          "first_name": "Remy",
          "last_name": "Okafor",
          "email": "remy@foldspace.ai",
          "linkedin_url": "https://www.linkedin.com/in/remy-okafor"
        }
      }
    }
  }
}'
Request body
{
  "data": {
    "type": "workspace",
    "attributes": {
      "name": "Foldspace AI",
      "description": "Production finance workspace for the Foldspace team.",
      "auto_extract_enabled": true
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "people",
          "id": "c4d5e6f7-8a9b-40c1-92d3-e4f5a6b7c8d9",
          "firebase_id": "uid_remy_okafor_01",
          "first_name": "Remy",
          "last_name": "Okafor",
          "email": "remy@foldspace.ai",
          "linkedin_url": "https://www.linkedin.com/in/remy-okafor"
        }
      }
    }
  }
}

Responses

201 — The created workspace.

{
  "data": {
    "type": "workspace",
    "id": "8f6b2c10-4a1e-4d2b-9c3a-1f0e7a5b6c21",
    "attributes": {
      "name": "Foldspace AI",
      "description": "Production finance workspace for the Foldspace team.",
      "avatar_image": null,
      "avatar_color": "#5B8DEF",
      "external_workspace_id": null,
      "trusted": false,
      "auto_extract_enabled": true,
      "stage": "active",
      "timezone": "America/Los_Angeles",
      "parent_workspace_id": null,
      "created_at": "2026-01-12T09:29:00.000Z",
      "updated_at": "2026-05-21T07:45:00.000Z"
    },
    "relationships": {
      "media": {
        "data": {
          "type": "media",
          "id": "00000000-0000-4000-8000-000000000001"
        }
      },
      "parent_workspace": {
        "data": {
          "type": "workspace",
          "id": "00000000-0000-4000-8000-000000000001"
        }
      },
      "own_company": {
        "data": {
          "type": "company",
          "id": "00000000-0000-4000-8000-000000000001"
        }
      },
      "child_workspaces": {
        "data": [
          {
            "type": "workspace",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        ]
      },
      "memberships": {
        "data": [
          {
            "type": "membership",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        ]
      },
      "webhooks": {
        "data": [
          {
            "type": "webhook",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        ]
      },
      "workspace_accounting_settings": {
        "data": {
          "type": "workspace_accounting_settings",
          "id": "00000000-0000-4000-8000-000000000001"
        }
      },
      "workspace_providers": {
        "data": [
          {
            "type": "workspace_provider",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        ]
      }
    }
  }
}

400 — Bad Request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

403 — Forbidden

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}