> ## 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.

# Mudar as configurações

> Mude o nome, o comando, a memória, a versão e o resto das configurações.

Muda as configurações do projeto, como a aba **Configurações** do painel.

Permissão da chave: `projects:settings` ([Chaves de API](/api-keys)).

## Erros comuns

| Código | HTTP | O que fazer |
| - | - | - |
| [`insufficient_scope`](/errors#param-insufficient-scope) | 403 | A chave não tem a permissão da rota (`requiredScope` diz qual): marque em Chaves de API › Editar permissões. |
| [`invalid_request`](/errors#param-invalid-request) | 400 | Confira o corpo ou os parâmetros do pedido. |
| [`project_busy`](/errors#param-project-busy) | 409 | Espere o envio ou a instalação em curso terminar. |
| [`subdomain_taken`](/errors#param-subdomain-taken) | 409 | Escolha outro subdomínio. |
| [`invalid_config`](/errors#param-invalid-config) | 422 | Confira o campo em `field`: a regra é a do `cube.json` e a do plano. |

Todos os códigos, com o formato do erro, em [Códigos de erro](/errors).


## OpenAPI

````yaml PATCH /projects/{id}
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, veja a análise das visitas dos
    sites, cuide das variáveis de ambiente, faça e baixe backups, volte para uma
    versão anterior, crie bancos de dados (PostgreSQL, MySQL, MongoDB e Redis),
    guarde arquivos privados no Blob, use um domínio seu nos sites e veja o uso
    do plano. Para agentes de IA, o servidor MCP da conta (`POST
    https://app.cubehosting.com.br/api/mcp`, JSON-RPC, com a mesma chave) está
    em https://docs.cubehosting.com.br/account-mcp.
  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: Análise
  - name: Variáveis de ambiente
  - name: Arquivos
  - name: Backups
  - name: Versões dos envios
  - name: Bancos de dados
  - name: Blob
  - name: Domínios
  - name: Templates
  - name: Avisos
  - name: Conta
paths:
  /projects/{id}:
    patch:
      tags:
        - Projetos
      summary: Mudar as configurações
      description: >-
        Muda qualquer parte das Configurações do projeto: `name`, `description`,
        `type`, `language`, `entry`, `command`, `installCommand`, `version`,
        `root`, `memoryMb`, `subdomain`, `port` e `systemPackages`, com as
        mesmas regras do [`cube.json`](/cube-json) e do plano. Nome e descrição
        valem na hora; o resto, no próximo início (`isRestartRequired`).


        **Permissão da chave:** `projects:settings` (Projetos · configurar).
        Veja [Chaves de API](/api-keys).
      operationId: updateProject
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              properties:
                name:
                  type: string
                  maxLength: 40
                description:
                  type: string
                  maxLength: 200
                type:
                  type: string
                  enum:
                    - bot
                    - site
                language:
                  type: string
                entry:
                  type: string
                command:
                  type: string
                installCommand:
                  type:
                    - string
                    - 'null'
                version:
                  type: string
                root:
                  type: string
                memoryMb:
                  type: integer
                subdomain:
                  type: string
                port:
                  type: integer
                systemPackages:
                  type: array
                  items:
                    type: string
                    enum:
                      - build-essential
                      - curl
                      - fonts-dejavu-core
                      - fonts-liberation
                      - fonts-noto-cjk
                      - fonts-noto-color-emoji
                      - ghostscript
                      - git
                      - graphviz
                      - imagemagick
                      - libvips-tools
                      - poppler-utils
                      - python3
                      - sqlite3
                      - tesseract-ocr
                      - tesseract-ocr-por
                      - unzip
                      - zip
            example:
              memoryMb: 512
              command: node dist/index.js
      responses:
        '200':
          description: Salvo.
          content:
            application/json:
              schema:
                type: object
                required:
                  - project
                  - isRestartRequired
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
                  isRestartRequired:
                    type: boolean
              example:
                project:
                  id: 01J8Z3W6N0Q4Y7V2K5T9D1H3XA
                  name: Meu bot
                  description: Atende o servidor da loja
                  type: bot
                  language: node
                  version: '24'
                  entry: index.js
                  command: node dist/index.js
                  installCommand: null
                  root: null
                  systemPackages: []
                  memoryMb: 512
                  port: null
                  subdomain: null
                  url: null
                  internalHost: cube-t9d1h3xa
                  status: running
                  error: null
                  hasAutoRestart: true
                  consecutiveCrashes: 0
                  lastExit: null
                  usage:
                    memoryMb: 83
                    cpuPercent: 1.2
                    networkInBps: 1200
                    networkOutBps: 300
                  startedAt: '2026-09-26T18:01:05.000Z'
                  templateId: null
                  restoredFromBackupId: null
                  createdAt: '2026-09-26T18:00:00.000Z'
                  updatedAt: '2026-09-26T18:01:10.000Z'
                isRestartRequired: true
        '400':
          description: Campo fora do formato, ou nenhum campo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_request:
                  summary: invalid_request
                  value:
                    status: error
                    code: invalid_request
                    message: >-
                      Envie o que quer mudar: nome, descrição, publicação na web
                      (tipo), linguagem, arquivo principal, comando de início,
                      comando de instalação, versão, pasta servida, memória,
                      subdomínio, porta ou pacotes do sistema.
        '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 não tem a permissão.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_scope:
                  summary: insufficient_scope
                  value:
                    status: error
                    code: insufficient_scope
                    message: >-
                      Esta chave não tem a permissão Projetos · configurar.
                      Marque a permissão na chave em Chaves de API no painel, ou
                      use outra chave.
                    requiredScope: projects:settings
        '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.
        '409':
          description: O projeto está ocupado, ou o subdomínio é de outro.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                project_busy:
                  summary: project_busy
                  value:
                    status: error
                    code: project_busy
                    message: >-
                      O projeto está sendo preparado ou já tem outra ação em
                      andamento. Espere terminar.
                subdomain_taken:
                  summary: subdomain_taken
                  value:
                    status: error
                    code: subdomain_taken
                    message: Este subdomínio já está em uso. Escolha outro.
                    field: subdomain
        '422':
          description: A configuração não vale no plano ou na linguagem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_config:
                  summary: invalid_config
                  value:
                    status: error
                    code: invalid_config
                    message: A memória mínima de um bot nos planos pagos é 256 MB.
                    field: memoryMb
        '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: O servidor dos projetos não respondeu a tempo. Nada foi alterado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                server_unavailable:
                  summary: server_unavailable
                  value:
                    status: error
                    code: server_unavailable
                    message: >-
                      O servidor dos projetos não respondeu. Tente de novo em
                      instantes.
      security:
        - bearerAuth:
            - projects:settings
      x-codeSamples:
        - lang: bash
          label: curl
          source: >-
            curl -X PATCH
            "https://app.cubehosting.com.br/api/projects/$PROJECT_ID" \
              -H "Authorization: Bearer $CUBE_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"memoryMb": 512, "command": "node dist/index.js"}'
        - 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}`,
            {
              method: 'PATCH',
              headers: { ...headers, 'Content-Type': 'application/json' },
              body: JSON.stringify({"memoryMb": 512, "command": "node dist/index.js"}),
            });

            console.log(await res.json());
        - 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.patch(
                f"{API}/projects/{os.environ['PROJECT_ID']}",
                headers=headers,
                json={"memoryMb": 512, "command": "node dist/index.js"},
                timeout=60,
            )
            r.raise_for_status()
            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:
    Project:
      type: object
      description: 'Um projeto: um bot ou um site.'
      required:
        - id
        - name
        - description
        - type
        - language
        - version
        - entry
        - command
        - installCommand
        - root
        - systemPackages
        - memoryMb
        - port
        - subdomain
        - url
        - internalHost
        - status
        - error
        - hasAutoRestart
        - consecutiveCrashes
        - lastExit
        - usage
        - startedAt
        - templateId
        - restoredFromBackupId
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: ID do projeto, 26 caracteres.
        name:
          type: string
          maxLength: 40
          description: Nome do projeto.
        description:
          type: string
          maxLength: 200
          description: Descrição do painel. `""` quando não tem.
        type:
          type: string
          enum:
            - bot
            - site
        language:
          type: string
          enum:
            - node
            - python
            - java
            - go
            - php
            - ruby
            - dotnet
            - elixir
            - static
          description: >-
            `java` roda um `.jar` pronto ([Hospedar Java](/hosting/java)), `go`
            é compilado a cada envio ([Hospedar Go](/hosting/go)), `php` e
            `ruby` instalam o `composer.json` e o `Gemfile` ([Hospedar
            PHP](/hosting/php), [Hospedar Ruby](/hosting/ruby)), `dotnet`
            publica o projeto a cada envio ([Hospedar .NET](/hosting/dotnet)),
            `elixir` compila o projeto do `mix.exs` a cada envio ([Hospedar
            Elixir](/hosting/elixir)) e `static` é o [site só de
            HTML](/hosting/static-site), servido pela Cube.
        version:
          type: string
          description: >-
            `20`, `22`, `24` ou `26` (Node.js); `3.11`, `3.12`, `3.13` ou `3.14`
            (Python); `21` ou `25` (Java); `1.26` ou `1.27` (Go); `8.4` ou `8.5`
            (PHP); `3.4` ou `4.0` (Ruby); `10` (.NET); `1.20` (Elixir); `""` no
            `static`.
        entry:
          type:
            - string
            - 'null'
          description: >-
            Arquivo principal: o arquivo que o comando roda, relativo à raiz do
            projeto (como `index.js`, `src/index.ts`, `src/bot.py`, `bot.jar`,
            `bot.php`, `bot.rb`, `Bot.csproj`, `app.dll` ou `mix.exs`). Vem do
            `command` quando ele é só `node <arquivo>`, `tsx <arquivo>`
            (TypeScript direto), `python <arquivo>`, `java -jar <arquivo>`, `php
            <arquivo>`, `ruby <arquivo>`, `dotnet <arquivo>.dll` ou `mix run
            --no-halt <arquivo>`, e muda em Configurações › Geral. No `go`, é o
            main cuja pasta o build compila (`null` = a raiz); no `dotnet`, o
            projeto que o build publica ou o `.dll` pronto. `null` com um
            comando próprio, como `npm start`.
        command:
          type: string
          description: >-
            Comando de início, o que de fato roda. Quando é `node <entry>`, `tsx
            <entry>`, `python <entry>` ou `java -jar <entry>` (ou, no `go`,
            `/dados/bin/app`, o programa do build; no site `php`,
            `cube-php-server`, o servidor da Cube; no `dotnet`, `dotnet
            /dados/publish/<projeto do entry>.dll` ou, no `.dll` pronto, `dotnet
            <entry>`; no `elixir`, `mix run --no-halt`), o painel mostra o campo
            vazio (vazio = roda o arquivo principal). `""` no `static`.
        installCommand:
          type:
            - string
            - 'null'
          description: >-
            O comando de instalação do projeto: `null` = a instalação automática
            da linguagem (`npm ci` ou `npm install`, `pip install -r
            requirements.txt`…); `""` = não instala nada; texto = o comando que
            roda no lugar da automática. Muda em Configurações › Geral, no
            Comando personalizado. `null` no `static`.
        root:
          type:
            - string
            - 'null'
          description: >-
            Só `static`: a pasta servida, relativa à raiz do projeto (`""` = a
            raiz). `null` nas outras linguagens.
        systemPackages:
          type: array
          items:
            type: string
            enum:
              - build-essential
              - curl
              - fonts-dejavu-core
              - fonts-liberation
              - fonts-noto-cjk
              - fonts-noto-color-emoji
              - ghostscript
              - git
              - graphviz
              - imagemagick
              - libvips-tools
              - poppler-utils
              - python3
              - sqlite3
              - tesseract-ocr
              - tesseract-ocr-por
              - unzip
              - zip
          description: >-
            Os [pacotes do sistema](/cube-json#pacotes-do-sistema) do projeto,
            na ordem da lista. `[]` sem nenhum (e sempre no `static`). Mudam em
            Configurações › Geral e valem no próximo início.
        memoryMb:
          type: integer
          description: Memória reservada, em MB. É também o teto do processo.
        port:
          type:
            - integer
            - 'null'
          description: >-
            Só site: a porta em que o app escuta (também na variável `PORT`).
            `null` em bot.
        subdomain:
          type:
            - string
            - 'null'
          description: 'Só site: o nome em `nome.cubehost.dev`. `null` em bot.'
        url:
          type:
            - string
            - 'null'
          format: uri
          description: 'Só site: o endereço público com HTTPS. `null` em bot.'
        internalHost:
          type: string
          pattern: ^cube-[0-9a-z]{8}$
          description: >-
            O **nome interno**: `cube-` e os 8 últimos caracteres do `id`, em
            minúsculas, fixo. Os outros projetos **da sua conta** chegam neste
            por ele, em qualquer porta em que ele escute, com ele no ar (como
            `http://cube-t9d1h3xa:2333` para o [Lavalink](/hosting/lavalink)).
            Outra conta não resolve o nome nem chega no projeto; não é um
            endereço público.
        status:
          $ref: '#/components/schemas/ProjectStatus'
        error:
          oneOf:
            - $ref: '#/components/schemas/ProjectError'
            - type: 'null'
          description: O motivo, quando `status` é `error` ou `crash_loop`.
        hasAutoRestart:
          type: boolean
          description: '`true` nos planos pagos: o projeto volta sozinho se cair.'
        consecutiveCrashes:
          type: integer
          description: >-
            Quedas seguidas desde a última vez que rodou 60 segundos sem cair.
            Com 5, o projeto vai para `crash_loop`.
        lastExit:
          oneOf:
            - $ref: '#/components/schemas/LastExit'
            - type: 'null'
          description: A última vez que o processo terminou.
        usage:
          oneOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
          description: O uso de agora. Só com `status` `running`.
        startedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Quando o processo subiu (o "tempo no ar" do painel). Só com
            `running`.
        templateId:
          type:
            - string
            - 'null'
          description: >-
            O [template](/hosting/templates) de onde o projeto nasceu, como
            `discord-js-bot`. `null` num `.zip` ou pelo GitHub, e volta a `null`
            quando o código é trocado por outro `.zip` ou pelo GitHub. Enquanto
            está preenchido, o projeto só inicia com as variáveis obrigatórias
            do template (`missing_variables`).
        restoredFromBackupId:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            O backup de onde o projeto nasceu pelo [Restaurar como
            novo](/api-reference/backups/restore-as-new). `null` nos outros.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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
    ProjectStatus:
      type: string
      enum:
        - creating
        - installing
        - running
        - stopped
        - restarting
        - crash_loop
        - error
      description: >-
        `creating` (Enviando), `installing` (Instalando), `running` (No ar),
        `stopped` (Parado), `restarting` (Reiniciando), `crash_loop` (Em loop de
        erro), `error` (Com erro).
    ProjectError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - install_failed
            - install_timeout
            - install_out_of_memory
            - install_interrupted
            - start_failed
            - system_packages_failed
            - process_exited
            - crash_loop
          description: >-
            Veja [Estados de erro do
            projeto](/errors#estados-de-erro-do-projeto).
        message:
          type: string
          description: Explicação em português.
    LastExit:
      type: object
      required:
        - code
        - isOutOfMemory
        - exitedAt
      properties:
        code:
          type: integer
          description: O código de saída do processo.
        isOutOfMemory:
          type: boolean
          description: '`true` se o processo passou da memória do projeto.'
        exitedAt:
          type: string
          format: date-time
    Usage:
      type: object
      required:
        - memoryMb
        - cpuPercent
        - networkInBps
        - networkOutBps
      properties:
        memoryMb:
          type: integer
          description: Memória em uso, em MB.
        cpuPercent:
          type: number
          description: Uso de processador. 100 = um núcleo inteiro.
        networkInBps:
          type: integer
          description: Rede recebida, em bytes por segundo.
        networkOutBps:
          type: integer
          description: Rede enviada, em bytes por segundo.
  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_…`. Cada rota pede uma permissão
        da chave (o escopo no `security` da rota, como `files:write`); sem ela,
        `403 insufficient_scope` com o `requiredScope`. Veja [Chaves de
        API](/api-keys).

````