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

# Nome e endereço do club

> Renomeia o club e define o subdomínio em que o classroom atende. Com `slug` o endereço é exato; com `name`, derivado.



## OpenAPI

````yaml PATCH /v1/clubs/{clubId}
openapi: 3.0.3
info:
  title: weve API
  description: >
    Contrato entre a API Go e o dashboard. **Este arquivo é a fonte de
    verdade**:

    os tipos e a interface de servidor em Go, e o client TypeScript, são todos

    gerados daqui (`make openapi`). Handler que divergir da interface não
    compila.


    A superfície interna (`/internal/*`) fica de fora de propósito: é acesso de

    máquina, protegido por segredo dedicado, e não é contrato de cliente.
  version: 0.2.0
servers:
  - url: https://api.useweve.com
    description: produção
  - url: http://localhost:8080
    description: desenvolvimento
security: []
tags:
  - name: health
  - name: session
  - name: account
  - name: clubs
  - name: members
  - name: webhooks
  - name: outgoing-webhooks
  - name: sales-platforms
  - name: catalog
  - name: content
  - name: classroom
  - name: community
  - name: mentorships
  - name: agents
  - name: lives
  - name: students
  - name: auth
  - name: campaigns
  - name: workflows
  - name: email
  - name: exports
  - name: certificates
  - name: terms
  - name: mcp
  - name: gamification
  - name: support
  - name: help
paths:
  /v1/clubs/{clubId}:
    parameters:
      - $ref: '#/components/parameters/OrgId'
    patch:
      tags:
        - clubs
      summary: Define o nome e o endereço do club no classroom
      description: |
        Grava o `slug` — o subdomínio em que o classroom deste club atende — e o
        `name`.

        Dois modos, num corpo só. Com `slug`, o endereço é o que veio, validado
        contra o formato de rótulo de DNS e contra os nomes que o produto
        reserva. Com `name`, o endereço é DERIVADO dele. Vindo os dois, `slug`
        vence, e o nome é gravado.

        Mandar só `name` é como se renomeia o club — e o endereço é SEMEADO
        DE NOVO junto, porque ele deriva do nome: o anterior deixa de
        responder. Quem quer o nome novo e o endereço de sempre manda o `slug`
        atual no mesmo corpo. Mandar só `slug` preserva o nome que já estava lá.

        O sufixo aleatório entra em toda sugestão, inclusive quando o nome está
        livre: sem ele o primeiro club a se cadastrar levaria o nome limpo e os
        seguintes ficariam numerados, o que faz do endereço uma corrida. Quem
        quiser o nome sem sufixo edita depois.

        Exige administrar o club (papel `owner` ou `admin`): o endereço é o que
        o club divulga aos alunos, e trocá-lo derruba o anterior.
      operationId: updateOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdate'
      responses:
        '200':
          description: Endereço gravado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - userSession: []
components:
  parameters:
    OrgId:
      name: clubId
      in: path
      required: true
      description: >
        Id público da organização — o mesmo que `GET /v1/me` devolve em

        `organization_id`.


        Na URL o recurso se chama **club**; no contrato e no domínio,
        organization.

        A divergência é deliberada: `clubs` é a palavra do produto, e a URL é o
        que

        as pessoas leem.


        É o identificador do provedor de autenticação, e é assim de propósito:

        o cliente precisa nomear a organização ao pedir o token, e o token é o

        que prova o escopo. Um id só nosso obrigaria a traduzir um no outro

        antes de ter um token — e a tradução exigiria uma chamada escopada, que

        é justamente a que ainda não dá para fazer.


        O uuid interno da organização não aparece no contrato: ele é o que as

        chaves estrangeiras do domínio referenciam, e continua sendo nosso.
      schema:
        type: string
        format: uuid
  schemas:
    OrganizationUpdate:
      type: object
      description: |
        Ao menos um campo. `slug` define o endereço exatamente; `name`
        renomeia o club e, na falta de `slug`, é a semente de um endereço
        derivado. A marca (`logo_media_id`, `favicon_media_id`,
        `login_image_media_id`), a cor (`accent_color`) e o suporte
        (`support_email`, `support_phone`) e o tema (`theme`,
        `member_theme_choice`) valem sozinhos e não tocam o endereço. Nulo
        tira; ausente mantém.
      properties:
        logo_media_id:
          description: A marca do club, da biblioteca de mídia. Nulo tira a marca.
          type: string
          format: uuid
          nullable: true
        favicon_media_id:
          description: |
            O ícone da aba do navegador no classroom — uma imagem da
            biblioteca, de preferência quadrada. Nulo volta ao ícone padrão.
          type: string
          format: uuid
          nullable: true
        login_image_media_id:
          description: |
            A imagem das telas de entrada do classroom — uma imagem da
            biblioteca. Nulo deixa a tela só com o formulário.
          type: string
          format: uuid
          nullable: true
        support_email:
          description: O e-mail de suporte ao aluno. Nulo (ou em branco) tira o contato.
          type: string
          maxLength: 254
          nullable: true
        theme:
          $ref: '#/components/schemas/ClassroomTheme'
        member_theme_choice:
          type: boolean
          description: Libera (ou tira) a troca de tema pelo aluno.
        support_phone:
          description: >
            O telefone de suporte ao aluno, escrito como o club quiser
            mostrá-lo:

            dígitos, espaço, `+`, `-`, `(` e `)`. Nulo (ou em branco) tira o

            contato.
          type: string
          maxLength: 32
          nullable: true
        accent_color:
          description: |
            A cor do club no classroom, em hex de seis dígitos. Nulo volta à
            cor do classroom. Como a marca, vale sozinha no corpo.
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          nullable: true
        slug:
          type: string
          minLength: 1
          maxLength: 63
          description: |
            Rótulo de DNS: minúscula, dígito e hífen, sem hífen nas pontas.
            Nomes que o produto reserva são recusados com o mesmo código de um
            slug mal formado — dizer qual é reservado entregaria a lista.
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: |
            O nome do club. Sem `slug` no corpo, é dele que o endereço
            derivado sai — renomear sozinho troca o endereço junto.
    OrganizationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Organization'
    ClassroomTheme:
      type: string
      enum:
        - light
        - dark
      description: |
        O tema base da área do aluno — o que vale para quem não escolheu outro
        (ou para todos, sem `member_theme_choice`).
    Organization:
      type: object
      description: |
        O escopo do domínio: o club. Tudo que o produto cria pertence a um.
      required:
        - id
        - name
        - theme
        - member_theme_choice
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Id do club — o que vai no `{clubId}` das rotas escopadas.
        name:
          type: string
          description: >-
            Como o club se chama. É o que as telas mostram, inclusive as
            anônimas do classroom.
        logo:
          $ref: '#/components/schemas/Media'
          description: A marca do club, da biblioteca de mídia.
        favicon:
          $ref: '#/components/schemas/Media'
          description: O ícone da aba do navegador no classroom, da biblioteca de mídia.
        login_image:
          $ref: '#/components/schemas/Media'
          description: >-
            A imagem que veste as telas de entrada do classroom, da biblioteca
            de mídia.
        support_email:
          type: string
          description: >-
            Para onde o aluno escreve pedindo ajuda. Ausente, o classroom não
            oferece e-mail.
        support_phone:
          type: string
          description: >-
            O telefone de suporte, como o club o escreveu. Ausente, o classroom
            não oferece telefone.
        theme:
          $ref: '#/components/schemas/ClassroomTheme'
        member_theme_choice:
          type: boolean
          description: |
            O aluno pode trocar o tema em Preferências. Desligado, todo mundo
            vê o `theme` do club.
        slug:
          type: string
          description: >
            O subdomínio em que o classroom deste club atende
            (`<slug>.weve.club`).


            Todo club criado por `POST /v1/clubs` nasce com um, derivado do

            nome. Ausente só em club antigo que nunca o definiu — e club sem

            `slug` não tem classroom.
        accent_color:
          $ref: '#/components/schemas/AccentColor'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorEnvelope:
      type: object
      description: >-
        Envelope único de erro da API. O `code` é o contrato com o cliente — a
        `message` é diagnóstico, e pode mudar.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
            message:
              type: string
    Media:
      type: object
      required:
        - id
        - kind
        - title
        - provider
        - status
        - visibility
        - archived
        - created_at
      properties:
        id:
          type: string
          format: uuid
        kind:
          $ref: '#/components/schemas/MediaKind'
        title:
          type: string
        file_name:
          type: string
        mime:
          type: string
        size_bytes:
          type: integer
          format: int64
        provider:
          $ref: '#/components/schemas/MediaProvider'
        external_id:
          description: |
            O id no provedor de FORA (o vídeo do YouTube, a URL colada). Para o
            que hospedamos, o id não vai na resposta: o que a tela precisa é o
            `preview_url` assinado.
          type: string
        status:
          $ref: '#/components/schemas/MediaStatus'
        visibility:
          $ref: '#/components/schemas/MediaVisibility'
        error:
          type: string
        duration_seconds:
          type: integer
        width:
          type: integer
        height:
          type: integer
        preview_url:
          description: |
            Endereço assinado e de prazo curto, para a tela do admin ver o que é
            este arquivo. Não é guardado em lugar nenhum — expira.
          type: string
        thumbnail_url:
          description: A miniatura, assinada pelo mesmo prazo curto.
          type: string
        folder_id:
          type: string
          format: uuid
        archived:
          type: boolean
        created_at:
          type: string
          format: date-time
        type:
          $ref: '#/components/schemas/MediaScreenType'
        download_url:
          description: |
            Endereço assinado e de prazo curto do arquivo — o `preview_url` abre
            na aba. No arquivo hospedado, baixa com o nome original; no vídeo
            hospedado, é o MP4 em 720p. Referência de fora não tem download.
          type: string
        expires_at:
          description: |
            A gravação de live ou de encontro sem a Hospedagem de vídeo sai
            nesta data — baixe antes (`download_url`) ou contrate a Hospedagem,
            e ela fica. Ausente é mídia que não vence.
          type: string
          format: date-time
        favorite:
          description: |
            Se QUEM PEDE favoritou. Vem na lista, na leitura de uma e nas
            edições da biblioteca; ausente nas outras respostas.
          type: boolean
        usage_count:
          description: |
            Em quantos lugares a mídia é usada — o "usado em 3 lugares" da tela.
            A lista é `GET /media/{mediaId}/usage`. Vem na lista, na leitura de
            uma e nas edições da biblioteca.
          type: integer
    AccentColor:
      type: string
      pattern: ^#[0-9a-fA-F]{6}$
      description: |
        A cor do club no classroom (botões e progresso), em hex de seis
        dígitos. Gravada em minúscula. Ausente, o classroom usa a dele.
      example: '#1d63d1'
    MediaKind:
      description: Rótulo de tela — o ícone e o filtro. Nada de acesso lê isto.
      type: string
      enum:
        - video
        - audio
        - image
        - document
    MediaProvider:
      description: |
        Onde o bit mora. `bunny_stream` é o vídeo que hospedamos e `r2` o
        arquivo; `youtube`, `vimeo` e `external` são referências a algo de fora,
        que a biblioteca guarda para a aula ter um caminho só. `safevideo` é o
        vídeo guardado no SafeVideo, que a extensão de mesmo nome traz: o
        player é o deles, e a entrega ao aluno sai com a marca d'água dele.
      type: string
      enum:
        - bunny_stream
        - r2
        - youtube
        - vimeo
        - external
        - safevideo
    MediaStatus:
      description: |
        `uploading` enquanto o arquivo não chegou, `processing` enquanto o
        provedor transcodifica, `ready` quando dá para entregar, `failed`
        quando o provedor desistiu (e aí `error` diz por quê).
      type: string
      enum:
        - uploading
        - processing
        - ready
        - failed
    MediaVisibility:
      description: |
        `private` é o padrão, e continua sendo depois de qualquer dúvida:
        publicar é escolha explícita.

        A diferença é de BUCKET, não de um sinalizador na hora de entregar —
        objeto privado não tem endereço público, então nenhum erro de código
        consegue publicá-lo. Privado é entregue por endereço assinado e de
        prazo curto; público, por um endereço estável que o CDN cacheia.

        Público existe para o que precisa ser visto por quem ainda não comprou
        e sobreviver a um cache: a capa do curso na vitrine, a marca do club, o
        trailer. Uma URL assinada não serve para isso — ela muda a cada
        resposta, então o CDN nunca acerta, a prévia de link do WhatsApp busca
        a imagem dias depois e a capa dentro de um e-mail vence.
      type: string
      enum:
        - private
        - public
    MediaScreenType:
      description: |
        O tipo como a TELA o mostra: o `kind`, com `document` separado em `pdf`
        e `file` (o zip, a planilha, o resto), e `embed` para a referência de
        fora (`youtube`, `vimeo`, `external`), qualquer que seja o `kind`. É
        derivado do provedor, do `kind`, do tipo do arquivo e da extensão, e é
        o mesmo que o filtro `types` usa.
      type: string
      enum:
        - video
        - image
        - audio
        - pdf
        - file
        - embed
  responses:
    BadRequest:
      description: Requisição malformada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Unauthorized:
      description: Sessão ausente, expirada ou revogada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >
        A sessão é válida, mas não age nesta organização. É a mesma resposta
        para

        uma organização que não existe — distinguir as duas deixaria enumerar

        organizações alheias.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Conflict:
      description: >-
        Conflito com o estado atual. O `code` diz qual; a descrição da operação
        lista os possíveis.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    UnprocessableEntity:
      description: Campos obrigatórios ausentes ou inválidos
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: >-
        Falha inesperada. O corpo nunca traz o erro real — ele fica no log e no
        rastreamento.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    userSession:
      type: http
      scheme: bearer
      description: |
        Token OPACO de sessão de quem administra, emitido por
        `/v1/auth/admin/sign-in` e verificado contra a nossa tabela — o mesmo
        desenho do `studentSession`, para a outra identidade.

        É o esquema de quem ADMINISTRA — o dashboard. O aluno do classroom usa o
        `studentSession`; uma rota consumida pelos dois declara os dois
        esquemas, e o middleware aceita qualquer um deles. As duas credenciais
        são opacas e chegam pelo mesmo cabeçalho: quem as separa é a tabela em
        que cada uma existe.

        O dashboard o guarda em cookie httpOnly, que o BFF troca pelo
        `Authorization` a cada chamada.

````