Skip to content

api-reference.md

Latest commit

 

History

History
83 lines (57 loc) · 3.05 KB

api-reference.md

File metadata and controls

83 lines (57 loc) · 3.05 KB
Raw

API Reference

The PromptConductor backend exposes a secure, high-performance streaming API for prompt optimization. It leverages Next.js Route Handlers and Server-Sent Events (SSE) to push reasoning and formatted prompt tokens to the client with minimal latency.

Authentication

All API endpoints are protected via Firebase Authentication ID Tokens. Requests must include the Authorization header with a valid Bearer token.

Important

If LOCAL_DEV_MODE=true is set in the environment, the API will bypass authentication and rate limiting for local testing, injecting a mock user ID (mock-developer-uid).

Authorization: Bearer <Firebase_ID_Token>

POST /api/optimize

Initiates an AI prompt optimization workflow against the target Google Cloud Vertex AI endpoint.

Request Body

Content-Type: application/json

Field Type Required Description
rawPrompt string Yes The user's original, unoptimized prompt text.
targetModel string Yes The ID/name of the target LLM architecture (e.g. Gemini 3.1 Pro (Low)). The backend uses this to dynamically fetch model-specific constraints from Vertex Search.

Example Request:

{
  "rawPrompt": "Write a python script to scrape a website",
  "targetModel": "Gemini 3.1 Pro (Low)"
}

Response

The response is a standard Server-Sent Event (SSE) text stream. Content-Type: text/event-stream

As the underlying Gemini model generates the analysis and optimized prompt, the API pipes textual chunks directly to the client.

Success Event Stream:

data: {"chunk":"<think>I need to construct a python scraper. "}

data: {"chunk":"I will use BeautifulSoup.</think>\n"}

data: {"chunk":"<optimized_prompt>..."}

Error Event Stream:

event: error
data: {"error": "Too many requests. Limit is 10 runs per minute.", "resetTime": 17183921100}

HTTP Status Codes

Code Status Description
200 OK Connection established, streaming chunks.
400 Bad Request Missing rawPrompt or targetModel in the request body.
401 Unauthorized Missing, expired, or invalid Firebase Bearer token.
429 Too Many Requests Rate limit exceeded. See Rate Limiting below.
500 Internal Server Error Failed to reach Vertex AI, Secret Manager, or Gemini endpoints.

Rate Limiting

The /api/optimize endpoint implements a token-bucket style rate limiter backed by a Firestore counter mechanism.

  • Limit: 10 requests per rolling 1 minute window per userId.
  • Enforcement: Enforced at the Edge (Next.js Route Handler).
  • Backend Storage: users/{userId}/rate_limit/{docId}

When a rate limit is hit, the API immediately aborts the stream and emits a 429 Too Many Requests alongside an SSE error payload containing the resetTime.

Caution

The rate limit Firestore documents are strictly protected from client-side manipulation. Only the Firebase Admin SDK (used securely by the /api/optimize route) can increment or reset the limits.