API — Organizações

Endpoints para gerenciar organizações, membros e convites.

Base path: /api/v1

Todos os endpoints requerem Authorization: Bearer {token}.

---

POST /organizations

Cria uma nova organização. O usuário autenticado torna-se owner.

Body

{
  "name": "Acme Corp",
  "slug": "acme-corp"
}

Response 201

{
  "id": "01J8X...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logo_url": null,
  "plan": "free",
  "created_at": "2026-04-18T12:00:00Z"
}

Exemplo

curl -X POST https://tasks.cloudface.tech/api/v1/organizations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

---

GET /organizations

Lista todas as organizações das quais o usuário autenticado é membro.

Response 200

{
  "organizations": [
    {
      "id": "01J8X...",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "logo_url": null,
      "role": "owner",
      "plan": "professional"
    }
  ]
}

---

GET /organizations/:slug

Retorna os detalhes de uma organização.

Response 200

{
  "id": "01J8X...",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logo_url": "https://...",
  "plan": "professional",
  "limits": {
    "members": 25,
    "members_used": 8,
    "projects": 20,
    "projects_used": 5,
    "issues": 10000,
    "issues_used": 423,
    "storage_bytes": 5368709120,
    "storage_used_bytes": 234567890
  },
  "created_at": "2026-01-01T00:00:00Z"
}

---

PATCH /organizations/:slug

Atualiza as configurações de uma organização. Requer papel admin ou owner.

Body (todos os campos são opcionais)

{
  "name": "Acme Corporation",
  "slug": "acme-corporation"
}

Response 200 — organização atualizada

WARNING

Alterar o slug invalida todas as URLs que usam o slug antigo.

---

DELETE /organizations/:slug

Deleta permanentemente a organização e todos os seus dados. Requer papel owner.

Response 204 — sem body

---

GET /organizations/:slug/members

Lista os membros da organização.

Query params

Param	Tipo	Descrição
page	integer	Página (padrão: 1)
per_page	integer	Itens por página (padrão: 50, máx: 100)

Response 200

{
  "members": [
    {
      "id": "01J8X...",
      "user_id": "01J8X...",
      "name": "Gabriel Mowses",
      "email": "gabriel@exemplo.com",
      "role": "owner",
      "joined_at": "2026-01-01T00:00:00Z"
    }
  ],
  "total": 8,
  "page": 1,
  "per_page": 50
}

---

POST /organizations/:slug/invite

Cria e envia um convite para um novo membro. Requer papel admin ou owner.

Body

{
  "email": "novo@membro.com",
  "role": "member"
}

Papéis válidos: member, admin, billing

Response 201

{
  "id": "01J8X...",
  "email": "novo@membro.com",
  "role": "member",
  "token": "aB3xK7mP9qRs...",
  "expires_at": "2026-04-25T12:00:00Z"
}

---

PATCH /organizations/:slug/members/:user_id

Altera o papel de um membro. Requer admin ou owner.

Body

{
  "role": "admin"
}

Response 200 — membro atualizado

---

DELETE /organizations/:slug/members/:user_id

Remove um membro da organização. Requer admin ou owner.

Response 204 — sem body

---

POST /invites/:token/accept

Aceita um convite. Requer autenticação. O usuário autenticado é adicionado à organização com o papel definido no convite.

Response 200

{
  "organization": {
    "id": "01J8X...",
    "name": "Acme Corp",
    "slug": "acme-corp"
  },
  "role": "member"
}

Erros

Status	Motivo
404	Token não encontrado
410	Convite expirado
409	Usuário já é membro