> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubehosting.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Definir variáveis

> Troque a lista inteira de variáveis de ambiente numa chamada só.

Troca a lista inteira de variáveis do projeto numa chamada só.

<Warning>
  **A lista que você manda substitui a que está guardada.** Variável que ficar de fora é apagada, e valor apagado não volta. Para mudar uma só, mande todas: a que muda com `value` e as outras só com `name`, para manter o valor. Veja os nomes atuais em [Listar variáveis](/api-reference/projects/list-variables).
</Warning>

<CodeGroup>
  ```json Novo TOKEN, mantendo o PREFIX theme={"dark"}
  {
    "variables": [
      { "name": "TOKEN", "value": "token-novo" },
      { "name": "PREFIX" }
    ]
  }
  ```

  ```json Apagar todas theme={"dark"}
  {
    "variables": []
  }
  ```
</CodeGroup>

No primeiro exemplo, `TOKEN` recebe um valor novo, `PREFIX` mantém o valor que já tinha e qualquer outra variável é apagada.

<Tip>
  Se `isRestartRequired` vier `true`, [reinicie](/api-reference/projects/restart) o projeto para ele receber os valores novos.
</Tip>

Veja as regras de nomes e tamanhos em [Variáveis de ambiente](/hosting/environment-variables#regras).


## OpenAPI

````yaml PUT /projects/{id}/variables
openapi: 3.1.0
info:
  title: API da Cube Hosting
  version: 1.0.0
  description: >-
    Hospede bots de Discord, sites e APIs em Node.js e Python: envie o .zip,
    inicie, pare, reinicie, leia logs e métricas e cuide das variáveis de
    ambiente.
  contact:
    name: Cube Hosting
    url: https://discord.gg/pv6D9tUsDV
servers:
  - url: https://app.cubehosting.com.br/api
security:
  - bearerAuth: []
tags:
  - name: Projetos
  - name: Controle
  - name: Logs e métricas
  - name: Variáveis de ambiente
paths:
  /projects/{id}/variables:
    put:
      tags:
        - Variáveis de ambiente
      summary: Definir variáveis
      description: >-
        Troca a lista inteira de variáveis do projeto:


        - `{ "name", "value" }` grava o valor novo.

        - `{ "name" }` sem `value` mantém o valor que já estava guardado (erro
        se a variável não existia).

        - O que não vier na lista é apagado.


        As variáveis chegam ao processo **no próximo início**: se o projeto está
        no ar, `isRestartRequired` vem `true` e é só
        [reiniciar](/api-reference/projects/restart). Até 50 variáveis; nome com
        letras, números e `_`, começando com letra ou `_` (até 64 caracteres);
        valor numa linha só, até 4.096 caracteres; tudo somado até 32 KB.
        `HOME`, `PATH`, o prefixo `CUBE_` e, em sites, `PORT` são reservados.
      operationId: setProjectVariables
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VariablesInput'
            example:
              variables:
                - name: TOKEN
                - name: PREFIX
      responses:
        '200':
          description: Variáveis salvas.
          content:
            application/json:
              schema:
                type: object
                required:
                  - variables
                  - isRestartRequired
                properties:
                  variables:
                    type: array
                    items:
                      $ref: '#/components/schemas/VariableName'
                  isRestartRequired:
                    type: boolean
                    description: >-
                      `true` quando algo mudou e o projeto está no ar: reinicie
                      para aplicar.
              example:
                variables:
                  - name: TOKEN
                  - name: PREFIX
                isRestartRequired: true
        '400':
          description: >-
            A lista está fora das regras. A mensagem diz o problema, nunca o
            valor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: invalid_request
                  value:
                    status: error
                    code: invalid_request
                    message: O nome HOME é reservado pela Cube. Escolha outro.
        '401':
          description: Chave ausente, inválida ou revogada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_api_key:
                  summary: invalid_api_key
                  value:
                    status: error
                    code: invalid_api_key
                    message: >-
                      Chave de API inválida ou revogada. Confira o cabeçalho
                      "Authorization: Bearer <chave>" ou crie outra em Chaves de
                      API no painel.
        '403':
          description: A chave é só de leitura.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_permission:
                  summary: insufficient_permission
                  value:
                    status: error
                    code: insufficient_permission
                    message: >-
                      Esta chave é só de leitura. Para enviar, iniciar, parar,
                      reiniciar ou mexer nas variáveis, crie uma chave de
                      leitura e escrita no painel.
        '404':
          description: O projeto não existe ou não é da sua conta.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  summary: not_found
                  value:
                    status: error
                    code: not_found
                    message: Projeto não encontrado.
        '413':
          description: O corpo do pedido é grande demais.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                payload_too_large:
                  summary: payload_too_large
                  value:
                    status: error
                    code: payload_too_large
                    message: O corpo da requisição é grande demais.
        '415':
          description: >-
            O corpo não veio como JSON. Mande o cabeçalho `Content-Type:
            application/json`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unsupported_media_type:
                  summary: unsupported_media_type
                  value:
                    status: error
                    code: unsupported_media_type
                    message: Envie o corpo em JSON.
        '429':
          description: Limite de pedidos. Traz o cabeçalho `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limit_exceeded:
                  summary: rate_limit_exceeded
                  value:
                    status: error
                    code: rate_limit_exceeded
                    message: >-
                      A sua conta passou do limite da API do plano Free: 10
                      pedidos por minuto. Espere 42 s e tente de novo.
                too_many_attempts:
                  summary: too_many_attempts
                  value:
                    status: error
                    code: too_many_attempts
                    message: Muitas tentativas. Tente de novo em 15 minutos.
        '503':
          description: Não deu para gravar as variáveis agora. Nada foi alterado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                variables_unavailable:
                  summary: variables_unavailable
                  value:
                    status: error
                    code: variables_unavailable
                    message: >-
                      As variáveis de ambiente do projeto não puderam ser
                      abertas agora. Tente de novo em instantes.
      x-codeSamples:
        - lang: bash
          label: curl
          source: >-
            curl -X PUT
            https://app.cubehosting.com.br/api/projects/$PROJECT_ID/variables \
              -H "Authorization: Bearer $CUBE_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"variables":[{"name":"TOKEN","value":"token-novo"},{"name":"PREFIX"}]}'
        - lang: javascript
          label: Node.js
          source: >-
            const API = 'https://app.cubehosting.com.br/api';

            const headers = { Authorization: `Bearer
            ${process.env.CUBE_API_KEY}` };


            const res = await
            fetch(`${API}/projects/${process.env.PROJECT_ID}/variables`, {
              method: 'PUT',
              headers: { ...headers, 'Content-Type': 'application/json' },
              body: JSON.stringify({
                variables: [
                  { name: 'TOKEN', value: process.env.BOT_TOKEN },
                  { name: 'PREFIX' }, // sem value: mantém o valor guardado
                ],
              }),
            });

            console.log(await res.json()); // { variables: [...],
            isRestartRequired: true }
        - lang: python
          label: Python
          source: |-
            import os
            import requests

            API = "https://app.cubehosting.com.br/api"
            headers = {"Authorization": f"Bearer {os.environ['CUBE_API_KEY']}"}

            r = requests.put(
                f"{API}/projects/{os.environ['PROJECT_ID']}/variables",
                headers=headers,
                json={
                    "variables": [
                        {"name": "TOKEN", "value": os.environ["BOT_TOKEN"]},
                        {"name": "PREFIX"},  # sem value: mantém o valor guardado
                    ]
                },
                timeout=30,
            )
            print(r.json())
components:
  parameters:
    ProjectId:
      name: id
      in: path
      required: true
      description: >-
        O ID do projeto (26 caracteres). Aparece no painel, no topo do projeto,
        e em `GET /projects`.
      schema:
        type: string
        pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
        example: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
  schemas:
    VariablesInput:
      type: object
      required:
        - variables
      properties:
        variables:
          type: array
          maxItems: 50
          items:
            type: object
            required:
              - name
            properties:
              name:
                type: string
                pattern: ^[A-Za-z_][A-Za-z0-9_]{0,63}$
                description: Nome da variável.
              value:
                type: string
                maxLength: 4096
                description: >-
                  Valor novo, numa linha só. Sem ele, o valor guardado é
                  mantido.
    VariableName:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: O nome da variável. O valor nunca volta.
    Error:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
          const: error
        code:
          type: string
          description: Código fixo em inglês. Veja [Códigos de erro](/errors).
        message:
          type: string
          description: Texto em português para mostrar a uma pessoa.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Chave de API da Cube (`cube_…`), criada no painel em **Chaves de API**.
        Mande como `Authorization: Bearer cube_…`.

````