{
  "openapi": "3.1.0",
  "info": {
    "title": "J14 Design Agency API",
    "description": "Machine-readable API for autonomous AI agents, enterprise clients, and integrations. Exposes structured interfaces to submit client inquiries, consultation briefs, career applications, and query agency capabilities.",
    "version": "1.0.0",
    "x-api-version": "1",
    "contact": {
      "name": "J14 Design Technical Support",
      "email": "sales@j14design.com",
      "url": "https://j14design.com"
    }
  },
  "servers": [
    {
      "url": "https://j14design.com",
      "description": "Production Web & API Gateway — v1"
    },
    {
      "url": "https://j14-form-handler.contact-965.workers.dev",
      "description": "Serverless Form Handler Worker"
    }
  ],
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "integer",
                "example": 400,
                "description": "HTTP status code"
              },
              "message": {
                "type": "string",
                "example": "Validation failed: 'email' is required.",
                "description": "Human-readable error description"
              },
              "resolution": {
                "type": "string",
                "example": "Ensure all required fields are present and correctly formatted.",
                "description": "Suggested action to resolve the error"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "example": ["'name' must be a non-empty string", "'email' must be a valid email address"],
                "description": "Field-level validation errors"
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "example": "https://j14design.com/openapi.json",
                "description": "Link to API documentation"
              }
            }
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string",
            "example": "Technical lead received. We respond within one business day."
          }
        }
      },
      "ServiceItem": {
        "type": "object",
        "required": ["id", "title", "description"],
        "properties": {
          "id": {
            "type": "string",
            "example": "private-ai"
          },
          "title": {
            "type": "string",
            "example": "Private AI Integration & ML Development"
          },
          "description": {
            "type": "string",
            "example": "AI-ready data models, TensorFlow workflows, Vertex AI pipelines, and RAG systems."
          }
        }
      },
      "PortfolioItem": {
        "type": "object",
        "required": ["id", "title", "description"],
        "properties": {
          "id": {
            "type": "string",
            "example": "plexis-erp"
          },
          "title": {
            "type": "string",
            "example": "Plexis ERP"
          },
          "description": {
            "type": "string",
            "example": "A complete multi-store retail ERP ecosystem with real-time POS and inventory sync."
          }
        }
      }
    },
    "headers": {
      "X-RateLimit-Limit": {
        "description": "Maximum number of requests allowed per time window",
        "schema": {
          "type": "integer",
          "example": 60
        }
      },
      "X-RateLimit-Remaining": {
        "description": "Number of requests remaining in the current time window",
        "schema": {
          "type": "integer",
          "example": 58
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying after a rate limit response",
        "schema": {
          "type": "integer",
          "example": 30
        }
      }
    }
  },
  "paths": {
    "/api/contact": {
      "post": {
        "summary": "Submit client consultation or project brief",
        "description": "Submits a new technical consultation lead or RFP brief to J14 Design. Proxied securely to the serverless form handler.",
        "operationId": "submitContactInquiry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "project_description"],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 100,
                    "example": "Alex Smith"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "alex@company.com"
                  },
                  "company": {
                    "type": "string",
                    "maxLength": 100,
                    "example": "Acme Logistics"
                  },
                  "phone": {
                    "type": "string",
                    "example": "+1-555-234-5678"
                  },
                  "selected_technologies": {
                    "type": "string",
                    "example": "Custom ERP, Private AI (RAG), QuickBooks Integration"
                  },
                  "project_description": {
                    "type": "string",
                    "minLength": 20,
                    "example": "Need an enterprise middleware system to sync operational data with QuickBooks."
                  },
                  "turnstileToken": {
                    "type": "string",
                    "description": "Cloudflare Turnstile token or pre-authorized agent bypass token"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry accepted successfully",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error or missing required fields",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Forbidden — invalid Turnstile token or blocked request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity — request body is malformed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Too many requests — rate limit exceeded",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/careers": {
      "post": {
        "summary": "Submit developer profile or job application",
        "description": "Submits candidate developer profiles, CV links, and experience summaries to J14 Design talent acquisition.",
        "operationId": "submitCareerApplication",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "email", "role"],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 100,
                    "example": "Jordan Lee"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "jordan@example.com"
                  },
                  "role": {
                    "type": "string",
                    "example": "Senior Full-Stack Engineer"
                  },
                  "portfolio_url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://github.com/jordanlee"
                  },
                  "experience_years": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 50,
                    "example": 7
                  },
                  "resume_summary": {
                    "type": "string",
                    "example": "Specialized in React, Node.js, and cloud infrastructure architectures."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Application accepted successfully",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Too many requests",
            "headers": {
              "Retry-After": { "$ref": "#/components/headers/Retry-After" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/services": {
      "get": {
        "summary": "Retrieve agency services and capabilities catalog",
        "description": "Returns the structured catalog of software development, private AI, and cloud services offered by J14 Design.",
        "operationId": "getServicesCatalog",
        "responses": {
          "200": {
            "description": "Services catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["services"],
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ServiceItem" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/portfolio": {
      "get": {
        "summary": "Retrieve agency case studies and architecture portfolio",
        "description": "Returns verified case studies including Plexis ERP, Momentum Logistics, and microservices projects.",
        "operationId": "getPortfolioCases",
        "responses": {
          "200": {
            "description": "Case studies catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["projects"],
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/PortfolioItem" }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  }
}