canonical: https://jentic.com/apis/hoplite.sh/hoplite

# Hoplite Sh Hoplite API

The Hoplite API composes managed agent execution into your own application: it runs agent threads in persistent workspaces, opens and merges pull requests, serves previews, and gates tool approvals, all behind one organization-scoped API. It binds projects to GitHub repositories, creates and runs automations, and exposes runs, checkpoints, and usage. Use it to build a software factory where agents produce reviewed code changes rather than wiring the orchestration yourself.

## For AI agents

Run managed agent threads bound to GitHub repositories, open and merge pull requests, serve previews, gate tool approvals, and run automations through one organization-scoped API.

## Scope

Does not host your production runtime, store secrets as a vault, or sell compute directly. Use for managed agent threads, pull requests, previews, and project automations only.

## Capabilities

- Create projects and bind them to GitHub repositories
- Start agent threads and send them messages to run work
- Open, inspect, and merge pull requests from a thread
- Start managed previews and issue gateway access to them
- Create and run managed automations on a project
- Resolve tool approvals and read run state and tool activity
- Subscribe to signed webhooks and inspect delivery attempts

## Use cases

### Agent-Built Pull Requests

Turn a task into a reviewable pull request produced by a managed agent, instead of running an agent loop and git plumbing yourself. The API starts a thread on a project, takes the task as a message, and opens a pull request from the thread's workspace. Engineering teams use this to let agents propose changes that still go through review.

Example prompt: POST `/api/threads` to start a thread on a project, POST `/api/threads/{id}/messages` with the task, then POST `/api/threads/{id}/pr` to open a pull request.

### Managed Preview Review

Give reviewers a running preview of an agent's change before it merges, without standing up preview infrastructure. The API starts a managed preview for a thread and issues gateway access to reach it. Teams use this to validate changes in a live environment as part of review.

Example prompt: POST `/api/threads/{id}/preview/start` to launch the managed preview, then GET `/api/threads/{id}/preview/access` to issue gateway access.

### Project Automation

Schedule recurring agent work on a project so routine changes run without a human kicking off each one. The API creates a managed automation on a project and runs it on demand, and it exposes recent executions. Platform teams use this to automate repetitive maintenance across repositories.

Example prompt: POST `/api/projects/{id}/automations` to create a managed automation, then POST `/api/projects/{id}/automations/{automationId}/run` to run it.

### Agent-Driven Software Factory

An AI agent drives a full change from task to pull request inside your own application through one API. Through Jentic the agent discovers the thread and pull-request operations, loads their schemas, and chains them without bespoke orchestration code. This lets a build assistant produce reviewed code changes directly.

Example prompt: Search Jentic for 'open a pull request', create a thread with POST `/api/threads`, drive it with POST `/api/threads/{id}/messages`, and open the pull request with POST `/api/threads/{id}/pr.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/projects` | Create a project |
| GET | `/api/threads` | List threads |
| POST | `/api/threads` | Create a thread |
| POST | `/api/threads/{id}/messages` | Send a thread message |
| POST | `/api/threads/{id}/pr` | Create a pull request |
| POST | `/api/threads/{id}/pr/merge` | Merge or enqueue the pull request head |
| GET | `/api/source-control/github/repositories` | List repositories |
| POST | `/api/projects/{id}/automations` | Create a managed automation |

## Key resources

- **Projects** — Create, read, update, and delete projects and bind them to repositories
- **Threads** — Start agent threads, send messages, read runs, and manage run state
- **Pull Requests** — Open pull requests from a thread, read checks and comments, and merge
- **Previews and Automations** — Start managed previews and create and run project automations
- **Webhooks and Service Accounts** — Subscribe to signed events and manage service-account credentials

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 59 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 46 / 100
  - Developer Experience & Jentic Compatibility: 74 / 100
  - AI-Readiness & Agent Experience: 48 / 100
  - Agent Usability: 88 / 100
  - Security: 53 / 100
  - AI Discoverability: 68 / 100
- **View full report:** https://jentic.com/apis/hoplite.sh/hoplite/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Hoplite by hand means handling either its X-Api-Key header or a bearer token, binding repositories, and sequencing the thread, preview, and pull-request operations yourself. Through Jentic you install once, import Hoplite from the API Directory, store the credential once, and your agent calls those operations in order.
- **Permission scoping:** Hoplite puts the project and thread id in the URL path, such as `/api/projects/{id}` and `/api/threads/{id}`, so a rule can pin your agent to one project or thread. You choose the operations it may call, so destructive ones like deleting a project or merging a pull request are not included unless you add them.
- **Credential handling:** Your Hoplite API key or bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'open a pull request' or 'start an agent thread', and Jentic returns the matching Hoplite operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **E2B API** — Sandboxed cloud runtimes for agent code execution
- **GitHub REST API** — The repositories and pull requests Hoplite works against
- **Vercel API** — Deployments and preview hosting for merged changes

## FAQ

### Is there a Hoplite MCP server?

You do not need an MCP server to give your agent the Hoplite API. Jentic connects it directly from the API Directory: import Hoplite, store your credential once, and your agent calls the project, thread, and pull-request endpoints. Operations are discovered on demand, so no extra server's tool definitions load into the agent's context.

### What authentication does the Hoplite API use?

The Hoplite API authenticates with an API key in the X-Api-Key header or a bearer token in the Authorization header, per its OpenAPI spec, and a browser session cookie is also supported for signed-in use. Through Jentic the credential is stored encrypted by your own Jentic One instance and injected at call time, so it never enters the agent's prompt or logs.

### Can I open and merge pull requests with the Hoplite API?

Yes. POST `/api/threads/{id}/pr` opens a pull request from a thread, GET `/api/threads/{id}/pr/status` reads its checks and reviews, and POST `/api/threads/{id}/pr/merge` merges or enqueues the expected head. Projects are bound to GitHub repositories, which the source-control endpoints list.

### What are the rate limits for the Hoplite API?

The OpenAPI spec does not publish numeric request rate limits; Hoplite exposes the effective organization plan and runtime limits through its billing endpoints. Check the Hoplite documentation at https://hoplite.sh/docs for the current limits that apply to your plan.

### How do I open a pull request through Jentic?

Search Jentic with the query 'open a pull request', create a thread with POST `/api/threads`, drive it with POST `/api/threads/{id}/messages`, then execute POST `/api/threads/{id}/pr.` To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Hoplite API?

Yes. Write a rule that allows only the read and thread operations under one project, such as GET `/api/threads` and POST `/api/threads/{id}/messages`, so the agent can run work and read results but cannot merge pull requests, delete projects, or rotate service-account credentials, and every call it makes is logged. Because project and thread ids live in the URL path, you can confine it to a single project.