Documentação da API da Xikota Design

Esta é a documentação da API (API documentation) da Xikota Design. O contrato OpenAPI descreve a configuração pública do formulário e o envio autorizado de uma solicitação de projeto. Para conhecer o studio e escolher o caminho de contato, comece pelas instruções para agentes.

Leitura em Markdown

A home, Sobre, Contato, Privacidade e esta documentação aceitam Accept: text/markdown. A resposta usa Content-Type: text/markdown e Vary: Accept. Para navegar pelo site, peça Accept: text/html. As preferências de qualidade do cabeçalho Accept são respeitadas; tipos incompatíveis nestas páginas recebem 406.

curl -H 'Accept: text/markdown' https://xikota.design/
curl -i 'https://xikota.design/api/v1/iniciar?locale=pt-BR'

Configuração e solicitação de projeto

GET /api/v1/iniciar retorna a configuração pública do desafio anti-spam. A resposta padrão mantém o formato {"turnstile":null}, ou um objeto com a chave pública quando o desafio está ativo. O parâmetro opcional locale=pt-BR ou locale=en acrescenta orientação nesse idioma, informa se a pessoa precisa concluir o desafio e aponta o formulário e o contato. Um idioma inválido ou repetido recebe erro JSON 400. Não exige login.

POST /api/v1/iniciar envia uma solicitação real: cria um contato e uma oportunidade no studio e pode disparar email de confirmação. Só envie depois que a pessoa revisar e autorizar seus dados. A alternativa é abrir o formulário no navegador.

O POST recebe JSON com name (pelo menos dois caracteres), email válido e summary (pelo menos dez caracteres). Campos opcionais e respostas estão no OpenAPI. O cabeçalho Origin: https://xikota.design é obrigatório. Quando o desafio está ativo, um turnstileToken válido também é obrigatório; encaminhe a pessoa ao formulário para concluir o desafio.

Erros e limites reais

A leitura da configuração permite 120 consultas por IP em 60 segundos. O envio mantém os limites de seis tentativas por IP em dez minutos e cinco por email em uma hora. Os contadores de leitura e envio são separados. As URLs com e sem /v1 compartilham os mesmos contadores: trocar de endereço ou idioma não reinicia o limite.

Na hospedagem Cloudflare, o IP informado pela borda identifica o cliente. O sistema armazena um identificador derivado desse IP com SHA-256 e atualiza o contador de forma atômica. Requisições inválidas de leitura também consomem o orçamento. Os dados e a retenção estão descritos na privacidade.

As respostas após a checagem de limite incluem RateLimit-Policy e RateLimit, conforme o Internet-Draft IETF de RateLimit. Uma resposta 429 inclui Retry-After em segundos. Aguarde esse prazo e não repita envios em paralelo. Erros são JSON, com o código estável no campo error, uma message e uma orientação em resolution.

RateLimit-Policy: "inquiry-read";q=120;w=60
RateLimit: "inquiry-read";r=119;t=60
API-Version: 1

Versionamento e descontinuação

A URL canônica da versão atual é /api/v1/iniciar. O cabeçalho API-Version: 1 identifica essa versão maior. O endereço anterior, /api/iniciar, continua como alias compatível, inclusive para o formulário existente. As duas URLs executam os mesmos handlers, validações e proteções.

Correções e adições compatíveis permanecem na v1. Uma mudança incompatível recebe nova versão maior e nova URL, com migração documentada. O contrato OpenAPI publica as operações da versão atual com identificadores estáveis, parâmetros tipados e respostas descritas.

Não há descontinuação ou data de remoção anunciada para a v1 nem para o alias anterior. Se uma descontinuação for decidida, esta página explicará a migração e a API sinalizará a decisão com Deprecation e um link de documentação, conforme a RFC 9745. Sunset, conforme a RFC 8594, será usado somente quando houver uma data real de encerramento. Esses cabeçalhos não são enviados hoje.

CLI oficial da Xikota Design

O CLI ajuda a descobrir os recursos, ler o OpenAPI, consultar a configuração e preparar o contexto de um projeto. O código fica no repositório oficial. O pacote oficial está publicado no npm e também está disponível para download direto.

Execute a versão fixada pelo npm ou instale o comando:

npx --yes xikota-design-cli@0.1.2 --help
npm install --global xikota-design-cli@0.1.2
xikota-design --help

Para instalar pelo Homebrew:

brew tap thiagoxikota/xikota
brew install thiagoxikota/xikota/xikota-design
xikota-design --help
xikota-design config --locale en
xikota-design inquiry template
xikota-design inquiry validate --file brief.json
xikota-design inquiry prepare --file brief.json

Também é possível executar o pacote com Node.js 20.9 ou posterior:

npx --yes --package=https://xikota.design/cli/xikota-design-cli-0.1.2.tgz xikota-design --help

inquiry prepare consulta a configuração e valida os dados localmente. Ele não envia o POST nem guarda um token de desafio. A pessoa revisa o contexto e conclui o envio pelo formulário. A área administrativa e os links de propostas mantêm sua autenticação.