Criar uma função
Um nome e uma lista de permissões. O que volta é mais longo do que o que enviou.
Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.
POST /roles
Um nome e uma lista de permissões. O que volta é mais longo do que o que enviou.
Exemplo
Requer roles:write. Devolve 201. Uma função personalizada tem builtin: null, editable: true e deletable: true, e não pertence a ninguém até alguém ser movido para ela.
curl -X POST "$OE/roles" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": ["emails:send", "threads:write", "labels:write", "contacts:read"] }'{ "object": "role", "id": "role_2b81de079c1f0a4b7e05d386", "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": [ "emails:send", "emails:read", "threads:read", "threads:write", "labels:read", "labels:write", "contacts:read" ], "builtin": null, "editable": true, "deletable": true, "members": 0, "apiKeys": 0, "createdAt": "2026-08-30T10:41:02.000Z", "updatedAt": "2026-08-30T10:41:02.000Z"}Entraram quatro permissões e voltaram sete. emails:send implica emails:read, threads:write implica threads:read, labels:write implica labels:read. Uma função que pode arquivar uma conversa que não pode abrir é uma caixa que alguém se esqueceu de marcar e não uma política que alguém queira, por isso a implicação é guardada em vez de recusada. A lista volta também por ordem canónica, que é o que permite a um cliente comparar duas funções como JSON e decidir se o botão Guardar fica ativo.
Uma permissão desconhecida É recusada aqui em vez de descartada: templates:writ é invalid_parameter, um 422, nomeando a string. O serviço normaliza em silêncio porque é também o caminho de pré-criação e o caminho MCP, onde falhar uma função inteira por causa de uma palavra não reconhecida seria pior. Numa chamada que alguém fez deliberadamente, está errado. Um 200 com uma função que não pode editar modelos não lhes disse nada, e vão passar a tarde às voltas com isso.
Um nome duplicado no mesmo espaço de trabalho é role_name_taken, um 409. A 25.ª função personalizada é role_limit_reached, um 422. Protege o tamanho que uma matriz pode atingir antes de ninguém a auditar, e não é uma fronteira de plano.
Criar uma função não a dá a ninguém. Mover pessoas para ela é PATCH /members/{userId}, e apontar uma chave para ela faz-se onde a chave é emitida.