API and worker contracts
Express routes
Generated from literal router registrations in the reviewed source. Auth is enforced on application routes; auth login/register/OAuth and SNS callback routes have their own behavior. Review linked handlers for request validation, authorization and response details. This is a route inventory, not a generated OpenAPI specification.
| Method | Path | Handler source |
|---|---|---|
| POST | /api/auth/register |
auth |
| POST | /api/auth/login |
auth |
| GET | /api/auth/me |
auth |
| POST | /api/auth/logout |
auth |
| GET | /api/auth/google |
auth |
| GET | /api/auth/google/callback |
auth |
| GET | /api/knowledge-base/ |
knowledgeBase |
| GET | /api/knowledge-base/content/:contentId |
knowledgeBase |
| POST | /api/knowledge-base/content/:contentId/retry |
knowledgeBase |
| GET | /api/knowledge-base/:id |
knowledgeBase |
| POST | /api/knowledge-base/ |
knowledgeBase |
| PATCH | /api/knowledge-base/:id |
knowledgeBase |
| DELETE | /api/knowledge-base/:id |
knowledgeBase |
| GET | /api/connectors/ |
connector |
| GET | /api/connectors/my-connections |
connector |
| GET | /api/connectors/active-model |
connector |
| POST | /api/connectors/connect |
connector |
| POST | /api/connectors/switch-model |
connector |
| PUT | /api/connectors/:connectorId/update |
connector |
| DELETE | /api/connectors/:connectorId/disconnect |
connector |
| GET | /api/chat-ai/published |
chatAI |
| GET | /api/chat-ai/knowledge-base/:knowledgeBaseId |
chatAI |
| GET | /api/chat-ai/:id |
chatAI |
| POST | /api/chat-ai/ |
chatAI |
| PATCH | /api/chat-ai/:id |
chatAI |
| DELETE | /api/chat-ai/:id |
chatAI |
| PATCH | /api/chat-ai/:id/toggle-publish |
chatAI |
| POST | /api/chat-ai/:id/chat |
chatAI |
| GET | /api/chat-ai/:id/messages |
chatAI |
| POST | /api/chat-ai/:id/messages |
chatAI |
| DELETE | /api/chat-ai/:id/messages |
chatAI |
| DELETE | /api/chat-ai/:id/messages/:messageId |
chatAI |
| GET | /api/agents/ |
agents |
| GET | /api/agents/:id |
agents |
| POST | /api/agents/ |
agents |
| PATCH | /api/agents/:id |
agents |
| PATCH | /api/agents/:id/toggle-publish |
agents |
| POST | /api/agents/:id/execute |
agents |
| POST | /api/agents/:id/resume |
agents |
| GET | /api/agents/:id/messages |
agents |
| DELETE | /api/agents/:id/messages |
agents |
| DELETE | /api/agents/:id |
agents |
| DELETE | /api/agents/:id |
agents |
| GET | /api/url-tree/by-id/:contentId |
urlTree |
| GET | /api/url-tree/:url |
urlTree |
| GET | /api/restricted-queries/ |
restrictedQuery |
| GET | /api/restricted-queries/knowledge-base/:kbId |
restrictedQuery |
| POST | /api/restricted-queries/ |
restrictedQuery |
| PUT | /api/restricted-queries/knowledge-base/:kbId |
restrictedQuery |
| DELETE | /api/restricted-queries/knowledge-base/:kbId |
restrictedQuery |
| GET | /knowledgebase/webhook/test |
webhook |
| GET | /api/webhook/webhook/test |
webhook |
| POST | /knowledgebase/webhook |
webhook |
| POST | /api/webhook/webhook |
webhook |
| POST | /knowledgebase/sns |
webhook |
| POST | /api/webhook/sns |
webhook |
GET /api/health is registered directly in index.ts and only reports process liveness. The agents router contains duplicate DELETE registrations for the same path in this snapshot.
RunPod payload examples
Use your own endpoint/credential and a test KB. Examples do not contain working credentials. Full sample JSON files are in examples.
| Task | Input | Application output |
|---|---|---|
| Embeddings | text: [string], task: "embeddings" |
Worker returns {output: vectors} inside RunPod outer output |
| Chat | user_query, kbId, optional history/settings/flags |
KNOWLEDGEBASE.STATUS, KNOWLEDGEBASE.CONTENT with llama_response/tokens/references |
| Transcriber | s3_key or audio_urls, kbId/content_type/title, optional diarization |
SNS-style attribute dictionary, transcript and status |
| Vision | s3_key or url, kbId, content_type image/video, title, optional delay |
SNS-style attributes, explanation/transcription/scene explanation |
Example request (RunPod outer input wrapper is already in the file):
curl -X POST "https://api.runpod.ai/v2/YOUR_ENDPOINT_ID/runsync" \
-H "Authorization: Bearer $RUNPOD_API_KEY" \
-H "Content-Type: application/json" \
--data @examples/embedding.json
Use /run for asynchronous submission and /status/JOB_ID for polling. Inspect both platform status and application status. A successful embedding response is normally shaped like {"status":"COMPLETED","output":{"output":[[...]]}}. Chat application status is Completed/Failed; the compatibility provider Lambda uses a different Success contract. Preserve punctuation and key names: the chat handler even emits KNOWLEDGEBASE.ID with a trailing space.
Native SNS Lambda test event
examples/sns-add-text.json reproduces the native Lambda envelope expected by the KB worker, rather than the Publish API request structure. A live publish must use SNS MessageAttributes with DataType/StringValue. The update webhook expects SNS headers including x-amz-sns-message-type, a notification body and Type/Value attributes. See synchronization before constructing manual events.
Scraper direct invoke
Example payload: {"KBID":"123","CONTENT":{"url":"https://example.com","depth":0},"CONTENT_TYPE":"url","UNIQUE_ID":"456"}. Multi-page orchestration adds parent_url and tree_document_id. RETURN_CONTENT_ONLY is a separate scraper-only extraction mode; it is not the complete KB indexing flow.