API Reference

The Longshot CLI exposes a full REST API for programmatic access. All API routes are validated with Zod schemas and documented via OpenAPI 3.1.

OpenAPI specification

The CLI serves an auto-generated OpenAPI 3.1.0 spec at:

GET http://localhost:3333/api/openapi.json

This spec is the definitive API reference — generated directly from the Zod schemas that validate every request at runtime. Import it into tools like Swagger UI, Postman, or any OpenAPI-compatible client.

Base URL

When running locally:

http://localhost:3333

When connected via the tunnel (through the web service):

https://app.longshothq.com/app/:daemonId

All API endpoints are under the /api prefix.

Tasks

MethodRouteDescription
GET/api/tasksList all tasks
GET/api/tasks/:idGet task detail
GET/api/tasks/:id/statusPoll task status (for UI updates)
POST/api/tasks/:id/readyMark task as ready
POST/api/tasks/:id/startStart work on task
POST/api/tasks/:id/cancelCancel a task
POST/api/tasks/:id/continueContinue a timed-out task

Chat

MethodRouteDescription
GET/api/chat/messagesGet chat messages (with pagination)
POST/api/chat/messageSend a chat message
POST/api/chat/draft-taskDraft a new task from a description
POST/api/chat/add-serviceAdd a service via natural language

Diff review

MethodRouteDescription
GET/api/diff/:idGet pending diff
POST/api/diff/:id/approveApprove and commit changes
POST/api/diff/:id/rejectReject and discard changes
POST/api/diff/:id/fixRequest a targeted fix

Agent

MethodRouteDescription
GET/api/agent/:runId/eventsGet agent events (with ?after=N for polling)

Work queue

MethodRouteDescription
GET/api/queueGet queue status (pending/running items)
DELETE/api/queue/:idRemove a pending queue item
POST/api/queue/:id/retryRetry a failed queue item

Git

MethodRouteDescription
GET/api/git/statusFetch from remote, return ahead/behind counts
POST/api/git/pushPush to remote
POST/api/git/pullPull from remote (supports { rebase: true })

Branches

MethodRouteDescription
GET/api/branchesList branches with current/active info
POST/api/branchesCreate a new branch
POST/api/branches/switchSwitch to a branch
POST/api/branches/:name/pushPush branch to remote
POST/api/branches/:name/mergeMerge branch into parent
DELETE/api/branches/:nameDelete a merged branch

Services

MethodRouteDescription
GET/api/servicesList all services with status
POST/api/servicesCreate a new service
PUT/api/services/:idUpdate a service definition
DELETE/api/services/:idDelete a service
POST/api/services/:id/startStart service
POST/api/services/:id/stopStop service
POST/api/services/:id/restartRestart service
GET/api/services/:id/logsGet service log tail
POST/api/services/:id/logs/clearClear service logs

Other endpoints

MethodRouteDescription
GET/api/specGet project spec
GET/api/historyGet action history
GET/api/run/:id/eventsGet run log events
GET/api/openapi.jsonOpenAPI 3.1 spec

Request validation

All JSON API routes validate requests at runtime using Zod schemas. Invalid requests receive a 400 response with structured error details:

{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_type",
        "path": ["message"],
        "message": "Required"
      }
    ]
  }
}