PSH Agent API

Authentication

Create a personal key in Settings → API Keys. Send the secret as a bearer token. The full key is displayed once and is never recoverable from PSH Agent.

CopyAuthorization: Bearer psh_live_YOUR_API_KEY

X-API-Key is also accepted. Account-security endpoints require a signed browser session instead of a personal API key.

Models and focus modes

The gateway exposes stable profile IDs instead of requiring clients to know local Ollama model names.

Every generation also accepts a focus mode:

Web and documentation research

Set webSearch to true on /chat, or web_search on /chat/completions, to allow PSH Agent to search public documentation and fetch public pages. Technical profiles are instructed to prefer official documentation and primary sources. Private, loopback and local-network fetch targets are blocked.

Distributed generation queue

The gateway can distribute generation across multiple PSH Seed Workers. If every configured generation slot is busy, the request waits in the gateway queue instead of starting another model on the same worker.

Send your own X-Request-ID on the chat request, then poll this route to display live queue state and Nixie activity. The activity.steps array contains high-level progress such as queueing, seed assignment, documentation research, tool usage and finalization; it does not expose private model chain-of-thought.

Copycurl.exe "%PSH_AGENT_URL%/api/v1/queue/status?requestId=%REQUEST_ID%" ^
  -H "Authorization: Bearer %PSH_API_KEY%"

{
  "enabled": true,
  "capacity": 2,
  "active": 2,
  "queued": 3,
  "request": { "status": "queued", "position": 2 }
}

Chat

Set conversationId to continue a stored conversation. Model/focus/web settings are persisted with that conversation.

Request

Copy{
  "message": "Build a production Roblox inventory UI and verify current Creator Hub APIs.",
  "conversationId": null,
  "model": "roblox",
  "mode": "high",
  "webSearch": true
}

Response

{
  "status": "completed",
  "requestId": "5a30...",
  "conversationId": "8d32...",
  "message": "...",
  "model": "roblox",
  "mode": "high",
  "webSearch": true,
  "usage": { "inputTokens": 421, "outputTokens": 166 }
}

OpenAI-shaped chat completions

This convenience endpoint is stateful through conversation_id. Streaming is not exposed on this endpoint.

Copycurl.exe -X POST "%PSH_AGENT_URL%/api/v1/chat/completions" ^
  -H "Authorization: Bearer %PSH_API_KEY%" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\":\"coding\",\"reasoning_effort\":\"high\",\"web_search\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Build a production Express API\"}],\"conversation_id\":null}"

Conversations

Conversation data is isolated to the authenticated account.

Scheduled tasks

Supported schedules are once, daily, weekly and interval.

Copy{
  "name": "Daily server review",
  "prompt": "Check my servers and summarize anything requiring attention.",
  "scheduleType": "daily",
  "timezone": "Europe/Berlin",
  "timeOfDay": "09:00"
}

Protected-action approvals

Read-only tools can run automatically. State-changing Pterodactyl operations return approval_required and wait for explicit approval.

Web account endpoints

These routes require a signed web-session JWT. Personal psh_live_ keys are deliberately rejected for account-security operations.

Errors and request IDs

Every API request receives an X-Request-ID response header. You can provide your own UUID in the request header; this is also the ID used to inspect live generation queue state.

{ "error": "The generation queue is full. Please try again shortly.", "requestId": "f3f0..." }

Windows CMD quick test

Copyset "PSH_AGENT_URL=%PSH_AGENT_ORIGIN%"
set "PSH_API_KEY=psh_live_REPLACE_WITH_YOUR_KEY"
set "REQUEST_ID=11111111-2222-4333-8444-555555555555"

curl.exe -X POST "%PSH_AGENT_URL%/api/v1/chat" ^
  -H "Authorization: Bearer %PSH_API_KEY%" ^
  -H "X-Request-ID: %REQUEST_ID%" ^
  -H "Content-Type: application/json" ^
  -d "{\"message\":\"Create a production FiveM resource\",\"conversationId\":null,\"model\":\"fivem\",\"mode\":\"high\",\"webSearch\":true}"

Security model

Personal API keys are scoped and hashed at rest. User Pterodactyl Client API credentials are encrypted. Web research blocks obvious local/private destinations. Seed workers require a private shared secret and should be firewalled so only the gateway can reach them. The internal /api/v1/admin/ surface uses a separate service key and IP allowlist.