---
title: "Platform API"
description: "Build your own chat editor on Hoplite’s managed agents, workspaces, previews, and source storage."
canonical_url: "https://hoplite.sh/docs/platform"
markdown_url: "https://hoplite.sh/docs/platform.md"
---

# Platform API
URL: /docs/platform
LLM index: /llms.txt
Description: Build your own chat editor on Hoplite’s managed agents, workspaces, previews, and source storage.

# Platform API

Hoplite supplies the agent runtime, persistent source versions, isolated editing workspaces, authenticated previews, and downloadable builds. Your application owns its users, interface, release approval, and hosting. You can build a website editor without creating a GitHub repository for each customer.

The Direct API automates Hoplite’s existing product. The Platform API, under `/api/platform/v1`, gives your product a source-based workflow. Both use the same organization and project permissions. The Platform contract is currently a release candidate; use the API base URL for the environment where this version is deployed.

## Start with a saved source

Create a project using `POST /api/projects` with `{"name":"Customer website"}`. No repository binding is required. For an existing project, create a server-side service credential with `project:read`, `project:update`, `thread:create`, `thread:read`, and `thread:update`, scoped to that project. Creating projects also requires `project:create` with organization-wide scope. Keep credentials on your backend.

Import your starter files:

```sh
curl "$HOPLITE_API_URL/api/platform/v1/projects/$PROJECT_ID/sources" \
  -H "Authorization: Bearer $HOPLITE_SERVICE_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: starter-1' \
  --data '{"files":[{"path":"index.html","content":"<h1>Hello</h1>"}]}'
```

Start an editing thread with the returned `source.id`:

```sh
curl "$HOPLITE_API_URL/api/platform/v1/projects/$PROJECT_ID/threads" \
  -H "Authorization: Bearer $HOPLITE_SERVICE_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: edit-1' \
  --data "{\"sourceId\":\"$SOURCE_ID\",\"prompt\":\"Create a warm orange landing page\"}"
```

The response contains the thread and admitted run. Poll `GET /api/platform/v1/projects/{projectId}/threads/{threadId}/runs/{runId}`. A completed run’s `resultSourceId` identifies its immutable output, even after later edits. Retrieve it with `GET /api/platform/v1/projects/{projectId}/sources/{sourceId}/files`; returned file contents are base64, including text.

A successful run completes only after its source and final message are persisted. Failed runs keep the previous successful source. Send another prompt to `POST /api/platform/v1/projects/{projectId}/threads/{threadId}/messages` with `{"content":"Add a contact page"}` and a fresh idempotency key.

## Add the rest of your editor

- [Embed previews](/docs/platform/previews) through your authenticated gateway, with HTTP and WebSocket support.
- [Integrate versions and builds](/docs/platform/versions) to combine concurrent edits and retrieve deployment artifacts.
- [Handle lifecycle and retries](/docs/platform/operations) to control idle time, recover uncertain requests, and retain source history.

The reference separates Platform Sources, Threads, Drafts, Previews, Builds, and Workspaces. Download the [Platform OpenAPI specification](/docs/platform-openapi.json), or browse [the API reference](/docs/api). Existing project, credential, event, cancellation, and usage operations remain in the Direct API.

A runnable customer application and gateway are included in `examples/borradh-studio`. Its README identifies the local authentication, storage, and publishing pieces you must replace for a hosted product.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).