Prompt Coach API

AI-powered prompt optimization service. Analyzes your prompts for clarity, specificity, and effectiveness, then rewrites them for better LLM performance. Returns scored before/after comparisons with actionable improvement suggestions.

Base URL

https://api.jarvisclaw.ai/v1

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

This endpoint is x402-enabled. Payment of $0.002 per request is required via the x402 protocol header, or deducted from your wallet balance.

Endpoints

POST /prompt-coach/optimize

Optimize a prompt for better LLM interaction results.

Pricing

Endpoint	Price
`/prompt-coach/optimize`	$0.002 / request

Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	The prompt text to optimize
`model`	string	No	Target model the prompt is intended for (informational, helps tailor optimization)
`context`	string	No	Additional context about the use case to guide optimization

Request

json

{
  "prompt": "Write me a python script that does web scraping",
  "model": "gpt-4o",
  "context": "I need to scrape product prices from e-commerce sites for price comparison"
}

Response

json

{
  "success": true,
  "data": {
    "original_prompt": "Write me a python script that does web scraping",
    "optimized_prompt": "Write a Python script using the `requests` and `BeautifulSoup` libraries to scrape product names and prices from an e-commerce product listing page. The script should: 1) Accept a URL as input, 2) Handle pagination, 3) Extract product name, price, and URL into a structured format, 4) Export results to CSV, 5) Include error handling for network timeouts and missing elements. Use type hints and include docstrings.",
    "explanation": "The original prompt was too vague - it didn't specify the scraping target, libraries, output format, or error handling requirements. The optimized version provides concrete structure, specific deliverables, and technical constraints that will produce immediately usable code.",
    "score_before": 25,
    "score_after": 87,
    "suggestions": [
      "Always specify the target data structure and output format",
      "Include error handling requirements explicitly",
      "Mention specific libraries or constraints when relevant",
      "Define scope boundaries (single page vs. pagination, one site vs. multiple)"
    ],
    "model_used": "deepseek/deepseek-chat"
  }
}

Error Response

json

{
  "error": {
    "message": "invalid request: Key: 'PromptCoachX402Request.Prompt' Error:Field validation for 'Prompt' failed on the 'required' tag",
    "type": "invalid_request_error"
  }
}

Score Interpretation

Score Range	Meaning
1-25	Very vague, lacks specificity
26-50	Basic intent clear, missing important details
51-75	Good structure, could be more specific
76-90	Well-crafted, minor improvements possible
91-100	Excellent, highly specific and actionable

Usage Notes

The service uses an LLM internally to analyze and optimize prompts
Optimization preserves the original intent while improving clarity and specificity
The model field is informational — it helps the optimizer tailor suggestions for that model's strengths
Scores are subjective estimates on a 1-100 scale
Works best with English prompts; other languages are supported but may score lower

cURL Examples

API Key

bash

curl -X POST https://api.jarvisclaw.ai/v1/prompt-coach/optimize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "make me a website",
    "context": "I want a portfolio site to showcase my photography work"
  }'

x402 (Private Key — no API key needed)

The x402 flow requires two steps: first receive the 402 payment requirements, then resend with a signed payment header.

bash

# Step 1: Send request without auth → receive 402 with payment requirements
curl -s -w "\n%{http_code}" -X POST https://api.jarvisclaw.ai/v1/prompt-coach/optimize \
  -H "Content-Type: application/json" \
  -d '{"prompt": "make me a website"}'
# → HTTP 402 + JSON body with payment requirements (amount, recipient, etc.)

# Step 2: Sign the payment with your wallet and resend
# (In practice, use the SDK which handles this automatically)
curl -X POST https://api.jarvisclaw.ai/v1/prompt-coach/optimize \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-encoded-x402-payload>" \
  -d '{
    "prompt": "make me a website",
    "context": "I want a portfolio site to showcase my photography work"
  }'

TIP

The x402 payment signing is complex (EIP-712 typed data). Use the Python or Go SDK which handles it transparently.

SDK Usage

Python

API Keyx402 Private Key

python

from jarvisclaw import PromptCoachClient

client = PromptCoachClient(api_key="YOUR_API_KEY")

result = client.optimize(
    prompt="make me a website",
    context="I want a portfolio site to showcase my photography work"
)

print(f"Score: {result['score_before']} → {result['score_after']}")
print(f"Optimized: {result['optimized_prompt']}")
print(f"Suggestions: {result['suggestions']}")

python

from jarvisclaw import PromptCoachClient

# x402: Agent pays $0.002 per request directly from wallet
client = PromptCoachClient(private_key="0x<your-evm-private-key>")

result = client.optimize(
    prompt="write code that does the thing",
    model="gpt-4o",
    context="Building a REST API for a task management app"
)

print(f"Score: {result['score_before']} → {result['score_after']}")
print(f"Optimized: {result['optimized_prompt']}")
for suggestion in result['suggestions']:
    print(f"  💡 {suggestion}")

Go

API Keyx402 Private Key

package main

import (
    "context"
    "fmt"
    "log"

    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()
    client, err := jc.NewClient(jc.WithAPIKey("YOUR_API_KEY"))
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.PromptCoach(ctx, jc.PromptCoachRequest{
        Prompt:  "make me a website",
        Context: "I want a portfolio site to showcase my photography work",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Score: %.1f → %.1f\n", result.ScoreBefore, result.ScoreAfter)
    fmt.Printf("Optimized: %s\n", result.OptimizedPrompt)
}

package main

import (
    "context"
    "fmt"
    "log"

    jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
    ctx := context.Background()

    // x402: Agent pays $0.002 per request directly from wallet
    client, err := jc.NewClient(jc.WithPrivateKey("0x<your-evm-private-key>"))
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.PromptCoach(ctx, jc.PromptCoachRequest{
        Prompt:      "write code that does the thing",
        Model:       "openai/gpt-4o",
        Context:     "Building a REST API for a task management app",
        OptimizeFor: "technical",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Score: %.1f → %.1f\n", result.ScoreBefore, result.ScoreAfter)
    fmt.Printf("Optimized: %s\n", result.OptimizedPrompt)
    for _, s := range result.Suggestions {
        fmt.Printf("  - %s\n", s)
    }
}

PromptCoach is a method on *Client, not a nested client.PromptCoach.Optimize field, and score fields are float64. NewClient returns (*Client, error).

PromptScore / /v1/prompt-coach/score is not available

Both SDKs expose a score-only helper (PromptCoachClient.score() in Python, client.PromptScore in Go) that posts to /v1/prompt-coach/score. That route is not registered on the gateway and returns 404. Use optimize and read score_before — it scores the original prompt as a side effect.

Via AIP (Intent Protocol)

Prompt Coach is also available as an AIP intent (prompt_optimization), which allows unified routing through the intent system:

PythonGo

python

from jarvisclaw import IntentClient

# Works with both api_key and private_key.
# payload is positional; execute() forwards the provider response unchanged.
client = IntentClient(private_key="0x<your-evm-private-key>")

result = client.execute(
    "prompt_optimization",
    {
        "prompt": "explain machine learning",
        "model": "anthropic/claude-sonnet-4.6",
        "context": "Technical blog post for senior engineers",
    },
)
print(f"Optimized: {result['optimized_prompt']}")
print(f"Score: {result['score_before']} → {result['score_after']}")

client, _ := jc.NewClient(jc.WithPrivateKey("0x<your-evm-private-key>"))

raw, _ := client.Execute(ctx, jc.ExecuteRequest{
    Intent: "prompt_optimization",
    Payload: map[string]any{
        "prompt":  "explain machine learning",
        "model":   "anthropic/claude-sonnet-4.6",
        "context": "Technical blog post for senior engineers",
    },
})
fmt.Println(string(raw))

Prompt Coach API ​

Base URL ​

Authentication ​

Endpoints ​

POST /prompt-coach/optimize ​

Pricing ​

Parameters ​

Request ​

Response ​

Error Response ​

Score Interpretation ​

Usage Notes ​

cURL Examples ​

API Key ​

x402 (Private Key — no API key needed) ​

SDK Usage ​

Python ​

Go ​

Via AIP (Intent Protocol) ​

Prompt Coach API

Base URL

Authentication

Endpoints

POST /prompt-coach/optimize

Pricing

Parameters

Request

Response

Error Response

Score Interpretation

Usage Notes

cURL Examples

API Key

x402 (Private Key — no API key needed)

SDK Usage

Python

Go

Via AIP (Intent Protocol)