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

# Create Session

Create a new workflow session. A new session starts with `status: "open"` and is immediately
writable — see [Session Lifecycle](/blob-types/workflow/workflows/session-lifecycle) for the
statuses it can move through afterwards.

## **POST** `/revisions/:id/data/command` (Command: `create_session`)

### Request Body

| Parameter     | Type   | Required | Description                                                                                                       |
| :------------ | :----- | :------- | :---------------------------------------------------------------------------------------------------------------- |
| `engine`      | string | Yes      | Must be `workflow_blobhub`.                                                                                       |
| `command`     | string | Yes      | Must be `create_session`.                                                                                         |
| `alias`       | string | No       | Optional stable name for the session. 6–42 chars, lowercase (`a`–`z`, `0`–`9`, `_`, `-`), unique in the revision. |
| `description` | string | No       | Optional description.                                                                                             |
| `tracing`     | object | No       | Tracing configuration (e.g., `{"log_data": true}`).                                                               |

See [Alias Grammar](/blob-types/scheduler/overview#alias-grammar) for the character rules, length
limits and which commands accept an alias in place of an id.

### Response

| Parameter | Type   | Description                 |
| :-------- | :----- | :-------------------------- |
| `session` | object | The created session object. |

### Errors

| Status | Error          | Cause                                        |
| :----- | :------------- | :------------------------------------------- |
| 400    | `alias_in_use` | The alias is already taken in this revision. |

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "create_session",
    "alias": "primary",
    "description": "Production Run 1",
    "tracing": { "log_data": true }
  }
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "session": {
      "id": "sess_001",
      "alias": "primary",
      "status": "open"
    }
  }
  ```
</CodeGroup>