---
title: "Create a workspace"
method: POST
path: "/v1/workspaces"
tags: ["Account"]
---

# Create a workspace

`POST /v1/workspaces`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/workspaces`
- Auth: none required

Returns the first API key once. When email verification is on, signup credits are added after the email link is opened. attribution is optional. When it is omitted, the rmcp_attr cookie from the first visit is stored instead. marketing_opt_in is optional and defaults to false.

No authentication.

## Request body

- object
  - `name` string, required
  - `email` string, required: Owner email. Required: the confirmation link goes there, and the free credits are added once it is opened. A missing or malformed address is 400 invalid_request with details.field email.
  - `first_name` string, nullable: Owner first name. Optional. Not taken from the workspace name.
  - `marketing_opt_in` boolean: Optional. Leave false, or omit it, until the person ticks the product-updates checkbox.
  - `attribution` object
    - `utm_source` string, nullable: utm_source from the first visit.
    - `utm_medium` string, nullable
    - `utm_campaign` string, nullable
    - `utm_content` string, nullable
    - `utm_term` string, nullable
    - `referrer` string, nullable: https referrer without a query string.
    - `landing_path` string, nullable: Path of the first page. Starts with /.

## Response `201`

Created.

- WorkspaceCreated
  - `id` string, required
  - `name` string
  - `api_key` string, required: Shown once. Store it.
  - `balance_credits` integer
  - `scopes` string[]
  - `email_verification` 'not_required' | 'sent'
  - `signup_credits_pending` integer
  - `signup_credits_pending_reason` 'email_already_claimed' | 'normalized_email_used', nullable: Why the free grant is 0. Null when it is still pending or already on the balance. email_already_claimed is the same address. normalized_email_used is a plus-tag or dotted Gmail form of an address that already received it.

## Other responses

- `400`: `invalid_request` (do not retry): email is required. Free credits are added after you confirm it. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `429`: `rate_limited` (retry): Too many requests from this network. Try again later.

## Changes

- **2026-10-20** `ad27b35513a6`: 2 warning
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/workspaces/post.md)

---

[API](https://skmtc.dev/recruitmcp/apis/recruitmcp-api.md) · [All operations](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/revisions/ad27b35513a6?raw)