API de Artifacts: guia de integração

​

Antes de começar

• Chave de API: envie como token Bearer no header Authorization. Veja Autenticação.
• Workspace: o header x-workspace-id é obrigatório em todas as chamadas. Sem ele, a resposta é 403.
• Permissões: as ações dependem do recurso estar habilitado e do plano e do papel do usuário dono da chave.

​

Conceitos

• Dono: quem cria o Artifact. Somente o dono altera, publica e compartilha. Outras pessoas recebem 404 (não sabem que o Artifact existe) ou 403 ARTIFACT_EDIT_FORBIDDEN (conseguem ler, mas não alterar).
• Versão mais recente (head_version): cada edição ou restauração cria uma nova versão. As edições sempre partem da mais recente.
• Versão compartilhada (shared_version): a versão que quem tem acesso vê. Ela muda quando você publica outra versão, no primeiro compartilhamento (que publica a versão mais recente), quando a versão compartilhada é excluída (passa para a anterior mais recente) e ao despublicar (fica nula). Edições nunca a alteram, o que permite revisar antes de liberar.
• Link (viewer_url): o endereço do Artifact na Tess. Continua o mesmo entre versões e exige login na Tess, inclusive para o acesso público.

​

Fluxo de integração

curl --request POST \
  --url 'https://api.tess.im/artifacts' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'x-workspace-id: YOUR_WORKSPACE_ID' \
  --data '{"title": "Pipeline semanal", "lang": "pt-BR", "content": "<h1>Pipeline semanal</h1><p>Pipeline aberto: R$ 1,2 mi</p>"}'

{ "grant": [{ "type": "team", "team_id": 87 }, { "type": "user", "email": "cfo@empresa.com" }] }

{ "base_version": 1, "operations": [{ "op": "replace", "old": "R$ 1,2 mi", "new": "R$ 1,4 mi" }] }

​

Compartilhamento e governança

• Conceder acesso respeita as restrições do usuário, definidas pelo administrador na página de membros. Por padrão, organização, workspace e equipes estão liberados e o acesso público não.
• Pessoas só podem ser adicionadas se forem membros ativos do workspace ou da organização.
• Uma chamada de compartilhamento é tudo ou nada: se um destino for recusado, nada é gravado e a resposta lista rejected_targets.
• Despublicar Artifact remove todos os acessos de uma vez. Quando um gestor despublica, o dono não consegue publicar de novo.
• As permissões são verificadas a cada abertura: quem sai do workspace ou perde o nível de compartilhamento perde o acesso na hora.
• No plano Enterprise, as alterações feitas pela API (criar, editar, publicar, compartilhar, excluir) também aparecem nos Eventos de Auditoria, com entity_type igual a artifact.

​

Erros

{
  "error_code": "ARTIFACT_STALE",
  "message": "Artifact is at version 4, edit was based on 3."
}

​

Limites

​

Endpoints