{
  "openapi": "3.1.1",
  "info": {
    "title": "Xikota Design public inquiry API v1",
    "version": "1.0.0",
    "description": "Version 1 of the existing website inquiry form API. The compatible legacy alias /api/iniciar remains available. Administrative and private proposal operations are excluded. POST creates real records and may send email: require the person to review and authorize the request first. Versioning and any future deprecation announcements are documented at https://xikota.design/docs#versionamento.",
    "contact": {
      "name": "Xikota Design",
      "email": "contato@xikota.design",
      "url": "https://xikota.design/contact"
    }
  },
  "servers": [
    {
      "url": "https://xikota.design"
    }
  ],
  "externalDocs": {
    "description": "Authentication, examples, privacy and quota behavior",
    "url": "https://xikota.design/docs#versionamento"
  },
  "paths": {
    "/api/v1/iniciar": {
      "get": {
        "operationId": "getProjectInquiryConfiguration",
        "summary": "Read public inquiry form configuration",
        "description": "Read-only public form configuration. The omitted locale preserves the original {turnstile} response shape. Supplying locale returns genuinely localized instructions for reviewing the project or completing the anti-spam challenge. Limited to 120 reads per client IP per 60 seconds, shared with /api/iniciar; this budget is separate from POST inquiry quotas. No inquiry or email is created.",
        "security": [],
        "responses": {
          "200": {
            "description": "Public form configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "turnstile"
                  ],
                  "properties": {
                    "turnstile": {
                      "oneOf": [
                        {
                          "type": "null"
                        },
                        {
                          "type": "object",
                          "required": [
                            "siteKey"
                          ],
                          "properties": {
                            "siteKey": {
                              "type": "string",
                              "description": "Public site key; never a secret."
                            }
                          },
                          "additionalProperties": false
                        }
                      ]
                    },
                    "locale": {
                      "type": "string",
                      "enum": [
                        "pt-BR",
                        "en"
                      ],
                      "description": "Echoes the requested guidance language."
                    },
                    "guidance": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "challengeRequired",
                        "instructions",
                        "formUrl",
                        "contactUrl"
                      ],
                      "properties": {
                        "challengeRequired": {
                          "type": "boolean",
                          "description": "Whether a person must solve the configured challenge before POST."
                        },
                        "instructions": {
                          "type": "string",
                          "description": "Instruction in the requested language, grounded in the current challenge configuration."
                        },
                        "formUrl": {
                          "type": "string",
                          "format": "uri",
                          "enum": [
                            "https://xikota.design/iniciar"
                          ]
                        },
                        "contactUrl": {
                          "type": "string",
                          "format": "uri",
                          "enum": [
                            "https://xikota.design/contact"
                          ]
                        }
                      }
                    }
                  },
                  "description": "turnstile is always present. locale and guidance are returned together only when the locale query parameter is supplied.",
                  "additionalProperties": false
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Actual shared read budget: \"inquiry-read\";q=120;w=60. Versioned and legacy URLs share the same client-IP counter.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Current remaining read requests and reset delay, for example \"inquiry-read\";r=119;t=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Inquiry form temporarily disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or repeated locale value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Actual shared read budget: \"inquiry-read\";q=120;w=60. Versioned and legacy URLs share the same client-IP counter.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Current remaining read requests and reset delay, for example \"inquiry-read\";r=119;t=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "The shared read budget is exhausted; wait Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Actual shared read budget: \"inquiry-read\";q=120;w=60. Versioned and legacy URLs share the same client-IP counter.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Current remaining read requests and reset delay, for example \"inquiry-read\";r=119;t=60.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Seconds until the exhausted window resets.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected failure. No request data or stack trace returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Actual shared read budget: \"inquiry-read\";q=120;w=60. Versioned and legacy URLs share the same client-IP counter.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Current remaining read requests and reset delay, for example \"inquiry-read\";r=119;t=60.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "description": "When present, include the corresponding Portuguese or English guidance for a person authorizing submission. Omit for the legacy configuration-only JSON shape. Invalid or repeated locale values return400 and still consume the read budget.",
            "schema": {
              "type": "string",
              "enum": [
                "pt-BR",
                "en"
              ]
            }
          }
        ]
      },
      "post": {
        "operationId": "submitProjectInquiry",
        "summary": "Submit an authorized project inquiry",
        "description": "Creates a contact and opportunity in the studio and may send confirmation email. Review personal data and obtain user authorization before invoking. Requires allowed Origin; Turnstile is fail-closed when configured. Six attempts per client IP per 600 seconds and five per email per 3,600 seconds. Does not subscribe the person to marketing or agree price, scope or timing.",
        "security": [],
        "x-openai-isConsequential": true,
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "description": "CSRF origin check; use the canonical studio origin. No CORS access is granted to arbitrary websites.",
            "schema": {
              "type": "string",
              "enum": [
                "https://xikota.design"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectInquiry"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry recorded. Does not mean the project is accepted.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Quota policies as Structured Fields, per draft-ietf-httpapi-ratelimit-headers-11. Example: \"inquiry-ip\";q=6;w=600.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Remaining requests and seconds until reset for each checked policy. Example: \"inquiry-ip\";r=5;t=600.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "confirmationEmail": {
                      "type": "boolean",
                      "description": "True only when the configured email provider delivers real email."
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Accepted response shape for the anti-spam path; no further retry is needed.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Quota policies as Structured Fields, per draft-ietf-httpapi-ratelimit-headers-11. Example: \"inquiry-ip\";q=6;w=600.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Remaining requests and seconds until reset for each checked policy. Example: \"inquiry-ip\";r=5;t=600.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "confirmationEmail": {
                      "type": "boolean",
                      "description": "True only when the configured email provider delivers real email."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation or anti-spam failure.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Quota policies as Structured Fields, per draft-ietf-httpapi-ratelimit-headers-11. Example: \"inquiry-ip\";q=6;w=600.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Remaining requests and seconds until reset for each checked policy. Example: \"inquiry-ip\";r=5;t=600.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Origin absent or not permitted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Quota exceeded. Wait Retry-After before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "RateLimit-Policy": {
                "description": "Quota policies as Structured Fields, per draft-ietf-httpapi-ratelimit-headers-11. Example: \"inquiry-ip\";q=6;w=600.",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit": {
                "description": "Remaining requests and seconds until reset for each checked policy. Example: \"inquiry-ip\";r=5;t=600.",
                "schema": {
                  "type": "string"
                }
              },
              "Retry-After": {
                "description": "Seconds until the exhausted window resets.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              },
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Inquiry service disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected internal failure; no stack traces or secrets returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "API-Version": {
                "description": "Current major version, also explicit in the canonical URL.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "1"
                  ]
                }
              },
              "Link": {
                "description": "Links to the OpenAPI contract and version policy.",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message",
          "resolution"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Safe explanation in Brazilian Portuguese."
          },
          "resolution": {
            "type": "string",
            "description": "How the client can resolve the error."
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Field-specific validation errors when present."
          },
          "reason": {
            "type": "string",
            "description": "Public anti-spam verification reason when present."
          },
          "details": {
            "description": "Optional public error details, represented as JSON values.",
            "type": [
              "object",
              "array",
              "string",
              "number",
              "boolean",
              "null"
            ]
          }
        }
      },
      "ProjectInquiry": {
        "type": "object",
        "required": [
          "name",
          "email",
          "summary"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "description": "Name authorized by the person making the inquiry."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Reply address authorized by the person."
          },
          "summary": {
            "type": "string",
            "minLength": 10,
            "description": "Project context. The server stores up to 4,000 characters; do not include sensitive personal data."
          },
          "whatsapp": {
            "type": "string",
            "description": "Optional valid phone number, normalized by the server."
          },
          "company": {
            "type": "string",
            "description": "Optional organization name."
          },
          "service": {
            "type": "string",
            "enum": [
              "marca",
              "design-grafico",
              "tirar-do-papel",
              "evoluir",
              "site-app",
              "outro"
            ],
            "description": "Optional service context; unknown values are stored as outro."
          },
          "deadline": {
            "type": "string",
            "description": "Optional timing context, stored up to 120 characters; does not create a deadline commitment."
          },
          "investment": {
            "type": "string",
            "description": "Optional budget context, stored up to 120 characters; does not create a price or commitment."
          },
          "link": {
            "type": "string",
            "description": "Optional reference URL or text, stored up to 300 characters."
          },
          "website": {
            "type": "string",
            "description": "Anti-spam honeypot. Legitimate clients must leave this empty.",
            "default": ""
          },
          "turnstileToken": {
            "type": "string",
            "description": "Required when GET config says Turnstile is active. A person must complete the challenge in the browser."
          },
          "utm": {
            "type": "object",
            "properties": {
              "utm_source": {
                "type": "string",
                "description": "Campaign attribution, truncated to 120 characters."
              },
              "utm_medium": {
                "type": "string",
                "description": "Campaign attribution, truncated to 120 characters."
              },
              "utm_campaign": {
                "type": "string",
                "description": "Campaign attribution, truncated to 120 characters."
              },
              "utm_content": {
                "type": "string",
                "description": "Campaign attribution, truncated to 120 characters."
              },
              "utm_term": {
                "type": "string",
                "description": "Campaign attribution, truncated to 120 characters."
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    }
  }
}