Developer Guide

The EchoStash API allows you to programmatically access your prompts. You can use any HTTP client like cURL, or integrate with your preferred programming language.

We also provide lightweight helper classes for Python and JavaScript to streamline integration. See the Helper Libraries section below.

All API requests require authentication via an API key. Sign in to create API keys.

curl -X GET "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123" \
  -H "X-API-KEY: sk_your_api_key"

Retrieve a prompt by its ID. Returns the currently published version content and metadata.

GET/api/sdk/prompts/{promptId}

curl -X GET "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123" \
  -H "X-API-KEY: sk_your_api_key"

{
  "id": 123,
  "name": "Welcome Email",
  "description": "Personalized welcome email template for new users",
  "content": "Hello, {{name}}! Welcome to {{company}}.",
  "parameterSymbol": "{{}}",
  "publishedVersionNo": 3,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:00:00Z"
}

Retrieve a specific version of a prompt by its version number. Useful for accessing historical versions or testing changes before publishing.

GET/api/sdk/prompts/{promptId}/versions/{versionNo}

curl -X GET "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123/versions/2" \
  -H "X-API-KEY: sk_your_api_key"

{
  "versionNo": 2,
  "content": "Hello, {{name}}! Welcome aboard.",
  "parameterSymbol": "{{}}",
  "metadata": "{\"author\": \"product-team\", \"notes\": \"Simplified greeting\"}",
  "createdAt": "2024-01-18T08:00:00Z"
}

Render a prompt with variable substitution. Pass your variables in the request body, and they will be replaced based on the prompt's parameter symbol (e.g., {{}}).

POST/api/sdk/prompts/{promptId}/render

curl -X POST "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123/render" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"name": "World", "company": "Acme Corp"}}'

{
  "content": "Hello, World! Welcome to Acme Corp.",
  "promptId": 123,
  "versionNo": 3
}

# Render a specific version
curl -X POST "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123/render" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"name": "World"}, "version": "2"}'

# Render the latest unpublished version
curl -X POST "https://gra-echostash-be-prod.up.railway.app/api/sdk/prompts/123/render" \
  -H "X-API-KEY: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"name": "World"}, "version": "latest"}'

The API returns standard HTTP status codes. Errors include a JSON body with details about what went wrong.

Example Error Response

{
  "timestamp": "2024-01-15T10:30:00Z",
  "status": 404,
  "error": "Prompt not found",
  "path": "/api/sdk/prompts/999"
}

To simplify integration, we provide lightweight helper classes for Python and JavaScript. These files wrap the API endpoints and can be dropped directly into your project.