{
 "openapi": "3.1.0",
 "info": {
  "title": "Lingo API",
  "version": "1.0.0",
  "description": "Lingo turns \"I know it when I see it\" into design words. Tap the looks you like or type how it feels (\"make it pop\", \"too busy\"), and it writes a precise design brief with names and values to paste into any AI coding agent or chat. Public, no API key. Rate limited per client. Made by Clawhard Studio, an AI-powered studio. Support: support@clawhard.com.",
  "contact": {
   "name": "Clawhard Studio",
   "url": "https://clawhard.com",
   "email": "support@clawhard.com"
  }
 },
 "servers": [
  {
   "url": "https://lingo.clawhard.com"
  }
 ],
 "paths": {
  "/api/v1/terms": {
   "get": {
    "operationId": "terms",
    "summary": "List design vocabulary terms",
    "description": "Lists the design vocabulary Lingo knows: 36 named looks in six groups (layout, type, color, shape, motion, style), each with a plain-English meaning and the exact wording and values to give an AI coding agent, plus the vague phrases Lingo can decode (like \"make it pop\"). Returns: {groups:[{group, terms:[{id,name,plain,say,conflicts_with?}]}], vague_phrases:[string]}",
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "parameters": []
   }
  },
  "/api/v1/translate": {
   "get": {
    "operationId": "translate",
    "summary": "Translate a vague design request into design terms",
    "description": "Turns a vague design request (\"make it pop\", \"it looks cheap\", \"too busy\", \"less AI-looking\") into what designers usually mean by it and the specific design terms and values to use instead. Returns a ready-to-paste design brief and a link that opens it in Lingo. Returns: {matches:[{phrase, usually_means:[string], terms:[{id,name,say}]}], brief, open_url}",
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "parameters": [
     {
      "name": "phrase",
      "in": "query",
      "required": true,
      "description": "The vague request in plain words, e.g. \"it feels cheap and too busy\".",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "avoid_ai_look",
      "in": "query",
      "required": false,
      "description": "Add rules that steer away from the generic AI-made look. Default true.",
      "schema": {
       "type": "boolean"
      }
     }
    ]
   },
   "post": {
    "operationId": "translate_post",
    "summary": "Translate a vague design request into design terms",
    "description": "Turns a vague design request (\"make it pop\", \"it looks cheap\", \"too busy\", \"less AI-looking\") into what designers usually mean by it and the specific design terms and values to use instead. Returns a ready-to-paste design brief and a link that opens it in Lingo. Returns: {matches:[{phrase, usually_means:[string], terms:[{id,name,say}]}], brief, open_url}",
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "phrase": {
          "type": "string",
          "description": "The vague request in plain words, e.g. \"it feels cheap and too busy\"."
         },
         "avoid_ai_look": {
          "type": "boolean",
          "description": "Add rules that steer away from the generic AI-made look. Default true."
         }
        },
        "required": [
         "phrase"
        ]
       }
      }
     }
    }
   }
  },
  "/api/v1/brief": {
   "get": {
    "operationId": "brief",
    "summary": "Write a design brief from chosen terms",
    "description": "Builds a precise design brief (markdown) from Lingo term ids and/or vague phrases, ready to paste into an AI coding agent or a project rules file. Conflicting picks (for example sharp and soft corners) keep the last one. Includes optional \"don't look AI-made\" rules and a link that opens the brief in Lingo. Returns: {terms:[id], brief, open_url}",
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "parameters": [
     {
      "name": "terms",
      "in": "query",
      "required": false,
      "description": "Term ids from the terms tool, e.g. [\"airy\",\"display\",\"accent\",\"soft\"]. In a GET query use a comma-separated list.",
      "schema": {
       "type": "array",
       "items": {
        "type": "string"
       }
      },
      "style": "form",
      "explode": false
     },
     {
      "name": "say",
      "in": "query",
      "required": false,
      "description": "Optional vague request to decode and include, e.g. \"more premium\".",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "avoid_ai_look",
      "in": "query",
      "required": false,
      "description": "Add rules that steer away from the generic AI-made look. Default true.",
      "schema": {
       "type": "boolean"
      }
     }
    ]
   },
   "post": {
    "operationId": "brief_post",
    "summary": "Write a design brief from chosen terms",
    "description": "Builds a precise design brief (markdown) from Lingo term ids and/or vague phrases, ready to paste into an AI coding agent or a project rules file. Conflicting picks (for example sharp and soft corners) keep the last one. Includes optional \"don't look AI-made\" rules and a link that opens the brief in Lingo. Returns: {terms:[id], brief, open_url}",
    "responses": {
     "200": {
      "description": "Result. Always has \"ok\": true.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         },
         "additionalProperties": true
        }
       }
      }
     },
     "400": {
      "description": "Bad input. {\"ok\":false,\"error\":\"...\"}"
     },
     "429": {
      "description": "Rate limited. Retry after the Retry-After header."
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "terms": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "description": "Term ids from the terms tool, e.g. [\"airy\",\"display\",\"accent\",\"soft\"]. In a GET query use a comma-separated list."
         },
         "say": {
          "type": "string",
          "description": "Optional vague request to decode and include, e.g. \"more premium\"."
         },
         "avoid_ai_look": {
          "type": "boolean",
          "description": "Add rules that steer away from the generic AI-made look. Default true."
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "externalDocs": {
  "description": "llms.txt",
  "url": "https://lingo.clawhard.com/llms.txt"
 }
}