> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luminpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Space
> Create a new Space within the authorized Workspace.
This endpoint requires the following scope:
`workspaces`
## OpenAPI
````yaml POST /workspaces/spaces
openapi: 3.1.0
info:
version: 1.0.0
title: Lumin API Reference
description: >
The Lumin API Reference provides a comprehensive set of tools to integrate
document workflows — including editing, eSignatures, and automation — into
your applications.
Useful links:
- [Document Repository](https://github.com/luminpdf/luminsign-docs)
- [API
Definition](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
- [Authentication Guide](/tabs/guides/authentication/overview)
termsOfService: https://www.luminpdf.com/terms-of-use/
contact:
name: API Support
email: integration@luminpdf.com
url: https://help.luminpdf.com
servers:
- url: https://api.luminpdf.com/v1
description: Production server
security: []
tags:
- name: Signature Requests
description: Everything about Signature Requests
- name: Users
description: Everything about Users
- name: Templates
description: Everything about Templates
- name: Documents
description: Everything about Documents
- name: Workspaces
description: Everything about Workspaces
- name: Agreements
description: Everything about Agreements
paths:
/workspaces/spaces:
post:
tags:
- Workspaces
summary: Create Space
description: >
Create a new Space within the authorized Workspace.
**Partial success (member invites):** The Space is created when
Space-level checks pass.
- Each object in `members` is evaluated independently.
- Entries that cannot be invited (for example, the user is not an active
Workspace member or the account is ineligible) are **skipped** rather
than failing the whole request.
- If any entry was skipped, an optional aggregate `member_invite_notice`
is included in the response.
**Member payload:**
- Invitees are identified by `user_id` only (plus `role`).
- Valid `user_id` values are the same users returned by [Get Workspace
Members](/tabs/api-reference/api/workspaces/get-workspace-members) for
this Workspace.
- Any other unknown property on a `members[]` object is silently
ignored.
**Space creation cap:** A Workspace's overall Space allowance is 2 on
Free plans and up to 200 on paid plans.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SpaceCreateRequest'
example:
name: Sales Team
members:
- user_id: 5eafc19053615900182f85c6
role: member
responses:
'200':
description: Returns the newly created Space.
content:
application/json:
schema:
$ref: '#/components/schemas/SpaceCreateResponse'
example:
space:
id: 69d74983d0cbaa0977be7997
name: Sales Team
created_at: '2026-04-09T06:38:59.381Z'
workspace_id: 60ab55f099ce3f001250857b
role_of_user: admin
total_members: 2
owner:
user_id: 655f01fadb5d4b9916422581
name: Jane Smith
email: jane@example.com
member_invite_notice: >-
Some members couldn't be added as they're not in this
Workspace or aren't eligible.
4XX:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
- BearerAuth:
- workspaces
components:
schemas:
SpaceCreateRequest:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 100
description: The name of the Space to create.
members:
type: array
description: >
Initial members to invite into the Space. If omitted, the Space is
created with only the requesting user as owner. Ineligible entries
are skipped; see `member_invite_notice` on the response.
items:
$ref: '#/components/schemas/SpaceMemberInvite'
SpaceCreateResponse:
type: object
required:
- space
properties:
space:
$ref: '#/components/schemas/SpaceDetail'
Error:
type: object
required:
- error_code
- error_message
properties:
error_code:
type: string
description: The system error code.
error_message:
type: string
description: The human-readable error message.
SpaceMemberInvite:
type: object
required:
- user_id
- role
properties:
user_id:
type: string
description: >
Lumin user ID of the member to invite. Must correspond to a user
returned by [Get Workspace
Members](/tabs/api-reference/api/workspaces/get-workspace-members)
for this Workspace. If the user is not an active Workspace member or
fails other invite checks, this entry is skipped; the Space is still
created and an aggregate `member_invite_notice` may be returned.
role:
type: string
description: Role assigned to this member in the new Space.
enum:
- admin
- member
SpaceDetail:
type: object
properties:
id:
type: string
description: The unique identifier of the newly created Space.
name:
type: string
description: The name of the Space.
created_at:
type: string
format: date-time
description: The timestamp when the Space was created (ISO 8601).
workspace_id:
type: string
description: The ID of the parent Workspace this Space belongs to.
role_of_user:
type: string
description: >-
The role of the requesting user in the newly created Space
(typically `admin`).
enum:
- admin
- member
total_members:
type: integer
description: >
Total members in the Space after this request (owner plus every
`members` entry that was successfully invited). Skipped invitees are
not counted.
owner:
$ref: '#/components/schemas/SpaceOwner'
member_invite_notice:
type: string
description: >
Optional. Omitted when every requested `members` entry was
successfully invited. When present, at least one invitee was skipped
(the Space was still created).
SpaceOwner:
type: object
properties:
user_id:
type: string
description: The unique identifier of the Space owner.
name:
type: string
description: The name of the Space owner.
email:
type: string
description: The email address of the Space owner.
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-API-Key
description: >
Provide your API key in the `X-API-Key` header, e.g., `X-API-Key:
YOUR_API_KEY`.
BearerAuth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://auth.luminpdf.com/oauth2/auth
tokenUrl: https://auth.luminpdf.com/oauth2/token
scopes:
openid: >-
Retrieve basic identity details (username, email, profile
picture).
offline_access: Request a refresh token for long-lived access. Private apps only.
profile.read: View basic user profile information.
workspaces: View and manage Workspaces and Spaces.
workspaces.read: View information about the authenticated user's Workspace.
templates: View and manage templates in a Workspace.
pdf:files: Create, edit, and delete PDF files in a Workspace.
pdf:files.read: Retrieve PDF documents stored in a Workspace.
sign:requests: Create, update, or view signature requests.
sign:requests.read: Retrieve signature requests.
agreements: Create, update, or delete AgreementGen documents.
description: >
OAuth 2.0 authorization code flow. Provide your access token in the
`Authorization` header, e.g., `Authorization: Bearer `. See the
[OAuth 2.0 guide](/tabs/guides/authentication/oauth2) for details.
````