openapi: 3.1.0
info:
  title: Vercy Meta-model Resolution API
  version: 1.1.0
  description: Search published Vercy models, discover non-installable Wikidata profile candidates when local coverage is absent, and queue deduplicated completion or materialization research.
servers:
  - url: https://ver.cy/api/v1
paths:
  /models/search/:
    get:
      operationId: searchMetaModels
      parameters:
        - {name: q, in: query, required: true, schema: {type: string, minLength: 1, maxLength: 160}}
        - {name: language, in: query, description: Two- or three-letter label language for local and external discovery, schema: {type: string, default: en}}
        - {name: family, in: query, schema: {type: string}}
        - {name: category, in: query, schema: {type: string}}
        - {name: industry, in: query, description: Comma-separated values, schema: {type: string}}
        - {name: domain, in: query, description: Comma-separated values, schema: {type: string}}
        - {name: tags, in: query, description: Comma-separated values, schema: {type: string}}
      responses:
        '200': {description: Ranked curated matches and, only when local coverage is weak, non-installable generated-profile candidates from Wikidata}
  /models/resolve/:
    post:
      operationId: resolveOrRequestMetaModel
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ResolutionNeed'}
      responses:
        '200': {description: A published installable model was resolved}
        '202': {description: A deduplicated creation, completion or external-profile materialization request was accepted}
        '422': {description: The structural need is invalid}
        '429': {description: Anonymous request creation was rate limited}
  /model-requests/:
    get:
      operationId: getMetaModelRequest
      parameters:
        - {name: id, in: query, required: true, schema: {type: string, format: uuid}}
      responses:
        '200': {description: Current request state and published resolution when ready}
        '404': {description: Unknown request UUID}
components:
  schemas:
    ResolutionNeed:
      type: object
      required: [need]
      properties:
        need:
          type: object
          required: [name]
          properties:
            name: {type: string, maxLength: 160}
            description: {type: string, maxLength: 2000}
            questions: {type: array, maxItems: 20, items: {type: string, maxLength: 240}}
            properties: {type: array, maxItems: 40, items: {type: string, maxLength: 120}}
            actions: {type: array, maxItems: 30, items: {type: string, maxLength: 120}}
            examples: {type: array, maxItems: 20, items: {type: string, maxLength: 160}}
        filters:
          type: object
          properties:
            family: {type: string}
            category: {type: string}
            industry: {type: array, items: {type: string}}
            domain: {type: array, items: {type: string}}
            tags: {type: array, items: {type: string}}
        language: {type: string, default: en}
        client:
          type: object
          properties:
            agent: {type: string}
            version: {type: string}