### Start preview with curl

Source: https://hoplite.sh/docs/api/startPlatformPreview

Example curl command to start or restore a source-backed preview. Requires the X-Api-Key header and an Idempotency-Key for service credentials. The frameOrigin is passed in the JSON body.

```bash
curl --request POST \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/threads/threadId/preview/start \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header "Idempotency-Key: $HOPLITE_OPERATION_ID" \
  --header 'Content-Type: application/json' \
  --data '{
  "frameOrigin": "https://dashboard.example.com"
}'
```

--------------------------------

### List GitHub installations with curl

Source: https://hoplite.sh/docs/api/listGitHubInstallations

Sends a GET request to /api/source-control/github/installations with the X-Api-Key header. Requires the repo:read permission. The response is a GitHubInstallationsResponse JSON object containing the connected installations.

```bash
curl --request GET \
  --url https://api.hoplite.sh/api/source-control/github/installations \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

--------------------------------

### POST /api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

Source: https://hoplite.sh/docs/api/startPlatformPreview

Starts the configured preview for an application thread, restoring an archived source workspace when needed. Requires product access and the dashboard frameOrigin. To replace an existing launch, supply restart.runScriptSha256. A confirmed replacement returns preview.restart with the new launchId, deterministic runId and matching command hash; unconfirmed restarts return 503 preview_unavailable. Session callers also need X-Hoplite-Action: preview-start. The gateway credential expires after five minutes; idempotent replay returns the original credential, so refresh it with GET preview. While the preview boots, relayed requests answer with X-Preview-State: starting (202 for documents, 425 otherwise). This does not publish or validate the application.

```APIDOC
## POST /api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

### Description
Starts the configured preview for an application thread, restoring an archived source workspace when needed. Requires product access and the dashboard frameOrigin. To replace an existing launch, supply restart.runScriptSha256. A confirmed replacement returns preview.restart with the new launchId, deterministic runId and matching command hash; unconfirmed restarts return 503 preview_unavailable. Session callers also need X-Hoplite-Action: preview-start. The gateway credential expires after five minutes; idempotent replay returns the original credential, so refresh it with GET preview. While the preview boots, relayed requests answer with X-Preview-State: starting (202 for documents, 425 otherwise). This does not publish or validate the application.

### Method
POST

### Endpoint
/api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **threadId** (string) - Required - The thread ID.

#### Header Parameters
- **Idempotency-Key** (string) - Optional - Required for service credentials. Retry the same request with the same key.

#### Request Body
- **restart** (object) - Optional - Restart configuration.
- **restart.runScriptSha256** (string) - Required - SHA-256 hash of the run script, pattern ^[a-f0-9]{64}$.
- **frameOrigin** (string<uri>) - Required - The dashboard frame origin, max length 2048.

### Request Example
{
  "frameOrigin": "https://dashboard.example.com"
}

### Response
#### Success Response (200)
- **ok** (boolean) - Required - Always true.
- **preview** (object) - Required - Preview details.
- **preview.status** (string) - Required - Status: ready, unsupported, reconciling, blocked, starting, stopped, crashed, inactive.
- **preview.name** (string) - Optional - Preview name, min length 1.
- **preview.port** (integer) - Optional - Port number, min 1, max 65535.
- **preview.reason** (string) - Optional - Reason for current status.
- **preview.url** (string<uri>) - Optional - Preview URL.
- **preview.restart** (object) - Optional - Restart information.
- **preview.restart.launchId** (string) - Required - Launch ID, min length 1.
- **preview.restart.runId** (string) - Required - Run ID, pattern ^[a-f0-9]{16}$.
- **preview.restart.runScriptSha256** (string) - Required - SHA-256 hash of the run script, pattern ^[a-f0-9]{64}$.
- **preview.gateway** (object) - Required - Gateway credentials.
- **preview.gateway.header** (string) - Required - Header name: x-hoplite-preview-token.
- **preview.gateway.token** (string) - Required - Gateway token.
- **preview.gateway.expiresAt** (string<date-time>) - Required - Expiration timestamp.

#### Response Example
{
  "ok": true,
  "preview": {
    "status": "ready",
    "name": "my-preview",
    "port": 8080,
    "url": "https://preview.example.com",
    "restart": {
      "launchId": "launch-123",
      "runId": "abcdef1234567890",
      "runScriptSha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "gateway": {
      "header": "x-hoplite-preview-token",
      "token": "gateway-token",
      "expiresAt": "2025-01-01T00:00:00Z"
    }
  }
}

### Status Codes
- **200** - Success
- **400** - Invalid request
- **401** - Authentication required
- **403** - Permission, app scope or entitlement denied
- **404** - App, source or thread not found
- **409** - Idempotency conflict or request in progress
- **413** - Request too large
- **503** - Source storage or execution unavailable
```

--------------------------------

### GET /api/source-control/github/installations

Source: https://hoplite.sh/docs/api/listGitHubInstallations

Lists GitHub App installations connected to the API key's organization. Requires the 'repo:read' permission.

```APIDOC
## GET /api/source-control/github/installations

### Description
Lists GitHub App installations connected to the API key's organization.

### Method
GET

### Endpoint
/api/source-control/github/installations

### Parameters
#### Path Parameters
None.

#### Query Parameters
None.

#### Request Body
None.

### Request Example
bash
curl --request GET \
  --url https://api.hoplite.sh/api/source-control/github/installations \
  --header "X-Api-Key: $HOPLITE_API_KEY"


### Response
#### Success Response (200)
- **ok** (boolean) - Required - Always true.
- **installations** (GitHubInstallation[]) - Required - List of installations.
- **installations.id** (string) - Required - Installation ID.
- **installations.installationId** (integer) - Required - GitHub installation ID.
- **installations.apiBaseUrl** (string) - Optional - API base URL.
- **installations.accountLogin** (string) - Required - Account login.
- **installations.accountType** (string) - Required - Account type (e.g., Organization).
- **installations.managementUrl** (string<uri>) - Optional - Management URL.
- **installations.repositories** (GitHubRepository[]) - Required - List of repositories.
- **installations.repositories.id** (string) - Required - Repository ID.
- **installations.repositories.installationId** (string) - Required - Installation ID.
- **installations.repositories.repositoryId** (integer) - Required - GitHub repository ID.
- **installations.repositories.fullName** (string) - Required - Full repository name.
- **installations.repositories.apiBaseUrl** (string) - Optional - API base URL.
- **installations.repositories.cloneUrl** (string | null) - Optional - Clone URL.
- **installations.repositories.language** (string | null) - Optional - Language.
- **installations.repositories.framework** (string | null) - Optional - Framework.
- **installations.repositories.defaultBranch** (string) - Required - Default branch.
- **installations.repositories.private** (boolean) - Required - Whether the repository is private.

#### Response Example

{
  "ok": true,
  "installations": [
    {
      "id": "gh_inst_12345678",
      "installationId": 12345678,
      "accountLogin": "acme",
      "accountType": "Organization",
      "repositories": []
    }
  ]
}


### Response Headers
- **RateLimit** (string) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Current ingress policy, remaining requests, and seconds until reset.
- **RateLimit-Policy** (string) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Ingress quota and window.
- **X-RateLimit-Limit** (integer) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Maximum requests allowed in the current rolling window.
- **X-RateLimit-Remaining** (integer) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Requests remaining in the current rolling window.
- **X-RateLimit-Reset** (integer) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Unix timestamp when the current rolling window resets.
- **x-request-id** (string) - Statuses: 200, 401, 402, 403, 429, 500, 501, 503 - Request correlation ID.
- **Retry-After** (integer) - Statuses: 429, 503 - Seconds until another request should be attempted.
- **X-Retry-After** (integer) - Statuses: 429, 503 - Legacy retry delay in seconds.

### Status Codes
- **200** - Connected installations.
- **401** - The API key is missing, invalid, or lacks the operation's permission.
- **402** - The organization does not have access to the requested product capability.
- **403** - The key's current user no longer has the required organization membership or role.
- **429** - The API-key rate limit has been exceeded.
- **500** - The API encountered an unexpected failure.
- **501** - The deployment has not configured the requested capability.
- **503** - A required API dependency, including the rate limiter, is unavailable.
```

--------------------------------

### Example request (curl)

Source: https://hoplite.sh/docs/api/restoreCheckpoint

Example curl command to restore a checkpoint. Requires the HOPLITE_API_KEY and HOPLITE_OPERATION_ID environment variables.

```bash
curl --request POST \
  --url https://api.hoplite.sh/api/threads/id/checkpoints/checkpointId/restore \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header "Idempotency-Key: $HOPLITE_OPERATION_ID" \
  --header 'Content-Type: application/json' \
  --data '{}'
```

--------------------------------

### curl request example

Source: https://hoplite.sh/docs/api/appendPlatformMessage

Example curl command to POST a message to a thread. Requires the HOPLITE_API_KEY and an optional Idempotency-Key header for service credentials.

```bash
curl --request POST \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/threads/threadId/messages \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header "Idempotency-Key: $HOPLITE_OPERATION_ID" \
  --header 'Content-Type: application/json' \
  --data '{
  "content": "Add a contact page"
}'
```

--------------------------------

### GET /api/threads/{id}/run-state

Source: https://hoplite.sh/docs/api/getThreadRunState

Documentation for the GET /api/threads/{id}/run-state endpoint, including parameters, request example, and response schema.

```APIDOC
## GET /api/threads/{id}/run-state

### Description
Reads the authoritative run state for a specific thread run. Requires the `thread:read` permission.

### Method
GET

### Endpoint
/api/threads/{id}/run-state

### Parameters
#### Path Parameters
- **id** (string) - Required - The thread ID.

#### Query Parameters
- **runId** (string) - Optional - The run ID to filter the state.

### Request Example
```bash
curl --request GET \
  --url https://api.hoplite.sh/api/threads/id/run-state \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

### Response
#### Success Response (200)
Content type: `application/json`. Response type: `object`.

- **ok** (boolean) - Required - Always `true`.
- **run** (object) - Required - The run state object.
  - **runId** (string) - Required - The run ID.
  - **status** (string) - Required - One of: `queued`, `running`, `waiting`, `completed`, `failed`, `cancelled`.
  - **finishedAt** (string | null) - Required - Timestamp when the run finished, or `null`.
  - **assistantMessage** (object | null) - Required - The assistant message, or `null`.
    - **id** (string) - Required - Message ID.
    - **threadId** (string) - Required - Thread ID.
    - **runId** (string) - Optional - Run ID.
    - **queuedAfterRunId** (string) - Optional - ID of the run this message was queued after.
    - **authorUserId** (string) - Optional - Author user ID.
    - **author** (object | null) - Optional - Author object or `null`.
      - **id** (string) - Required - Author ID.
      - **name** (string) - Required - Author name.
      - **image** (string | null) - Optional - Author image URL or `null`.
      - **[key]** (object) - Optional - Additional author properties.
    - **role** (string) - Required - One of: `user`, `assistant`, `system`, `tool`.
    - **content** (string) - Required - Message content.
    - **createdAt** (string) - Required - Creation timestamp.
    - **kind** (string) - Optional - One of: `chat`, `thinking`, `tool`, `status`.
    - **toolCallId** (string) - Optional - Tool call ID.
    - **toolName** (string) - Optional - Tool name.
    - **checkpointId** (string) - Optional - Checkpoint ID.
    - **metadata** (object) - Optional - Metadata object.
      - **[key]** (object) - Optional - Metadata key-value pairs. Values can be string, number, boolean, null, array, or object.
  - **userMessage** (object | null) - Required - The user message, or `null`.
    - **id** (string) - Required - Message ID.
    - **threadId** (string) - Required - Thread ID.
    - **runId** (string) - Optional - Run ID.
    - **queuedAfterRunId** (string) - Optional - ID of the run this message was queued after.
    - **authorUserId** (string) - Optional - Author user ID.
    - **author** (object | null) - Optional - Author object or `null`.
      - **id** (string) - Required - Author ID.
      - **name** (string) - Required - Author name.
      - **image** (string | null) - Optional - Author image URL or `null`.
      - **[key]** (object) - Optional - Additional author properties.
    - **role** (string) - Required - One of: `user`, `assistant`, `system`, `tool`.
    - **content** (string) - Required - Message content.
    - **createdAt** (string) - Required - Creation timestamp.
    - **kind** (string) - Optional - One of: `chat`, `thinking`, `tool`, `status`.

#### Response Example
```json
{
  "ok": true,
  "run": {
    "runId": "string",
    "status": "queued",
    "finishedAt": null,
    "assistantMessage": null,
    "userMessage": null
  }
}
```
```

--------------------------------

### Start preview with curl

Source: https://hoplite.sh/docs/api/startThreadPreview

Sends a POST request to start a managed preview. Requires the thread:update permission and an API key. The Idempotency-Key header is required for writes authenticated by a service credential.

```bash
curl --request POST \
  --url https://api.hoplite.sh/api/threads/id/preview/start \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header "Idempotency-Key: $HOPLITE_OPERATION_ID"
```

--------------------------------

### POST /preview/start

Source: https://hoplite.sh/docs/api/startThreadPreview

Starts a new thread preview with the provided configuration. The request body includes optional preview port settings, verification verdict, and restart parameters.

```APIDOC
## [POST] /preview/start

### Description
Starts a new thread preview with the provided configuration. The request body includes optional preview port settings, verification verdict, and restart parameters.

### Method
POST

### Endpoint
/preview/start

### Parameters
#### Request Body
- **preview.ports.verification.error.Option 2** (string) - Optional - Description not provided.
- **preview.ports.verification.verdict** (object) - Required - Verification verdict object.
- **preview.ports.verification.verdict.status** (string) - Required - Status of the verdict. Allowed values: ready, degraded, broken.
- **preview.ports.verification.verdict.reason** (string) - Required - Reason for the verdict.
- **preview.restart** (object) - Optional - Restart configuration.
- **preview.restart.launchId** (string) - Required - Launch ID, min length 1.
- **preview.restart.runId** (string) - Required - Run ID, pattern ^[a-f0-9]{16}$.
- **preview.restart.runScriptSha256** (string) - Required - SHA256 hash of the run script, pattern ^[a-f0-9]{64}$.

### Response
#### Success Response (200)
- **RateLimit** (string) - Current ingress policy, remaining requests, and seconds until reset.
- **RateLimit-Policy** (string) - Ingress quota and window.
- **X-RateLimit-Limit** (integer) - Maximum requests allowed in the current rolling window.
- **X-RateLimit-Remaining** (integer) - Requests remaining in the current rolling window.
- **X-RateLimit-Reset** (integer) - Unix timestamp when the current rolling window resets.
- **x-request-id** (string) - Request correlation ID.
- **Retry-After** (integer) - Seconds until another request should be attempted (429, 503).
- **X-Retry-After** (integer) - Legacy retry delay in seconds (429, 503).

### Response
#### Success Response (200)
- **RateLimit** (string) - Current ingress policy, remaining requests, and seconds until reset.
- **RateLimit-Policy** (string) - Ingress quota and window.
- **X-RateLimit-Limit** (integer) - Maximum requests allowed in the current rolling window.
- **X-RateLimit-Remaining** (integer) - Requests remaining in the current rolling window.
- **X-RateLimit-Reset** (integer) - Unix timestamp when the current rolling window resets.
- **x-request-id** (string) - Request correlation ID.
- **Retry-After** (integer) - Seconds until another request should be attempted. (429, 503)
- **X-Retry-After** (integer) - Legacy retry delay in seconds. (429, 503)

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### 200 response for GET /api/events

Source: https://hoplite.sh/docs/api/listPublicEvents

Example 200 response for GET /api/events. Contains an ok flag, an events array with event details, a nextCursor for pagination, and a hasMore boolean. The events.data object includes resource-specific fields such as id and status.

```json
{
  "ok": true,
  "events": [
    {
      "id": "event_example",
      "orgId": "org_example",
      "projectId": "project_example",
      "threadId": "thread_example",
      "runId": "run_example",
      "sequence": "42",
      "type": "run.completed",
      "data": {
        "id": "run_example",
        "status": "completed"
      },
      "occurredAt": "2026-09-22T10:00:00.000Z",
      "publishedAt": "2026-09-22T10:00:01.000Z",
      "cursor": "opaque-cursor"
    }
  ],
  "nextCursor": "opaque-cursor",
  "hasMore": false
}
```

--------------------------------

### POST /api/platform/v1/apps/{appId}/source-head/initialize

Source: https://hoplite.sh/docs/api

Initializes the shared app source for the first time.

```APIDOC
## POST /api/platform/v1/apps/{appId}/source-head/initialize

### Description
Initialize the shared app source once.

### Method
POST

### Endpoint
/api/platform/v1/apps/{appId}/source-head/initialize

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.

```

--------------------------------

### GET preview with frameOrigin

Source: https://hoplite.sh/docs/api/getPlatformPreview

Use this GET request to inspect an existing preview without starting it or resuming an archived workspace. The frameOrigin query parameter must be an exact HTTPS dashboard origin without a trailing slash. The request requires the thread:read permission and an API key.

```bash
curl --request GET \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/threads/threadId/preview?frameOrigin=https%3A%2F%2Fdashboard.example.com \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

--------------------------------

### GET /api/platform/v1/apps/{appId}/threads/{threadId}/preview

Source: https://hoplite.sh/docs/api/getPlatformPreview

Retrieves the current preview state and optional gateway credentials for a specific thread without starting or resuming the preview.

```APIDOC
## GET /api/platform/v1/apps/{appId}/threads/{threadId}/preview

### Description
Inspect the existing preview without starting it or resuming an archived workspace. Use the POST start endpoint with thread:update to start or resume. Supply frameOrigin as an exact HTTPS origin in the query. When a gateway URL exists, receive a fresh five-minute server-only credential. Relay HTTP and WebSocket requests through your authenticated backend; do not expose the credential to browsers. Responses the preview proxy generates itself carry X-Preview-State (starting, unavailable, not_found or unauthorized) with an unbranded body; relayed application responses never do, so your gateway can substitute its own page.

### Method
GET

### Endpoint
/api/platform/v1/apps/{appId}/threads/{threadId}/preview

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **threadId** (string) - Required - The thread ID.

#### Query Parameters
- **frameOrigin** (string<uri>) - Required - Exact HTTPS dashboard origin, without a trailing slash.

### Request Example
```bash
curl --request GET \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/threads/threadId/preview?frameOrigin=https%3A%2F%2Fdashboard.example.com \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Required - Always true.
- **preview** (object) - Required - Preview details.
- **preview.status** (string) - Required - One of: ready, unsupported, reconciling, blocked, starting, stopped, crashed, inactive.
- **preview.name** (string) - Optional - Preview name, min length 1.
- **preview.port** (integer) - Optional - Port number, min 1, max 65535.
- **preview.reason** (string) - Optional - Reason for current status.
- **preview.url** (string<uri>) - Optional - Preview URL.
- **preview.restart** (object) - Optional - Restart information.
- **preview.restart.launchId** (string) - Required - Launch ID, min length 1.
- **preview.restart.runId** (string) - Required - Run ID, pattern ^[a-f0-9]{16}$.
- **preview.restart.runScriptSha256** (string) - Required - SHA256 of run script, pattern ^[a-f0-9]{64}$.
- **preview.gateway** (object) - Required - Gateway credential details.
- **preview.gateway.header** (string) - Required - Header name, value: x-hoplite-preview-token.
- **preview.gateway.token** (string) - Required - Gateway token.
- **preview.gateway.expiresAt** (string<date-time>) - Required - Expiration timestamp.

#### Response Example
```json
{
  "ok": true,
  "preview": {
    "status": "ready",
    "name": "my-preview",
    "port": 8080,
    "reason": null,
    "url": "https://preview.example.com",
    "restart": {
      "launchId": "launch-123",
      "runId": "abcdef1234567890",
      "runScriptSha256": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "gateway": {
      "header": "x-hoplite-preview-token",
      "token": "gateway-token",
      "expiresAt": "2025-01-01T00:00:00Z"
    }
  }
}
```

### Status Codes
- **200** - Success
- **400** - Invalid request
- **401** - Authentication required
- **403** - Permission, app scope or entitlement denied
- **404** - App, source or thread not found
- **409** - Idempotency conflict or request in progress
- **413** - Request too large
- **503** - Source storage or execution unavailable

```

--------------------------------

### Create project with curl

Source: https://hoplite.sh/docs/api/createProject

Sends a POST request to create a new project. Requires the X-Api-Key header with the Hoplite API key and an Idempotency-Key header to prevent duplicate creation. The JSON body includes name, description, repositoryId, baseBranch, and clientOperationId.

```bash
curl --request POST \
  --url https://api.hoplite.sh/api/projects \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header 'Idempotency-Key: project-import-2026-08-10' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Storefront",
  "description": "Customer-facing web application",
  "repositoryId": "repo_987654321",
  "baseBranch": "main",
  "clientOperationId": "project-import-2026-08-10"
}'
```

--------------------------------

### GET /api/platform/v1/apps/{appId}/threads/{threadId}/messages/{messageId}

Source: https://hoplite.sh/docs/api/getPlatformMessage

Reads a single message from a thread, including queued follow-ups and the runId that started it. Requires the thread:read permission.

```APIDOC
## [GET] /api/platform/v1/apps/{appId}/threads/{threadId}/messages/{messageId}

### Description
Read one message, including a queued follow-up and the runId it started.

### Method
GET

### Endpoint
/api/platform/v1/apps/{appId}/threads/{threadId}/messages/{messageId}

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **threadId** (string) - Required - The thread ID.
- **messageId** (string) - Required - The message ID.

### Request Example
```bash
curl --request GET \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/threads/threadId/messages/messageId \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Required - Always true.
- **message** (object) - Required - The message object.
- **message.id** (string) - Required - The message ID.
- **message.threadId** (string) - Required - The thread ID.
- **message.runId** (string) - Required - The run ID that started the message.
- **message.role** (string) - Required - The role of the message sender.
- **message.kind** (string) - Required - The kind of message.
- **message.content** (string) - Required - The content of the message.
- **message.createdAt** (string) - Required - The creation timestamp.

#### Response Example
```json
{
  "ok": true,
  "message": {
    "id": "string",
    "threadId": "string",
    "runId": "string",
    "role": "string",
    "kind": "string",
    "content": "string",
    "createdAt": "string"
  }
}
```

### Status Codes
- **200** - Success
- **400** - Invalid request
- **401** - Authentication required
- **403** - Permission, app scope or entitlement denied
- **404** - App, source or thread not found
- **409** - Idempotency conflict or request in progress
- **413** - Request too large
- **503** - Source storage or execution unavailable
```

--------------------------------

### GET /api/platform/v1/apps/{appId}/source-head

Source: https://hoplite.sh/docs/api/getPlatformSourceHead

Reads the app's current accepted source and revision. This is not the published application. Start a new thread from this source ID to create an independent draft.

```APIDOC
## GET /api/platform/v1/apps/{appId}/source-head

### Description
Reads the app's current accepted source and revision. This is not the published application. Start a new thread from this source ID to create an independent draft.

### Method
GET

### Endpoint
/api/platform/v1/apps/{appId}/source-head

### Parameters
#### Path Parameters
- **appId** (string) - Required - The unique identifier of the app.

### Request Example
```bash
curl --request GET \
  --url https://api.hoplite.sh/api/platform/v1/apps/appId/source-head \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

### Response
#### Success Response (200)
Content type: `application/json`. Response type: `object`.

- **ok** (boolean) - Required - Always true.
- **head** (object) - Required - The source head object.
- **head.orgId** (string) - Required - The organization ID.
- **head.projectId** (string) - Required - The project ID.
- **head.sourceId** (string) - Required - The source ID.
- **head.revision** (integer) - Required - The revision number. Constraints: min -9007199254740991, max 9007199254740991.
- **head.updatedAt** (string) - Required - The timestamp of the last update.

#### Response Example
```json
{
  "ok": true,
  "head": {
    "orgId": "string",
    "projectId": "string",
    "sourceId": "string",
    "revision": 0,
    "updatedAt": "string"
  }
}
```

### Status Codes
- `200` — Success
- `400` — Invalid request
- `401` — Authentication required
- `403` — Permission, app scope or entitlement denied
- `404` — App, source or thread not found
- `409` — Idempotency conflict or request in progress
- `413` — Request too large
- `503` — Source storage or execution unavailable

```

--------------------------------

### POST /api/threads/{id}/preview/start

Source: https://hoplite.sh/docs/api/startThreadPreview

Starts a managed preview for a thread. Requires the thread:update permission. Accepts optional name and port query parameters and an optional Idempotency-Key header.

```APIDOC
## POST /api/threads/{id}/preview/start

### Description
Starts a managed preview for a thread. Requires the `thread:update` permission.

### Method
POST

### Endpoint
`/api/threads/{id}/preview/start`

### Parameters
#### Path Parameters
- **id** (string) - Required - The thread ID.

#### Query Parameters
- **name** (string) - Optional - The preview name.
- **port** (integer) - Optional - The port for the preview.

#### Headers
- **Idempotency-Key** (string) - Optional - Required for writes authenticated by a service credential and for service-account lifecycle writes. Other session writes may opt in. Reuse the key and payload for retries. Settled keys remain reserved for at least seven days; a transient 4xx releases its key. Changed payloads return 409. Match any legacy clientOperationId/clientMessageId in the body.

### Request Example
```bash
curl --request POST \
  --url https://api.hoplite.sh/api/threads/id/preview/start \
  --header "X-Api-Key: $HOPLITE_API_KEY" \
  --header "Idempotency-Key: $HOPLITE_OPERATION_ID"
```

### Response
#### Success Response (200)
Content type: `application/json`. Response type: `object`.

- **ok** (boolean) - Required - constant true
- **preview** (object) - Required - Preview details.
  - **name** (string) - Optional - min length 1
  - **status** (string) - Required - ready · unsupported · reconciling · blocked · starting · stopped · crashed · inactive
  - **port** (integer) - Optional - min 1, max 65535
  - **url** (string<uri>) - Optional - Preview URL.
  - **reason** (string) - Optional - Reason for status.
  - **expiresAt** (string<date-time>) - Optional - Expiration timestamp.
  - **oomKilled** (boolean) - Optional - Whether the preview was OOM killed.
  - **stopProvenance** (object) - Optional - Stop provenance details.
    - **initiator** (string) - Required - hoplite · external · process
    - **source** (string) - Required - managed_stop · signal · process_exit · workspace_archive · lifecycle_reconcile
    - **phase** (string) - Required - starting · post_ready
    - **signal** (string) - Optional - SIGHUP · SIGINT · SIGQUIT · SIGTERM
    - **exitCode** (integer) - Optional - min 0, max 255
    - **occurredAt** (string<date-time>) - Optional - Timestamp of stop.
    - **trigger** (string) - Optional - min length 1, max length 64
    - **cause** (string) - Optional - workspace_archive · generation_changed · supervision_lost · exit_unobserved
    - **resumeOnRestore** (boolean) - Optional - Whether to resume on restore.
  - **requiredResources** (object) - Optional - Required resources.
    - **cpu** (number) - Optional - CPU requirement.
    - **memoryGiB** (number) - Optional - Memory requirement in GiB.
  - **configuredResources** (object) - Optional - Configured resources.
    - **cpu** (number) - Optional - CPU configuration.
    - **memoryGiB** (number) - Optional - Memory configuration in GiB.
  - **verification** (object) - Optional - Verification details.
    - **http** (object) - Required - HTTP verification.
      - **statusCode** (integer | null) - Required - HTTP status code.
      - **responseTimeMs** (number | null) - Required - Response time in milliseconds.
      - **finalUrl** (string<uri> | null) - Required - Final URL after redirects.
      - **contentType** (string | null) - Required - Content type of response.
      - **isHtmlDocument** (boolean) - Required - Whether the response is an HTML document.
    - **browser** (object | null) - Required - Browser verification.
      - **available** (boolean) - Required - Whether browser verification is available.
      - **unavailableReason** (string) - Optional - deadline-exhausted · service-unavailable
      - **consoleErrorCount** (integer) - Required - min 0, max 9007199254740991
      - **consoleErrors** (object[]) - Required - max 3 items
        - **message** (string) - Required - Error message.
        - **stack** (string) - Optional - Stack trace.
      - **uncaughtExceptionCount** (integer) - Required - min 0, max 9007199254740991
      - **uncaughtExceptions** (object[]) - Required - max 3 items
        - **message** (string) - Required - Exception message.
        - **stack** (string) - Optional - Stack trace.

#### Response Example
```json
{
  "ok": true,
  "preview": {
    "name": "my-preview",
    "status": "ready",
    "port": 8080,
    "url": "https://example.com",
    "reason": null,
    "expiresAt": "2023-01-01T00:00:00Z",
    "oomKilled": false,
    "stopProvenance": null,
    "requiredResources": {
      "cpu": 0.5,
      "memoryGiB": 1.0
    },
    "configuredResources": {
      "cpu": 0.5,
      "memoryGiB": 1.0
    },
    "verification": {
      "http": {
        "statusCode": 200,
        "responseTimeMs": 100,
        "finalUrl": "https://example.com",
        "contentType": "text/html",
        "isHtmlDocument": true
      },
      "browser": {
        "available": true,
        "unavailableReason": null,
        "consoleErrorCount": 0,
        "consoleErrors": [],
        "uncaughtExceptionCount": 0,
        "uncaughtExceptions": []
      }
    }
  }
}
```
```

--------------------------------

### POST /api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

Source: https://hoplite.sh/docs/api

Starts or restores a source-backed preview for a thread.

```APIDOC
## POST /api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

### Description
Start or restore a source-backed preview.

### Method
POST

### Endpoint
/api/platform/v1/apps/{appId}/threads/{threadId}/preview/start

### Parameters
#### Path Parameters
- **appId** (string) - Required - The application ID.
- **threadId** (string) - Required - The thread ID.

```

--------------------------------

### GET /api/threads/{id}/preview/access

Source: https://hoplite.sh/docs/api/getThreadPreviewAccess

This endpoint inspects the existing preview without starting it and returns a fresh five-minute server-only gateway credential for its URL. It requires the thread:read permission and accepts frameOrigin as a query parameter.

```APIDOC
## GET /api/threads/{id}/preview/access

### Description
Inspect the existing preview without starting it, then receive a fresh five-minute server-only gateway credential for its URL. Start the preview first with startThreadPreview. Supply frameOrigin as the exact HTTPS dashboard origin. Relay HTTP and WebSocket requests through your authenticated backend to preview.url with the credential in X-Hoplite-Preview-Token; never expose it to browsers. Project restrictions are enforced when access is issued; revoking a credential stops new grants but not an unexpired one.

### Method
GET

### Endpoint
/api/threads/{id}/preview/access

### Parameters
#### Path Parameters
- **id** (string) - Required - 

#### Query Parameters
- **frameOrigin** (string<uri>) - Required - 
- **name** (string) - Optional - 
- **port** (integer) - Optional - 

### Request Example
```bash
curl --request GET \
  --url https://api.hoplite.sh/api/threads/id/preview/access?frameOrigin=frameOrigin \
  --header "X-Api-Key: $HOPLITE_API_KEY"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Required - constant true
- **preview** (object) - Required - 
- **preview.status** (string) - Required - ready · unsupported · reconciling · blocked · starting · stopped · crashed · inactive
- **preview.name** (string) - Optional - min length 1
- **preview.port** (integer) - Optional - min 1, max 65535
- **preview.reason** (string) - Optional - 
- **preview.url** (string<uri>) - Optional - 
- **preview.restart** (object) - Optional - 
- **preview.restart.launchId** (string) - Required - min length 1
- **preview.restart.runId** (string) - Required - pattern ^[a-f0-9]{16}$
- **preview.restart.runScriptSha256** (string) - Required - pattern ^[a-f0-9]{64}$
- **preview.gateway** (object | null) - Required - 
- **preview.gateway.Option 1** (object) - Optional - 
- **preview.gateway.Option 1.header** (string) - Required - constant "x-hoplite-preview-token"
- **preview.gateway.Option 1.token** (string) - Required - 
- **preview.gateway.Option 1.expiresAt** (string<date-time>) - Required - 
- **preview.gateway.Option 2** (null) - Optional - 

#### Response Example
```json
{
  "ok": true,
  "preview": {
    "status": "ready",
    "name": "preview",
    "port": 3000,
    "url": "https://preview-token.preview.hoplite.sh/",
    "gateway": {
      "header": "x-hoplite-preview-token",
      "token": "signed-gateway-token",
      "expiresAt": "2026-09-22T10:05:00.000Z"
    }
  }
}
```

### Response Headers
- **RateLimit** (string) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Current ingress policy, remaining requests, and seconds until reset, for example `"ingress";r=599;t=60`.
- **RateLimit-Policy** (string) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Ingress quota and window, for example `"ingress";q=600;qu="requests";w=60`.
- **X-RateLimit-Limit** (integer) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Maximum requests allowed in the current rolling window.
- **X-RateLimit-Remaining** (integer) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Requests remaining in the current rolling window.
- **X-RateLimit-Reset** (integer) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Unix timestamp when the current rolling window resets.
- **x-request-id** (string) - Statuses: 200, 400, 401, 402, 403, 404, 409, 410, 429, 500, 501, 503 - Request correlation ID.
- **Retry-After** (integer) - Statuses: 429, 503 - Seconds until another request should be attempted.
- **X-Retry-After** (integer) - Statuses: 429, 503 - Legacy retry delay in seconds.

### Status Codes
- **200** - Successful response
- **400** - Invalid request. Validation responses include field paths.
- **401** - The API key is missing, invalid, or lacks the operation's permission.
- **402** - The organization does not have access to the requested product capability.
- **403** - The key's current user no longer has the required organization membership or role.
- **404** - The resource is not available in the authenticated scope.
- **409** - The request conflicts with a retry receipt or current resource state.
- **410** - The event cursor has expired; capture a fresh head and resource snapshot.
- **429** - The API-key rate limit has been exceeded.
- **500** - The API encountered an unexpected failure.
- **501** - The deployment has not configured the requested capability.
- **503** - A required API dependency, including the rate limiter, is unavailable.
```