dot-prompt

API Reference

The container exposes an HTTP API for compiling and rendering prompts.

Base URL

http://localhost:4041

Endpoints

Render Prompt

POST /api/render — Compile and inject in one call 

{
  "prompt": "hello",
  "params": {
    "variation": "analogy"
  },
  "runtime": {
    "user_input": "What is recursion?"
  },
  "seed": 42
}

Response

{
  "prompt": "...",
  "response_contract": {...}
}

Compile

POST /api/compile — Resolve control flow, return template 

{
  "prompt": "hello",
  "params": {...}
}

Inject

POST /api/inject — Fill runtime variables into template 

{
  "template": "Hello, @name!",
  "runtime": { "name": "World" }
}

Get Schema

GET /api/schema/:prompt — Schema for latest major version

GET /api/schema/:prompt/:major — Schema for specific major version

List Prompts

GET /api/prompts — List all prompt files

List Collections

GET /api/collections — List all collections

Events

GET /api/events — SSE stream for VS Code integration

Version

POST /api/version — Trigger version action 

{
  "prompt": "hello",
  "action": "bump_major"
}

Webhooks

POST /webhooks/commit — Post-commit hook receiver

Python Client

from dot_prompt import Client

client = Client("http://localhost:4041")

result = client.render(
    "concept_explanation",
    params={
        "pattern_step": 2,
        "variation": "recognition"
    },
    runtime={
        "user_input": "Can you give me an example?"
    },
    seed=42
)

result["prompt"]             # compiled string
result["response_contract"]  # derived schema

Error Responses

{
  "error": "validation_error",
  "message": "Parameter 'age' must be an integer",
  "details": {...}
}

Next Steps