--- title: "Create a space" method: POST path: "/spaces" tags: ["spaces"] --- # Create a space `POST /spaces` Creates a new space based on an existing Space Config ## Headers - `Authorization` string, required - `X-Disable-Hooks` 'true', required ## Request body - TypeSpacesSpaceConfig — Properties used to create a new Space - `spaceConfigId` string — Space Config ID - `environmentId` string — Environment ID - `primaryWorkbookId` string — Workbook ID - `metadata` unknown - `settings` TypeSpacesSpaceSettings — Settings for a space - `sidebarConfig` TypeSpacesSpaceSidebarConfig - `workbookSidebarOrder` TypeCommonsWorkbookId[] — Used to set the order of workbooks in the sidebar. This will not affect workbooks that are pinned and workbooks that are not specified here will be sorted alphabetically. - `filesMappedAfterJob` string — The name of the job that needs to complete before navigating to file mapping - `extractionOptions` TypeFilesHeaderDetectionOptions - `algorithm` 'aiDetection' | 'default' | 'explicitHeaders' | 'specificRows' | 'dataRowAndSubHeaderDetection', required - `rowsToSearch` integer - `skip` integer - `headers` string[] - `rowNumbers` integer[] - `omitActions` string[] — List of action names to omit from the space interface (e.g., 'file.import', 'records.delete', 'records.download') - `omitRowSelectionToolbar` boolean — Whether to hide the floating toolbar at the bottom that appears when rows are selected - `actions` TypeCommonsAction[] - `slug` string — **This is deprecated. Use `operation` instead.** - `operation` string — This will become the job operation that is triggered - `mode` 'foreground' | 'background' | 'toolbarBlocking' — Foreground actions will prevent interacting with the resource until complete - `tooltip` string — A tooltip that appears when hovering the action button - `messages` TypeCommonsActionMessage[] - `type` 'error' | 'info', required - `content` string, required - `type` string — **This is deprecated.** - `description` string — The text that appears in the dialog after the action is clicked. - `schedule` 'weekly' | 'daily' | 'hourly' - `primary` boolean — A primary action will be more visibly present, whether in Sheet or Workbook. - `confirm` boolean — Whether to show a modal to confirm the action - `icon` string — Icon will work on primary actions. It will only accept an already existing Flatfile design system icon. - `requireAllValid` boolean — **This is deprecated. Use `constraints` instead.** - `requireSelection` boolean — **This is deprecated. Use `constraints` instead.** - `inputForm` TypeCommonsInputForm - `type` 'simple', required - `fields` TypeCommonsInputField[], required - `key` string, required — Unique key for a Field. - `label` string, required — Visible name of a Field. - `description` string — Brief description below the name of the Field. - `type` string, required — Field Types inform the user interface how to sort and display data. - `defaultValue` unknown - `config` TypeCommonsInputConfig - `options` TypeCommonsInputEnumPropertyOption[], required - `label` string — A visual label for this option, defaults to value if not provided - `description` string — A short description for this option - `color` string — An optional color to assign this option - `icon` string — A reference pointer to a previously registered icon - `meta` object — An arbitrary JSON object to be associated with this option and made available to hooks - `value` unknown, required - `constraints` TypeCommonsInputConstraint[] — Indicate additional validations that will be applied to the Field. - `type` 'required', required - `constraints` TypeCommonsActionConstraint[] — A limitation or restriction on the action. - union - object - `type` 'hasAllValid', required — Discriminator value: hasAllValid - `ignoreSelection` boolean - object - `type` 'hasSelection', required — Discriminator value: hasSelection - object - `type` 'hasData', required — Discriminator value: hasData - object - `type` 'hasColumnEnabled', required — Discriminator value: hasColumnEnabled - `mount` union - object - `type` 'sheet', required — Discriminator value: sheet - `slugs` string[] - object - `type` 'workbook', required — Discriminator value: workbook - `slugs` string[] - object - `type` 'field', required — Discriminator value: field - `keys` string[] - object - `type` 'document', required — Discriminator value: document - object - `type` 'file', required — Discriminator value: file - `guide` TypeCommonsGuide - `content` string, required — Markdown guidance for this action - `guardrail` TypeCommonsGuardrail - `content` string, required — Markdown guardrail for this action - `createdFrom` string — Action ID - `lastPropagatedAt` string, date-time — The last time this action was propagated to a workbook - `deletedAt` string, date-time — The time this action was deleted - `invalidConditionalMessaging` boolean — When enabled, shows dynamic confirmation messages based on record validation status instead of the static description - `validRecordsMessage` string — Custom message to show when all records are valid (only used when invalidConditionalMessaging is true) - `invalidRecordsMessage` string — Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true) - `label` string, required — The text on the Button itself - `access` TypeSpacesSpaceAccess[] - `autoConfigure` boolean — Only used during creation - will be ignored on update - `namespace` string - `labels` string[] - `translationsPath` string - `languageOverride` string - `archivedAt` string, date-time — Date when space was archived - `appId` string — App ID - `isAppTemplate` boolean — Whether the space is an app template. Only one space per app can be an app template. - `name` string — The name of the space - `displayOrder` integer — The display order - `guestAuthentication` TypeEnvironmentsGuestAuthenticationEnum[] ## Response `200` Response with status 200 - TypeSpacesSpaceResponse - `data` TypeSpacesSpace, required — A place to store your workbooks - `spaceConfigId` string — Space Config ID - `environmentId` string — Environment ID - `primaryWorkbookId` string — Workbook ID - `metadata` unknown - `settings` TypeSpacesSpaceSettings — Settings for a space - `sidebarConfig` TypeSpacesSpaceSidebarConfig - `workbookSidebarOrder` TypeCommonsWorkbookId[] — Used to set the order of workbooks in the sidebar. This will not affect workbooks that are pinned and workbooks that are not specified here will be sorted alphabetically. - `filesMappedAfterJob` string — The name of the job that needs to complete before navigating to file mapping - `extractionOptions` TypeFilesHeaderDetectionOptions - `algorithm` 'aiDetection' | 'default' | 'explicitHeaders' | 'specificRows' | 'dataRowAndSubHeaderDetection', required - `rowsToSearch` integer - `skip` integer - `headers` string[] - `rowNumbers` integer[] - `omitActions` string[] — List of action names to omit from the space interface (e.g., 'file.import', 'records.delete', 'records.download') - `omitRowSelectionToolbar` boolean — Whether to hide the floating toolbar at the bottom that appears when rows are selected - `actions` TypeCommonsAction[] - `slug` string — **This is deprecated. Use `operation` instead.** - `operation` string — This will become the job operation that is triggered - `mode` 'foreground' | 'background' | 'toolbarBlocking' — Foreground actions will prevent interacting with the resource until complete - `tooltip` string — A tooltip that appears when hovering the action button - `messages` TypeCommonsActionMessage[] - `type` 'error' | 'info', required - `content` string, required - `type` string — **This is deprecated.** - `description` string — The text that appears in the dialog after the action is clicked. - `schedule` 'weekly' | 'daily' | 'hourly' - `primary` boolean — A primary action will be more visibly present, whether in Sheet or Workbook. - `confirm` boolean — Whether to show a modal to confirm the action - `icon` string — Icon will work on primary actions. It will only accept an already existing Flatfile design system icon. - `requireAllValid` boolean — **This is deprecated. Use `constraints` instead.** - `requireSelection` boolean — **This is deprecated. Use `constraints` instead.** - `inputForm` TypeCommonsInputForm - `type` 'simple', required - `fields` TypeCommonsInputField[], required - `key` string, required — Unique key for a Field. - `label` string, required — Visible name of a Field. - `description` string — Brief description below the name of the Field. - `type` string, required — Field Types inform the user interface how to sort and display data. - `defaultValue` unknown - `config` TypeCommonsInputConfig - `options` TypeCommonsInputEnumPropertyOption[], required - … - `constraints` TypeCommonsInputConstraint[] — Indicate additional validations that will be applied to the Field. - `type` 'required', required - `constraints` TypeCommonsActionConstraint[] — A limitation or restriction on the action. - union - object - `type` 'hasAllValid', required — Discriminator value: hasAllValid - `ignoreSelection` boolean - object - `type` 'hasSelection', required — Discriminator value: hasSelection - object - `type` 'hasData', required — Discriminator value: hasData - object - `type` 'hasColumnEnabled', required — Discriminator value: hasColumnEnabled - `mount` union - object - `type` 'sheet', required — Discriminator value: sheet - `slugs` string[] - object - `type` 'workbook', required — Discriminator value: workbook - `slugs` string[] - object - `type` 'field', required — Discriminator value: field - `keys` string[] - object - `type` 'document', required — Discriminator value: document - object - `type` 'file', required — Discriminator value: file - `guide` TypeCommonsGuide - `content` string, required — Markdown guidance for this action - `guardrail` TypeCommonsGuardrail - `content` string, required — Markdown guardrail for this action - `createdFrom` string — Action ID - `lastPropagatedAt` string, date-time — The last time this action was propagated to a workbook - `deletedAt` string, date-time — The time this action was deleted - `invalidConditionalMessaging` boolean — When enabled, shows dynamic confirmation messages based on record validation status instead of the static description - `validRecordsMessage` string — Custom message to show when all records are valid (only used when invalidConditionalMessaging is true) - `invalidRecordsMessage` string — Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true) - `label` string, required — The text on the Button itself - `access` TypeSpacesSpaceAccess[] - `autoConfigure` boolean — Only used during creation - will be ignored on update - `namespace` string - `labels` string[] - `translationsPath` string - `languageOverride` string - `archivedAt` string, date-time — Date when space was archived - `appId` string — App ID - `isAppTemplate` boolean — Whether the space is an app template. Only one space per app can be an app template. - `id` string, required — Space ID - `workbooksCount` integer — Amount of workbooks in the space - `filesCount` integer — Amount of files in the space - `createdByUserId` string — User ID - `createdByUserName` string — User name who created space - `createdAt` string, date-time, required — Date when space was created - `updatedAt` string, date-time, required — Date when space was updated - `expiredAt` string, date-time — Date when space was expired - `lastActivityAt` string, date-time — This date marks the most recent activity within the space, tracking actions to the second. Activities include creating or updating records in a sheet, uploading files, or modifying a workbook's configuration. - `guestLink` string — Guest link to the space - `name` string, required — The name of the space - `displayOrder` integer — The display order - `accessToken` string — Access token for the space - `isCollaborative` boolean — Flag for collaborative (project) spaces - `size` TypeSpacesSpaceSize — The size of a space - `name` string, required - `id` string, required - `numUsers` integer, required - `pdv` integer, required - `numFiles` integer, required - `upgradedAt` string, date-time — Date when the space was upgraded - `guestAuthentication` TypeEnvironmentsGuestAuthenticationEnum[], required — Type of guest authentication - `createdFrom` string — Space ID - `lastPropagatedAt` string, date-time — The last time the space template configuration was propagated to this space ## Other responses - `400` — Error response with status 400 - `404` — Error response with status 404 --- [API](https://skmtc.net/flatfile/apis/api-reference.md) · [All operations](https://skmtc.net/flatfile/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flatfile/api-reference/revisions/9d3a9979cd96/schema)