> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create workspace

> Create a new workspace to organize computers.

Creates a workspace and returns it with `201`. The calling account becomes the owner.

<Info>
  Workspaces are containers for computers. Use them to separate projects, environments, or teams.
</Info>

Creating a workspace needs an account-wide API key. A workspace-scoped key gets `403`. See [Authentication](/api-reference/authentication).

## Request

<ParamField body="name" type="string" required>
  Workspace name. Leading and trailing whitespace is trimmed. The name must not match one you already own, compared case-insensitively. Names of workspaces shared with you do not conflict. Missing, non-string, or whitespace-only values are rejected with `400`.
</ParamField>

<ParamField body="icon_url" type="string">
  Optional URL of an icon for the workspace. Stored as given and not validated. Omit it and the workspace is created with `icon_url: null`.
</ParamField>

<ParamField body="status" type="string" default="active">
  Optional. Defaults to `active` when omitted. The product understands `active` and `inactive`. The field is stored as given and is not validated against that list.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Workspace identifier. Use it as `workspace_id` when creating computers.
</ResponseField>

<ResponseField name="name" type="string">
  Workspace name, trimmed.
</ResponseField>

<ResponseField name="user_id" type="string">
  User ID of the owner, which is your account.
</ResponseField>

<ResponseField name="status" type="string">
  Workspace status.
</ResponseField>

<ResponseField name="icon_url" type="string">
  Icon URL, or `null` when none was sent.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

The create response does not include `updated_at`, `owner_tier`, `owner_email`, or `desktops`. [Get workspace](/api-reference/workspaces/get) returns those.

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/workspaces \
    -H "Authorization: Bearer $ORGO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "production"}'
  ```

  ```python Python theme={null}
  import os
  import requests

  api_key = os.environ["ORGO_API_KEY"]

  response = requests.post(
      "https://www.orgo.ai/api/workspaces",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={"name": "production"}
  )

  workspace = response.json()
  print(f"Created: {workspace['id']}")
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ORGO_API_KEY;

  const response = await fetch('https://www.orgo.ai/api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'production' })
  });

  const workspace = await response.json();
  console.log(`Created: ${workspace.id}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "production",
  "user_id": "4d96f9a0-7727-4b63-889a-32544c206d7c",
  "status": "active",
  "icon_url": null,
  "created_at": "2026-04-07T10:30:00Z"
}
```

## Errors

| Status | Body | Meaning |
| - | - | - |
| `400` | `{ "error": "Invalid request body" }` | The body was not valid JSON. |
| `400` | `{ "error": "Project name is required" }` | `name` was missing, not a string, or whitespace only. |
| `400` | `{ "error": "A project with this name already exists" }` | You already own a workspace with that name, compared case-insensitively. |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `403` | `{ "error": "Workspace-scoped keys cannot create workspaces (workspace_scope_mismatch)." }` | The API key is scoped to a workspace. Use an account-wide key. |
| `403` | `{ "error": "Sign up to create your own workspace.", "code": "GUEST_RESTRICTED" }` | The caller joined through a share link. Guests can work in the workspace they were invited to but cannot create their own. |
| `500` | `{ "error": "Could not verify account", "code": "AUTH_LOOKUP_FAILED" }` | The account lookup that gates guests failed. Retry. |
| `500` | `{ "error": "<message>" }` | Unexpected server error. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |

Some error bodies on this endpoint carry a `code` alongside `error`. Branch on `code` where it is present. It is stable, and the `error` string is not.


## OpenAPI

````yaml POST /workspaces
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Clients
    description: >-
      Run Orgo for your clients from your own app: a workspace and scoped key
      each, billed to you or to them.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /workspaces:
    post:
      tags:
        - Workspaces
      summary: Create workspace
      description: >-
        Creates a workspace and returns it with `201`. The calling account
        becomes the owner. Names must not match one you already own, compared
        case-insensitively. Needs an account-wide key.
      operationId: createWorkspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Workspace name. Must be unique within your account.
                  minLength: 1
                  example: my-workspace
                icon_url:
                  type: string
                  description: Optional icon URL
                status:
                  type: string
                  default: active
                  description: >-
                    Defaults to `active`. Stored as given and not validated: the
                    product understands `active` and `inactive`.
      responses:
        '201':
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                name: my-workspace
                user_id: 4d96f9a0-7727-4b63-889a-32544c206d7c
                status: active
                icon_url: null
                created_at: '2026-04-07T10:30:00Z'
        '400':
          description: >-
            The body is not valid JSON, `name` is missing or blank, or you
            already own a workspace with that name.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                bad-body:
                  summary: Not JSON
                  value:
                    error: Invalid request body
                no-name:
                  summary: No name
                  value:
                    error: Project name is required
                duplicate:
                  summary: Name taken
                  value:
                    error: A project with this name already exists
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            The API key is scoped to a workspace, or you joined through a share
            link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                scoped-key:
                  summary: Workspace-scoped key
                  value:
                    error: >-
                      Workspace-scoped keys cannot create workspaces
                      (workspace_scope_mismatch).
                guest:
                  summary: Share-link guest
                  value:
                    error: Sign up to create your own workspace.
                    code: GUEST_RESTRICTED
        '500':
          description: >-
            The account lookup that gates guests failed, or an unexpected server
            error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth-lookup:
                  summary: Account lookup failed. Retry.
                  value:
                    error: Could not verify account
                    code: AUTH_LOOKUP_FAILED
                other:
                  summary: Unexpected
                  value:
                    error: …
        '503':
          $ref: '#/components/responses/AuthUnavailable'
components:
  schemas:
    Workspace:
      type: object
      properties:
        id:
          type: string
          description: Unique workspace identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          description: Workspace name
          example: production
        user_id:
          type: string
          description: Owner user ID
        status:
          type: string
          enum:
            - active
            - inactive
          example: active
        icon_url:
          type:
            - string
            - 'null'
          description: Icon URL for the workspace, or `null` when none is set.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      description: >-
        The base error body. Every failure carries `error`; individual endpoints
        add the fields named in the schemas below.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message.
          example: Access denied
        code:
          type: string
          description: >-
            Machine-readable reason. Present on the failures that define one,
            absent otherwise.
  responses:
    Unauthorized:
      description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalid-key:
              summary: The key is not one of yours
              value:
                error: Invalid API key
            no-credential:
              summary: No key and no session
              value:
                error: Authentication required
    AuthUnavailable:
      description: >-
        Orgo could not verify the credential because of a server-side fault,
        such as a database outage. Retry after `Retry-After`. Do not rotate the
        key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: >-
              Service temporarily unavailable. The database is not accepting
              requests. Retry shortly.
      headers:
        Retry-After:
          description: Seconds to wait before retrying. Always `5`.
          schema:
            type: string
            example: '5'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.