# Hoplite API reference

Build your own cloud software factory with Hoplite. Compose managed agent execution, persistent workspaces, previews, approvals, and pull requests into your own application and workflows through one organization-scoped API.

Production base URL: `https://api.hoplite.sh`.

Direct API specification: `/docs/openapi.json`. Platform API specification: `/docs/platform-openapi.json`. Start a customer-built editor with `/docs/platform`.

## Endpoints

### Service accounts

- [GET /api/service-accounts](/docs/api/listServiceAccounts) — List service accounts

- [POST /api/service-accounts](/docs/api/createServiceAccount) — Create a service account

- [PATCH /api/service-accounts/{id}](/docs/api/updateServiceAccount) — Restrict or disable a service account

- [POST /api/service-accounts/{id}/rotate](/docs/api/rotateServiceAccount) — Rotate a service account credential

- [GET /api/service-accounts/{id}/credentials](/docs/api/listServiceCredentials) — List service credential identities

- [DELETE /api/service-accounts/{id}/credentials/{credentialId}](/docs/api/revokeServiceCredential) — Revoke a service credential

- [GET /api/service-accounts/self](/docs/api/getServiceAccountIdentity) — Inspect the calling service account

- [POST /api/service-accounts/self/rotate](/docs/api/rotateOwnServiceCredential) — Rotate the calling service credential

### Repositories

- [GET /api/source-control/github/installations](/docs/api/listGitHubInstallations) — List GitHub installations

- [GET /api/source-control/github/repositories](/docs/api/listGitHubRepositories) — List repositories

- [GET /api/source-control/github/repositories/{id}/branches](/docs/api/listGitHubRepositoryBranches) — List repository branches

- [GET /api/source-control/github/repositories/{id}/inspect](/docs/api/inspectGitHubRepository) — Inspect a repository

### Projects

- [GET /api/projects](/docs/api/listProjects) — List projects

- [POST /api/projects](/docs/api/createProject) — Create a project

- [GET /api/projects/{id}](/docs/api/getProject) — Get a project

- [PATCH /api/projects/{id}](/docs/api/updateProject) — Update project configuration

- [DELETE /api/projects/{id}](/docs/api/deleteProject) — Delete a project

- [GET /api/projects/{id}/repositories](/docs/api/listProjectRepositories) — Read project repository bindings

- [PUT /api/projects/{id}/repositories](/docs/api/assignProjectRepositories) — Assign project repositories

### Environment variables

- [GET /api/projects/{id}/env-vars](/docs/api/listProjectEnvironment) — List environment variable identities

- [PUT /api/projects/{id}/env-vars/{key}](/docs/api/setProjectEnvironment) — Set an encrypted project environment variable

- [DELETE /api/projects/{id}/env-vars/{key}](/docs/api/deleteProjectEnvironment) — Delete a project environment variable

### Models

- [GET /api/model-providers](/docs/api/listModels) — Discover authorized models and run capabilities

### Threads

- [GET /api/threads](/docs/api/listThreads) — List threads

- [POST /api/threads](/docs/api/createThread) — Create a thread

- [GET /api/threads/{id}](/docs/api/getThread) — Get a thread

- [PATCH /api/threads/{id}](/docs/api/updateThread) — Update thread state or spending limit

- [POST /api/threads/{id}/compact](/docs/api/compactThread) — Compact a thread

### Messages

- [GET /api/threads/{id}/messages](/docs/api/listThreadMessages) — List thread messages

- [POST /api/threads/{id}/messages](/docs/api/appendThreadMessage) — Send a thread message

- [GET /api/threads/{id}/export](/docs/api/exportThreadTranscript) — Export a thread transcript

### Runs

- [GET /api/threads/{id}/runs](/docs/api/listThreadRuns) — List thread runs

- [GET /api/threads/{id}/run-state](/docs/api/getThreadRunState) — Read authoritative run state

- [GET /api/threads/{id}/active-run](/docs/api/getActiveRun) — Read the active run identity

- [POST /api/threads/{id}/stop](/docs/api/stopRun) — Stop an explicitly identified run

- [POST /api/threads/{id}/retry](/docs/api/retryThread) — Retry a thread

- [GET /api/threads/{id}/runs/{runId}/failure](/docs/api/getRunFailure) — Inspect run failure

- [GET /api/threads/{id}/runs/{runId}/activity](/docs/api/listRunActivity) — Read tool activity

- [GET /api/threads/{id}/runs/{runId}/activity/bounds](/docs/api/getRunActivityBounds) — Read tool activity bounds

### Approvals

- [POST /api/threads/{id}/approvals/{approvalId}](/docs/api/resolveToolApproval) — Resolve a tool approval

- [GET /api/threads/{id}/approvals](/docs/api/listThreadApprovals) — List pending tool approvals

### Workspaces

- [GET /api/threads/{id}/workspace/recovery](/docs/api/getWorkspaceRecovery) — Read workspace recovery options

- [POST /api/threads/{id}/workspace/recovery](/docs/api/recoverWorkspace) — Recover or explicitly reset the workspace

### Diffs and checkpoints

- [GET /api/threads/{id}/diff](/docs/api/getThreadDiff) — Read the managed workspace diff

- [GET /api/threads/{id}/checkpoints](/docs/api/listThreadCheckpoints) — List durable checkpoints

- [POST /api/threads/{id}/checkpoints/{checkpointId}/restore](/docs/api/restoreCheckpoint) — Restore a checkpoint

### Attachments

- [POST /api/threads/{id}/attachments/presign](/docs/api/presignThreadAttachment) — Prepare a direct attachment upload

- [POST /api/threads/{id}/attachments/confirm](/docs/api/confirmThreadAttachment) — Persist a staged attachment

- [GET /api/threads/{id}/attachments/{artifactId}](/docs/api/downloadThreadAttachment) — Download a thread attachment

### Previews

- [GET /api/threads/{id}/preview](/docs/api/getThreadPreview) — Read preview state

- [POST /api/threads/{id}/preview/start](/docs/api/startThreadPreview) — Start the managed preview

- [GET /api/threads/{id}/preview/access](/docs/api/getThreadPreviewAccess) — Issue preview gateway access

### Pull requests

- [POST /api/threads/{id}/pr](/docs/api/createPullRequest) — Create a pull request

- [GET /api/threads/{id}/pr/status](/docs/api/getPullRequestStatus) — Read pull request checks and reviews

- [GET /api/threads/{id}/pr/comments](/docs/api/getPullRequestComments) — Read pull request comments

- [POST /api/threads/{id}/pr/merge](/docs/api/mergePullRequest) — Merge or enqueue the expected pull request head

- [GET /api/threads/{id}/pr/review-loop](/docs/api/getPullRequestReviewLoop) — Read managed review-loop state

- [PATCH /api/threads/{id}/pr/review-loop](/docs/api/updatePullRequestReviewLoop) — Configure the managed review loop

### Automations

- [GET /api/projects/{id}/automations](/docs/api/listAutomations) — List managed automations

- [POST /api/projects/{id}/automations](/docs/api/createAutomation) — Create a managed automation

- [GET /api/projects/{id}/automations/status](/docs/api/getAutomationStatus) — Read automation execution status

- [GET /api/projects/{id}/automations/{automationId}/executions](/docs/api/listAutomationExecutions) — Read recent automation executions

- [PATCH /api/projects/{id}/automations/{automationId}](/docs/api/updateAutomation) — Update a managed automation

- [DELETE /api/projects/{id}/automations/{automationId}](/docs/api/deleteAutomation) — Delete a managed automation

- [POST /api/projects/{id}/automations/{automationId}/run](/docs/api/runAutomation) — Run a managed automation

### MCP servers

- [GET /api/mcp/servers](/docs/api/listMcpServers) — Read redacted MCP configuration

- [POST /api/mcp/servers](/docs/api/createMcpServer) — Configure an MCP server

- [PATCH /api/mcp/servers/{id}](/docs/api/updateMcpServer) — Update MCP configuration

- [DELETE /api/mcp/servers/{id}](/docs/api/deleteMcpServer) — Remove an MCP server

### Events

- [GET /api/events/head](/docs/api/getEventHead) — Capture the event publication cursor

- [GET /api/events](/docs/api/listPublicEvents) — Replay durable public events

- [GET /api/events/stream](/docs/api/streamPublicEvents) — Stream public events and live drafts

### Webhooks

- [GET /api/webhooks](/docs/api/listWebhooks) — List webhook subscriptions

- [POST /api/webhooks](/docs/api/createWebhook) — Subscribe to signed public events

- [PATCH /api/webhooks/{id}](/docs/api/updateWebhook) — Update or pause a webhook

- [DELETE /api/webhooks/{id}](/docs/api/disableWebhook) — Disable a webhook subscription

- [POST /api/webhooks/{id}/rotate-secret](/docs/api/rotateWebhookSecret) — Rotate a webhook signing secret

- [GET /api/webhooks/{id}/deliveries](/docs/api/listWebhookDeliveries) — Inspect webhook delivery attempts

- [POST /api/webhooks/{id}/deliveries/{deliveryId}/redeliver](/docs/api/redeliverWebhook) — Request a new delivery of an existing event

### Operation receipts

- [GET /api/operations/{id}](/docs/api/getApiOperation) — Read a write receipt

### Billing and usage

- [GET /api/billing/plan](/docs/api/getBillingPlan) — Read the effective organization plan and runtime limits

- [GET /api/billing/summary](/docs/api/getBillingSummary) — Read available and reserved organization credits

- [GET /api/threads/{id}/usage](/docs/api/getThreadUsage) — Read thread spend

- [GET /api/usage](/docs/api/getOrganizationUsage) — Read organization usage

### System

- [GET /health](/docs/api/getHealth) — Health check

- [GET /api/capabilities](/docs/api/getFactoryCapabilities) — Discover the available factory surface

### Platform · Apps

- [GET /api/platform/v1/apps](/docs/api/listPlatformApps) — List apps

- [POST /api/platform/v1/apps](/docs/api/createPlatformApp) — Create an app

- [GET /api/platform/v1/apps/{appId}](/docs/api/getPlatformApp) — Read an app

- [PATCH /api/platform/v1/apps/{appId}](/docs/api/updatePlatformApp) — Update an app

- [DELETE /api/platform/v1/apps/{appId}](/docs/api/deletePlatformApp) — Delete an app and everything in it

### Platform · Sources

- [POST /api/platform/v1/apps/{appId}/sources](/docs/api/importPlatformSource) — Import an immutable source bundle

- [GET /api/platform/v1/apps/{appId}/sources/{sourceId}](/docs/api/getPlatformSource) — Get source metadata

- [GET /api/platform/v1/apps/{appId}/sources/{sourceId}/files](/docs/api/getPlatformSourceFiles) — Download source files

### Platform · Threads

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}/runs/{runId}](/docs/api/getPlatformRun) — Read an agent run and its immutable result source

- [GET /api/platform/v1/apps/{appId}/threads](/docs/api/listPlatformThreads) — List source-backed threads in an app

- [POST /api/platform/v1/apps/{appId}/threads](/docs/api/createPlatformThread) — Run an agent from a source bundle

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}](/docs/api/getPlatformThread) — Read a source-backed thread and its latest source

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}/messages](/docs/api/listPlatformMessages) — Read thread messages

- [POST /api/platform/v1/apps/{appId}/threads/{threadId}/messages](/docs/api/appendPlatformMessage) — Continue editing a source-backed workspace

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}/messages/{messageId}](/docs/api/getPlatformMessage) — Read one message

### Platform · Drafts

- [GET /api/platform/v1/apps/{appId}/source-head](/docs/api/getPlatformSourceHead) — Read the shared app source

- [POST /api/platform/v1/apps/{appId}/source-head/initialize](/docs/api/initializePlatformSourceHead) — Initialize the shared app source once

- [POST /api/platform/v1/apps/{appId}/threads/{threadId}/apply](/docs/api/applyPlatformDraft) — Queue a draft for integration into the app

- [GET /api/platform/v1/apps/{appId}/applies/{applyId}](/docs/api/getPlatformDraftApply) — Read an apply result or conflicts

### Platform · Previews

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}/preview](/docs/api/getPlatformPreview) — Read a preview and refresh gateway access

- [POST /api/platform/v1/apps/{appId}/threads/{threadId}/preview/start](/docs/api/startPlatformPreview) — Start or restore a source-backed preview

### Platform · Builds

- [POST /api/platform/v1/apps/{appId}/threads/{threadId}/builds](/docs/api/createPlatformBuild) — Build a pinned source version

- [GET /api/platform/v1/apps/{appId}/builds/{buildId}](/docs/api/getPlatformBuild) — Read build status

- [GET /api/platform/v1/apps/{appId}/builds/{buildId}/logs](/docs/api/getPlatformBuildLogs) — Read build logs

- [GET /api/platform/v1/apps/{appId}/builds/{buildId}/manifest](/docs/api/getPlatformBuildManifest) — Read build manifest

- [GET /api/platform/v1/apps/{appId}/builds/{buildId}/artifact](/docs/api/getPlatformBuildArtifact) — Read build artifact

### Platform · Workspaces

- [POST /api/platform/v1/apps/{appId}/threads/{threadId}/workspace/activity](/docs/api/recordPlatformWorkspaceActivity) — Keep an editing workspace active

- [GET /api/platform/v1/apps/{appId}/threads/{threadId}/workspace/policy](/docs/api/getPlatformWorkspacePolicy) — Read the workspace idle policy

### Platform · Events

- [GET /api/platform/v1/events/head](/docs/api/getPlatformEventHead) — Capture the event cursor for all apps

- [GET /api/platform/v1/events](/docs/api/listPlatformEvents) — Replay events for all apps

- [GET /api/platform/v1/events/stream](/docs/api/streamPlatformEvents) — Stream events for all apps

- [GET /api/platform/v1/apps/{appId}/events/head](/docs/api/getPlatformAppEventHead) — Capture the event cursor for one app

- [GET /api/platform/v1/apps/{appId}/events](/docs/api/listPlatformAppEvents) — Replay events for one app

- [GET /api/platform/v1/apps/{appId}/events/stream](/docs/api/streamPlatformAppEvents) — Stream events and live drafts for one app