# PromptMia API — Machine-Readable Reference

Base URL: https://promptmia.com
Auth:     Bearer {api_key}     (header: Authorization)
          Session cookie       (browser only — no header needed)

## Core workflow for LLM agents
1. POST /api/auth/login          → obtains session (or use pre-generated API key)
2. POST /api/templates           → create a template
3. POST /api/templates/{id}/compile → compile with variable values → get plain text
4. GET  /api/templates           → list owned templates
5. GET  /api/templates/public    → browse public templates (no auth)

## Template endpoints  (auth: API key or session)

POST /api/templates
  Body:    { title: string, content: string, tags?: string[], description?: string, is_public?: bool }
  Returns: { template: { id, user_id, title, content, tags, is_public, created_at, updated_at } }

GET /api/templates
  Returns: { templates: Template[] }

GET /api/templates/{id}
  Returns: { template: Template }

PUT /api/templates/{id}
  Body:    { title?, content?, tags?, description?, is_public? }
  Returns: { template: Template }

DELETE /api/templates/{id}
  Returns: { success: true }

## Compile & Download  (auth: API key or session — non-owners may access public templates)

POST /api/templates/{id}/compile
  Body:    { variables: Record<string,string> }
  Returns: { compiled: string, missing_variables: string[] }

GET /api/templates/{id}/download?format=raw|compiled&variables={base64-json}
  Returns: text/markdown file attachment

## Public templates  (no auth required)

GET /api/templates/public?q={search}&tag={tag}&author={userId}&sort=newest|oldest&page={n}
  Returns: { templates: Template[], total, page, page_size, total_pages }

GET /api/templates/{id}/public
  Returns: { template: { id, title, description, content, tags, created_at } }

## Share links  (auth: API key or session — must be template owner, except GET /api/share/{token})

POST /api/templates/{id}/share
  Body:    { prefilled_variables?: Record<string,string>, expires_in_hours?: number }
  Returns: { token: string, share_url: string, expires_at?: string }

GET /api/templates/{id}/shares
  Returns: { shares: [{ id, token, share_url, prefilled_variables, expires_at, created_at }] }

PUT /api/templates/{id}/shares/{shareId}
  Body:    { prefilled_variables: Record<string,string> }
  Returns: { success: true }

DELETE /api/templates/{id}/shares/{shareId}
  Returns: { success: true }

GET /api/share/{token}           (no auth required)
  Returns: { template: { id, title, description, content, tags }, prefilled_variables: Record<string,string>, expires_at?: string }

GET /api/shares                  (auth: session only)
  Query:   template_id? (optional filter)
  Returns: { shares: [{ id, token, share_url, prefilled_variables, expires_at, created_at, is_expired: bool, template: { id, title } }] }

## API Keys  (auth: session only — cannot be managed via API key)

GET /api/keys
  Returns: { keys: [{ id, name, key_prefix, last_used, created_at }] }

POST /api/keys
  Body:    { name: string }
  Returns: { api_key: { id, name, key_prefix, created_at }, raw_key: string }  <- raw_key shown once

DELETE /api/keys/{id}
  Returns: { success: true }

## Profile  (GET/PUT own profile: session only; GET by userId or username: no auth)

GET /api/profile                 (session only)
  Returns: { profile: { id, display_name, username, avatar_url, bio, email, created_at } }

PUT /api/profile                 (session only)
  Body:    { display_name?, bio?, username? }
  Returns: { profile: { ... } }

GET /api/profile/{userId}        (no auth)
  Returns: { profile: { id, display_name, username, avatar_url, bio, created_at }, templates: Template[] }

GET /api/u/{username}            (no auth)
  Returns: { profile: { id, display_name, username, avatar_url, bio, created_at }, templates: Template[] }

## Variable syntax in template content
  {{name}}                           text field, max 128 chars
  {{name|text}}                      explicit text type
  {{name|textarea:512}}              textarea, max 512 chars
  {{name|number}}                    numeric input
  {{name|email}}                     email input
  {{name|phone}}                     phone input
  {{name|list}}                      comma-separated list
  {{name|type:maxLength|description}} full form: all three segments

## API Key format
  All API keys start with 'pt_' followed by 64 hex characters.
  Keys are hashed server-side. The raw key is shown once on creation.
  Create keys at: https://promptmia.com/settings