Conceitos da API

Mapa de conceitos para quem integra a API da Axuz, com hierarquia de domínio, ids, teamId no path, multi-tenant, hosts por serviço, versão /v1 e o que é público ou interno.

Antes de chamar a API, vale entender como o domínio da Axuz é organizado e como as rotas refletem essa organização.

Hierarquia de domínio

company → team (workspace) → project (opcional) → channel | timeline | board de tarefas | wiki | file

Conceito	O que é	Observação para integradores
company	Organização que agrupa teams	papéis de company têm precedência sobre os de team
team (workspace)	Unidade de tenancy; quase toda rota começa em `/teams/{teamId}/...`	é o limite de isolamento dos dados
project	Camada opcional entre team e conteúdo	recursos aceitam `project_id` nulo (“sem projeto”)
channel	Container de conversa, tarefas, arquivos e wiki de um projeto/equipe	na UI chama-se Channel; no banco e em alguns nomes de campo é `timeline`
timeline	Feed social do workspace (posts ricos)	na API, `feeds` e `feed_posts`; não confunda com o channel
board	Quadro de tarefas (Kanban, lista, Gantt, calendário sobre o mesmo dado)	ids de board aparecem em `/teams/{teamId}/boards/{id}`

Identificadores

Ids de recurso são UUID. Os parâmetros de path ({teamId}, {id}, {shareId}…) são validados como UUID e um valor malformado costuma resultar em 400. Datas são timestamptz em RFC 3339. Listagens grandes usam paginação por cursor (nunca OFFSET). E-mail e telefone não são identificadores de usuário; use sempre o id.

teamId no path e multi-tenant

A API é multi-tenant sobre um banco compartilhado. Toda tabela de domínio carrega team_id e toda consulta é escopada por ele. Consequências práticas:

o teamId vem do path e é conferido contra a sua membership; nunca é aceito do corpo da requisição;
ser membro de outro team não dá acesso: o recurso responde 404, não 403, para não confirmar a existência do id;
a ordem de checagem é: sessão (401) → membership (403) → recurso (404) → papel/escopo (403) → validação (400/422);
dentro do team, o acesso é resolvido do mais estreito para o mais amplo: papel de company, papel de team, escopo de project e escopo de channel.

Hosts por serviço

Cada serviço tem seu host: https://<subdomínio>.<domínio>, onde o domínio é axuz.net (staging) ou axuz.club (produção). Os servidores da especificação usam esse padrão (https://api.{domain}, etc.).

Host da API	Serviço	Interface de produto correspondente
`api`	Backend principal: workspace, tarefas, busca, notificações, integrações	`workspace`, `hub`, `app`
`auth-api`	Login, registro, sessões, OAuth	`auth` (login), `admin`, `backoffice`
`api-workspace`	Tarefas, notas, feeds, timelines, wiki, board público	`workspace`
`api-billing`	Assinaturas, faturas, contas a pagar/receber	`financer`
`api-calendar`	Eventos, recorrência, convites	`calendar`
`api-flow`	Fluxogramas, versões, compartilhamento	`flow`
`api-forms`	Formulários e respostas	`forms`
`files-api`	Arquivos e links de compartilhamento	`drive`
`mail-api`	E-mail (SMTP/IMAP)	`mail`
`meet-api`	Salas de reunião	`meet`
`messaging-api`	Web Push e entrega de mensagens	(sem UI própria)

Cada operação da referência indica o servidor correto; chamar o host errado resulta em 404. As rotas de um mesmo recurso podem viver em hosts diferentes durante a extração gradual de serviços: sempre use o servidor listado na operação.

Versões e /v1

A especificação documenta os paths sem prefixo. Os serviços workspace, forms e flow também montam as mesmas rotas sob /v1 (espelho), e há rotas explicitamente em /v1 no backend principal, como /v1/integration-scopes. Não há ainda política publicada de versões paralelas (v2); mudanças incompatíveis serão anunciadas em Releases. Prefira o path como está na referência.

Autenticação, em uma linha

Sessão (cookie HTTP-only ou Authorization: Bearer), token pessoal axp_, token de integração axz_bot_ e OAuth 2.1. Detalhes em Autenticação. Cada operação da referência tem uma classe de acesso: public, public-signed (token na URL), authenticated, team-member, team-admin, permission e scope.

O que é público e o que é interno

Pública: tudo o que está na referência. É o contrato que mantemos.
Rotas /platform/* (operação da plataforma, backoffice) não são API pública: exigem papéis de plataforma e não estão na especificação.
Rotas /internal/* servem a comunicação entre serviços (autenticadas por chave interna) e não são API pública; podem mudar ou sumir sem aviso. Não as chame.
Rotas sem login existem de propósito (links públicos, formulários, salas de visitante). Veja Área pública e assignees externos.

Erros e formato

Os serviços respondem erro em JSON {"error": "<mensagem>"}; alguns acrescentam campos (fields em validação, retry_after em 429). Espere 429 com Retry-After nas rotas com limite de taxa e respeite-o.

Atualizado em 2026-10-22