PowerShell API Documentation

Explore the available API endpoints for PowerShell management.

Introduction

This document outlines the RESTful API endpoints available for interacting with and managing PowerShell environments. You can use these endpoints to automate tasks, retrieve information, and control PowerShell sessions programmatically.

All API requests should include the Authorization header with a valid token. Responses are typically in JSON format.

Authentication

Authentication is handled via OAuth 2.0. Obtain a token by following the standard OAuth 2.0 flow for your application.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

The obtained token should be included in the Authorization header of subsequent requests:

Authorization: Bearer YOUR_ACCESS_TOKEN

API Endpoints

GET /powershell/docs/api/version

Retrieves the current version of the PowerShell API.

Response:
{
  "version": "1.0.0",
  "apiName": "PowerShell Management API"
}

GET /powershell/docs/api/sessions

Lists all active PowerShell sessions.

Query Parameters:
  • status (optional): Filter sessions by status (e.g., "running", "stopped").
  • limit (optional): Maximum number of sessions to return.
Response:
[
  {
    "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "status": "running",
    "startTime": "2023-10-27T10:00:00Z",
    "scriptName": "default.ps1"
  },
  {
    "sessionId": "f0e9d8c7-b6a5-4321-0987-fedcba098765",
    "status": "running",
    "startTime": "2023-10-27T11:00:00Z",
    "scriptName": "monitor.ps1"
  }
]

POST /powershell/docs/api/sessions

Starts a new PowerShell session.

Request Body:
{
  "scriptPath": "/path/to/your/script.ps1",
  "parameters": {
    "param1": "value1",
    "param2": 123
  },
  "environmentVariables": {
    "MY_VAR": "my_value"
  }
}
Response:
{
  "sessionId": "new-session-id-12345",
  "status": "starting",
  "message": "Session initiation requested successfully."
}

GET /powershell/docs/api/sessions/{sessionId}

Retrieves details for a specific PowerShell session.

Path Parameters:
  • sessionId (required): The ID of the session to retrieve.
Response:
{
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "running",
  "startTime": "2023-10-27T10:00:00Z",
  "endTime": null,
  "scriptName": "default.ps1",
  "logs": [
    {"timestamp": "2023-10-27T10:05:15Z", "level": "INFO", "message": "Processing data..."},
    {"timestamp": "2023-10-27T10:06:01Z", "level": "WARN", "message": "Configuration not found."}
  ]
}

DELETE /powershell/docs/api/sessions/{sessionId}

Stops a running PowerShell session.

Path Parameters:
  • sessionId (required): The ID of the session to stop.
Response:
{
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "stopping",
  "message": "Session stop request processed."
}

GET /powershell/docs/api/sessions/{sessionId}/logs

Retrieves the logs for a specific PowerShell session.

Path Parameters:
  • sessionId (required): The ID of the session whose logs are requested.
Query Parameters:
  • since (optional): Filter logs by timestamp (e.g., "2023-10-27T10:30:00Z").
  • level (optional): Filter logs by severity level (e.g., "INFO", "WARN", "ERROR").
Response:
[
  {"timestamp": "2023-10-27T10:35:00Z", "level": "INFO", "message": "Task completed."},
  {"timestamp": "2023-10-27T10:35:05Z", "level": "ERROR", "message": "Failed to connect to service."}
]