# Documentação (/docs) Em docs.fazer.ai, você encontra guias de uso, instruções de instalação e a referência da API dos produtos da fazer.ai. Hoje, a documentação cobre o fazer.ai projects. ## Produtos [#produtos] Organize projetos e tarefas para times de pessoas e agentes de IA. O produto oferece uma API REST e um servidor MCP. A documentação de outros produtos da fazer.ai também entra nesta página com o tempo. ## Para agentes de IA [#para-agentes-de-ia] Você pode indicar ao seu agente onde encontrar uma página, fornecer a documentação inteira ou passar só a página relevante para a tarefa. - [`/llms.txt`](/llms.txt) lista todas as páginas da documentação e inclui um link para a versão em Markdown de cada uma. - [`/llms-full.txt`](/llms-full.txt) reúne toda a documentação em um único arquivo. - Acrescente `.md` ao fim do endereço de qualquer página para obter seu conteúdo em Markdown. Por exemplo, use [`/docs/projects.md`](/docs/projects.md). ## Ajuda [#ajuda] Se você faz parte da [comunidade Lucas Moreira](https://lucasmoreira.ai/?utm_source=docs-fazer-ai&utm_medium=docs&utm_campaign=projects), tire por lá as suas dúvidas sobre o produto e conte os problemas que encontrar. # Agentes e MCP (/docs/projects/guias/agentes-e-mcp) O MCP é um protocolo que permite que um agente de IA use ferramentas externas. Ao conectar um agente ao fazer.ai projects, você pode pedir que ele leia e altere projetos, tarefas, comentários, anexos, lembretes, revisões e notificações. As operações seguem as mesmas regras da interface do produto. ## Agentes [#agentes] Um agente é um tipo de usuário que sempre pertence a uma pessoa. Você já tem um agente padrão com o nome `Agente de `. Em **Configurações** → **Agentes**, você pode criar outros, até o limite de 10 agentes por pessoa. Você pode usar um para o Claude Code no notebook e outro para uma automação no n8n, por exemplo. O agente vê exatamente o que o dono vê. Quando ele cria algo ou publica um comentário, a ação aparece em nome do agente. A interface também mostra quem é o dono, então quem lê um comentário pode identificar qual agente escreveu e a quem ele pertence. ## O endereço do servidor [#o-endereço-do-servidor] O servidor MCP do fazer.ai projects usa o transporte Streamable HTTP e fica neste endereço. ```text https://projects.fazer.ai/api/mcp ``` Use o login no navegador, via OAuth, quando estiver no computador e puder aprovar a conexão. Esse fluxo autentica o cliente sem guardar uma chave de API nele. Use uma chave de API do agente para scripts, automações, chamadas com `claude -p` ou servidores que rodam sem navegador. ## Claude Code [#claude-code] ### Com login no navegador [#com-login-no-navegador] Rode este comando para cadastrar o servidor `projects` no Claude Code. ```bash claude mcp add --transport http -s user projects https://projects.fazer.ai/api/mcp ``` A opção `-s user` deixa o servidor disponível em qualquer pasta. Sem essa opção, ele fica disponível só na pasta em que você rodou o comando. No Claude Code, rode `/mcp` e selecione `projects`. O navegador abre o fazer.ai projects. Entre na sua conta se precisar. Na tela **Conectar ...**, escolha a organização e selecione o agente em **Agir como**. Confira o que ele poderá fazer e clique em **Aprovar**. ### Com uma chave de API [#com-uma-chave-de-api] Rode os comandos abaixo no terminal em que você vai abrir o Claude Code. A primeira linha pede a chave sem mostrá-la na tela nem registrá-la no histórico do shell. Cole a chave e pressione Enter. Depois de registrar o servidor, abra o Claude Code nesse terminal para que ele receba `PROJECTS_TOKEN`. Se já estiver aberto, feche e abra de novo a partir do shell em que você exportou a variável. ```bash read -rs PROJECTS_TOKEN && export PROJECTS_TOKEN claude mcp add --transport http -s user projects https://projects.fazer.ai/api/mcp \ --header 'Authorization: Bearer ${PROJECTS_TOKEN}' ``` Mantenha as aspas simples no valor de `--header`. Elas fazem o Claude Code guardar o texto `${PROJECTS_TOKEN}` e ler a variável a cada conexão. Com aspas duplas, o shell substitui a variável pela chave antes de passar o valor ao Claude Code. Nesse caso, a chave fica em texto puro no arquivo `~/.claude.json`. ## Codex [#codex] ### Com login no navegador [#com-login-no-navegador-1] Use os comandos abaixo para cadastrar o servidor no Codex e, quando precisar, refazer o login. ```bash codex mcp add projects --url https://projects.fazer.ai/api/mcp codex mcp login projects ``` O primeiro comando registra `projects` e já abre o login no navegador. Use `codex mcp login projects` se a janela não abrir ou se você precisar entrar novamente. Na tela de aprovação, escolha a organização e o agente em **Agir como**, confira o que ele poderá fazer e clique em **Aprovar**. ### Com uma chave de API [#com-uma-chave-de-api-1] No terminal, rode os comandos abaixo, cole a chave quando a primeira linha pedir e pressione Enter. ```bash read -rs PROJECTS_TOKEN && export PROJECTS_TOKEN codex mcp add projects --url https://projects.fazer.ai/api/mcp --bearer-token-env-var PROJECTS_TOKEN ``` O Codex grava só o nome da variável em `~/.codex/config.toml` e lê a chave do ambiente a cada uso. ```toml title="~/.codex/config.toml" [mcp_servers.projects] url = "https://projects.fazer.ai/api/mcp" bearer_token_env_var = "PROJECTS_TOKEN" ``` ## Outros agentes compatíveis com MCP [#outros-agentes-compatíveis-com-mcp] No Cursor, no Windsurf, no VS Code, no n8n ou em outro cliente que fale MCP por HTTP, configure o endereço do servidor e escolha a autenticação. Se o cliente aceitar OAuth, ele descobre onde iniciar o login na resposta HTTP 401 do primeiro acesso e se registra automaticamente. Em um cliente sem OAuth, envie a chave no cabeçalho `Authorization: Bearer `. Vários clientes usam um arquivo de configuração com este formato. ```json { "mcpServers": { "projects": { "type": "http", "url": "https://projects.fazer.ai/api/mcp", "headers": { "Authorization": "Bearer ${PROJECTS_TOKEN}" } } } } ``` Se o cliente não expandir `${PROJECTS_TOKEN}`, escreva a chave no lugar da variável e mantenha o arquivo fora do Git e de pastas sincronizadas. ## Conferir a conexão [#conferir-a-conexão] No Codex, `codex mcp list` mostra o servidor com **Bearer token** quando você configura a autenticação por chave. Para testar a conexão em qualquer cliente, peça ao agente “chame o whoami do projects”. A resposta traz o handle do agente, o dono, a organização, os escopos e a data de hoje no fuso configurado. Se a chamada devolver esses dados, a conexão está funcionando. ## Chaves de API [#chaves-de-api] Abra **Configurações** → **Agentes**, selecione o agente que vai usar a conexão e clique em **Criar chave**. Escolha os escopos conforme as ações que ele precisa executar e defina uma expiração se quiser. Para um agente que consulta e atualiza informações no dia a dia, selecione `read` e `write`. - `read` permite ver tarefas, projetos e pessoas. - `write` permite criar e alterar. - `admin` permite agir como administrador. Só o dono ou um admin da organização pode usar esse escopo. Uma chave com `admin` expira em até 7 dias. A chave começa com `fzp_` e aparece uma única vez, na hora da criação. Guarde o valor em um gerenciador de senhas e use o valor guardado ali para exportar `PROJECTS_TOKEN`. A criação e a revogação de chaves, inclusive da própria chave em uso, só podem ser feitas pela interface. ## Desconectar e revogar [#desconectar-e-revogar] Abra **Configurações** → **Agentes**. Em **Apps conectados**, você encontra os clientes que entraram pelo navegador e pode usar **Desconectar** para encerrar o acesso de um deles. Para interromper na hora todas as conexões que usam uma chave, clique em **Revogar** ao lado dela. A revogação é definitiva. Desativar o agente interrompe o acesso por todas as chaves dele e desconecta seus apps. ## O que o agente pode fazer [#o-que-o-agente-pode-fazer] Você pode pedir ao agente que consulte as informações do projeto e faça alterações dentro das permissões do dono e dos escopos da conexão. Toda operação de escrita aceita uma chave de idempotência. Se o cliente repetir a mesma chamada com a mesma chave de idempotência, o servidor devolve o resultado da primeira chamada sem gravar a alteração de novo. Apagar uma tarefa ou um anexo, arquivar, juntar ou apagar um projeto e apagar uma label ou um workflow exigem confirmação explícita. O cliente deve perguntar antes de enviar essa confirmação. Uma tarefa apagada vai para a lixeira e pode ser restaurada por 30 dias. Para um anexo apagado, o prazo é de 7 dias. Apagar de vez da lixeira, juntar projetos e apagar um projeto são ações irreversíveis. ## Problemas comuns [#problemas-comuns] - **Erro HTTP 401.** A chave pode ter expirado ou sido revogada, ou o agente pode estar desativado. Confira também se `PROJECTS_TOKEN` estava definida quando o cliente abriu. Se você exportou a variável depois, feche o cliente e abra de novo a partir do shell que tem a variável. - **Erro `forbidden`.** A chave não tem o escopo que a ação exige. Uma tentativa de escrita com uma chave que tem só `read`, por exemplo, precisa de uma chave com `write`. - **Erro `request_budget_exceeded` ou HTTP 429.** Os agentes de uma mesma pessoa passaram de 500 chamadas por minuto, somando API e MCP. A resposta indica quantos segundos esperar antes de tentar novamente. - **O login abre, mas a tela de aprovação não mostra nenhum agente.** Crie um em **Configurações** → **Agentes** ou use **Novo agente** na própria tela de aprovação. - **Você quer conectar uma instância no seu servidor.** Quando a versão self-host estiver disponível, substitua `https://projects.fazer.ai` pelo endereço da sua instância em todos os comandos. # API REST e chaves (/docs/projects/guias/api-e-chaves) Use a API REST do fazer.ai projects para integrar scripts, fluxos do n8n ou seu próprio back-end por HTTP. A API usa JSON e fica em `https://projects.fazer.ai/api/v1`. Ela cobre as operações da tela com tarefas, projetos, comentários, labels, status, lembretes, revisões, anexos e notificações. As mesmas regras valem na tela, na API e no MCP. Toda chamada à API é feita por um agente. Ele tem acesso ao que a pessoa dona do agente pode ver, e as alterações ficam registradas em nome do agente. ## A chave [#a-chave] Em **Configurações**, abra **Agentes** e escolha o agente que vai usar a API. Você também pode criar um agente para a integração, por exemplo, `n8n`. Clique em **Criar chave**, selecione os escopos e, se quiser, defina uma data de expiração. A chave pertence ao agente e começa com `fzp_`. Ela aparece uma única vez, quando você a cria. Guarde o valor em um gerenciador de senhas. - `read` permite consultar tarefas, projetos e pessoas. - `write` permite criar e alterar dados. - `admin` está disponível apenas para quem é dono ou admin da organização. Uma chave com esse escopo expira em no máximo 7 dias. A criação, a listagem e a revogação de chaves são feitas apenas pela tela. Isso vale também para a própria chave que autentica uma integração. Para cortar o acesso de uma chave, volte a **Configurações**, abra **Agentes** e clique em **Revogar** na chave. A revogação tem efeito imediato. ## Autenticação [#autenticação] Envie a chave no cabeçalho `Authorization: Bearer ` e use `GET /api/v1/me` para testar o acesso. ```bash curl https://projects.fazer.ai/api/v1/me \ -H "Authorization: Bearer $PROJECTS_TOKEN" ``` A resposta identifica o agente associado à chave. Os IDs nas respostas da API vêm como texto. Se a chave estiver revogada, expirada ou for inexistente, a API retorna `401` com o mesmo corpo de erro nos três casos. Se a chave for válida e faltar o escopo exigido pela operação, o retorno é `403`. As respostas de erro seguem o formato `{ "error": "mensagem" }`. ## Limites [#limites] Cada chave de API tem um limite de 600 requisições por minuto. No SaaS, também se aplica um limite de 500 requisições por minuto por pessoa. Esse total soma o tráfego de todas as chaves de API e conexões MCP dos agentes que pertencem à pessoa. Se você exceder um dos limites, a API responde `429`. O cabeçalho `Retry-After` indica quantos segundos esperar para tentar de novo. No limite por pessoa, o corpo da resposta também informa esse intervalo em `retryAfterSeconds`. ## Escritas idempotentes [#escritas-idempotentes] Inclua o cabeçalho `Idempotency-Key` em uma escrita que você pode precisar repetir. Se um timeout ou uma queda de rede impedir que você receba a resposta, envie a mesma requisição com o mesmo valor no cabeçalho. O valor deve ter de 1 a 128 caracteres e vale por 24 horas. Cada chave de API tem seu próprio espaço de chaves de idempotência. No exemplo, `dueAt` usa `amanhã`. A API interpreta `hoje`, `amanhã`, `today` e `tomorrow` no calendário de quem chama. Ela também aceita um instante ISO com fuso ou uma data no formato `YYYY-MM-DD` para um dia inteiro. ```bash IDEMPOTENCY_KEY=$(uuidgen) # guarde para repetir a mesma escrita curl https://projects.fazer.ai/api/v1/tasks \ -H "Authorization: Bearer $PROJECTS_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $IDEMPOTENCY_KEY" \ -d '{"title": "Enviar o relatório", "dueAt": "amanhã"}' ``` | Caso | Resposta | | --- | --- | | Primeira chamada com essa chave de idempotência | Resposta normal da operação. | | Mesma chave, mesmo método, caminho e corpo | Resposta da primeira chamada, com `Idempotent-Replayed: true`, sem gravar de novo. | | Mesma chave, requisição diferente | `422`. | | Mesma chave, primeira chamada ainda em execução | `409`. | ## Sincronizar com /changes [#sincronizar-com-changes] Para manter uma integração sincronizada sem consultar periodicamente cada lista, leia o feed de `/changes`. Ele reúne as mudanças que o agente tem permissão para ver. Passe o cursor em `since` e use `since=0` para ler desde o começo. O parâmetro `limit` define quantas mudanças pedir por página. O padrão é 100 e o máximo é 500. Para acompanhar um tipo de entidade, passe `entityType` com um valor como `TASK` ou `PROJECT`. ```bash curl "https://projects.fazer.ai/api/v1/changes?since=0&limit=100" \ -H "Authorization: Bearer $PROJECTS_TOKEN" ``` Guarde o `nextCursor` de toda resposta, inclusive de uma página vazia, e envie esse valor em `since` na próxima chamada. Uma página vazia pode avançar o cursor, quando houve mudanças que o agente não pode ver, e nunca o leva de volta ao zero. O feed só inclui mudanças feitas há pelo menos 2 segundos, para evitar que alguma fique para trás quando o cursor avança. Por isso, uma alteração aparece no feed alguns segundos depois de acontecer. ## Referência completa [#referência-completa] Abra **Referência da API** no menu desta documentação para consultar os detalhes da operação que você quer chamar. Cada operação tem uma página com os parâmetros que aceita e as respostas que pode retornar. # Recorrência, lembretes e revisões (/docs/projects/guias/recorrencia-e-lembretes) No fazer.ai projects, você pode fazer uma tarefa se repetir, receber um lembrete perto do prazo e pedir que outra pessoa revise o trabalho antes de concluir. Essas funções ficam no painel da tarefa. Se você trabalha com um agente, ele também pode configurar recorrências, gerenciar lembretes e encaminhar revisões pelo MCP ou pela API. ## Tarefas que se repetem [#tarefas-que-se-repetem] Abra o painel da tarefa, vá à seção **Recorrência** e clique em **Repetir**. Digite a frequência no campo **Regra**. A tela mostra as próximas datas antes de você salvar, então você pode conferir se elas caem nos dias esperados. O campo aceita regras em maiúsculas ou minúsculas. Para remover a regra, clique em **Parar de repetir**. | Regra | O que faz | | --- | --- | | `daily` | Repete a tarefa todos os dias. | | `weekly` | Repete a tarefa toda semana, no dia da semana em que cai a data da tarefa. | | `weekly:sex` | Repete a tarefa toda sexta-feira. Você pode escrever o dia em português ou inglês, com ou sem acento. Para sexta-feira, use `sex`, `sexta`, `fri` ou `friday`. | | `monthly` | Repete a tarefa todo mês, no dia do mês em que cai a data da tarefa. Se um mês não tiver esse dia, a repetição pula para o próximo mês que tiver. | | `monthly:10` | Repete a tarefa no dia 10 de cada mês. Se você usar um número negativo, a contagem começa no fim do mês. | | `monthly-last` | Repete a tarefa no último dia de cada mês, seja dia 28, 29, 30 ou 31. | | `yearly` | Repete a tarefa todo ano. | | `every:3d`, `every:2w` | Repete a tarefa a cada 3 dias ou a cada 2 semanas, respectivamente. | | RRULE do iCalendar | Define calendários como a última sexta-feira de cada mês. Para esse caso, use `FREQ=MONTHLY;BYDAY=-1FR`. | Acrescente `!` ao fim da regra para contar o próximo intervalo a partir do dia em que você concluir a tarefa. Use `every:30d!`, por exemplo, para marcar a próxima troca de filtro 30 dias depois da troca que você acabou de registrar. O sufixo funciona apenas em intervalos simples, como `daily!` e `every:30d!`. Regras que fixam um dia, como `weekly:sex!` ou `monthly:10!`, não aceitam o sufixo. ## Concluir uma tarefa recorrente [#concluir-uma-tarefa-recorrente] Ao concluir uma ocorrência, a tarefa avança para a próxima data e continua aberta. No histórico da tarefa, você pode consultar cada ocorrência concluída e ver quem concluiu e quando. Se você definiu um número de ocorrências ou uma data final na RRULE, a tarefa fecha quando você conclui a última ocorrência. Se você precisar adiar ou antecipar a tarefa uma vez, mude a data da ocorrência. A mudança vale só para aquela vez. A regra continua igual e a ocorrência seguinte volta ao calendário definido por ela. Se você concluiu a tarefa por engano, clique em **Reabrir** para desfazer a última conclusão e recuperar a data anterior. ## Lembretes [#lembretes] Na seção **Lembretes** do painel da tarefa, clique em **Adicionar lembrete**. Você pode configurar o aviso para si ou para outra pessoa que tenha acesso à tarefa. O lembrete chega como notificação no app. Quem ativou as notificações push em **Configurações**, na seção **Notificações**, também recebe o aviso no navegador. - **Em uma data e hora.** Escolha quando o aviso deve chegar. Esse lembrete dispara uma vez, no momento escolhido. - **Relativo ao prazo ou à data de início.** Escolha a data de referência e o intervalo, como uma hora antes do prazo. O lembrete dispara a cada ocorrência. Em uma tarefa recorrente, ele acompanha a próxima data quando a tarefa avança. Você pode configurar até 20 lembretes por tarefa. Um lembrete relativo pode ficar até um ano antes ou depois da data de referência. O painel mostra quando cada lembrete dispara e avisa se ele não puder disparar, por exemplo, quando a tarefa está fechada, está sem prazo ou o horário previsto já passou. ## Pedir uma revisão [#pedir-uma-revisão] Quando terminar o trabalho e precisar da aprovação de alguém, clique em **Pedir revisão** no painel da tarefa. Selecione a pessoa em **Quem revisa** e, em **Ao aprovar**, escolha **Concluir a tarefa** ou **Devolver para mim**. Enquanto espera, a tarefa continua aberta, sai do seu **Hoje** e aparece para quem revisa. Na página **Revisões**, você encontra os pedidos em **Esperando por mim** e **Esperando pelos outros**. Se a pessoa aprovar, a tarefa é concluída ou volta para você, conforme a opção escolhida. Se clicar em **Pedir ajustes**, o pedido vira um comentário na tarefa e ela volta para você. Em uma tarefa recorrente, a revisão vale para aquela ocorrência. Quando a aprovação conclui a ocorrência, a tarefa avança para a próxima data. Enquanto a revisão está pendente, quem revisa recebe um lembrete a cada 2 dias úteis. Quem pediu a revisão recebe um aviso depois de 5 dias úteis. Para esses avisos, os dias úteis vão de segunda a sexta, a partir das 9h no fuso horário de cada pessoa. Se você fez o pedido, pode clicar em **Cobrar** para enviar outro aviso a quem revisa, uma vez por dia. # Introdução (/docs/projects) O fazer.ai projects é um sistema de projetos e tarefas para times em que pessoas e agentes de IA trabalham juntos. Você pode organizar projetos em uma árvore de subprojetos e definir datas, responsáveis e labels nas tarefas. Nas tarefas, você também pode comentar, anexar arquivos, configurar recorrência e lembretes e pedir revisão. ## Pessoas e agentes no mesmo lugar [#pessoas-e-agentes-no-mesmo-lugar] Cada pessoa já tem um agente padrão quando cria a conta. O agente é um usuário do sistema, com nome e handle próprios. Ele pode ser responsável por tarefas, receber menções com `@` e comentar. Todo agente tem uma pessoa como dona e vê exatamente o que ela vê. O que o agente escreve sai assinado pelo próprio agente. Você pode acessar o mesmo sistema pela tela no navegador, pela API REST ou pelo servidor MCP. A interface do navegador também pode ser instalada como app. Agentes como Claude Code e Codex podem se conectar pelo MCP. ## Onde usar [#onde-usar] Hoje, o fazer.ai projects está disponível como SaaS. Crie sua conta com Google ou com e-mail e senha em [projects.fazer.ai](https://projects.fazer.ai). Sua conta começa com uma organização própria, da qual você é dono. Você pode convidar outras pessoas por e-mail. Uma versão Pro para instalar no seu servidor e uma versão Free de código aberto estão previstas. As duas versões seguem sem data de lançamento. A seção [Self-host](/docs/projects/self-host), marcada como em breve, descreve como a instalação vai funcionar. ## Planos [#planos] O SaaS tem dois planos, Pro da comunidade e Free. Qualquer pessoa pode usar o Free. Você pode usar o benefício em uma organização da qual é dono. Ele vale para uma organização por vez. [Conheça a comunidade Lucas Moreira](https://lucasmoreira.ai/?utm_source=docs-fazer-ai&utm_medium=docs&utm_campaign=projects). | Limite | Pro da comunidade | Free | | --- | --- | --- | | Membros por organização | 5 | 2 | | Espaço para anexos por organização | 50 GB | 1 GB | | Tamanho por arquivo | 100 MB | 100 MB | | Agentes por pessoa | 10 | 10 | | Chamadas dos agentes de uma pessoa por minuto (API e MCP somados) | 500 | 500 | Para ativar o Pro, vá a **Configurações**, entre em **Organização** e abra **Gerenciar plano**. Escolha **Usar o meu Pro da comunidade**. O sistema reconhece o benefício pelo mesmo e-mail que você usa na comunidade Lucas Moreira. ## Como esta seção está organizada [#como-esta-seção-está-organizada] Crie sua conta e comece a trabalhar com projetos e tarefas. Entenda como os agentes trabalham no sistema e como se conectam pelo MCP. Veja como acessar o sistema pela API REST. Veja como funcionará a instalação no seu servidor. # Primeiros passos (/docs/projects/primeiros-passos) Crie sua conta no fazer.ai projects e adicione uma tarefa ao projeto Pessoal. Quando precisar compartilhar tarefas com o time, crie um projeto, escolha quem pode acessá-lo e convide as pessoas por e-mail. ## Criar a conta [#criar-a-conta] Acesse [projects.fazer.ai](https://projects.fazer.ai) e entre com sua conta do Google ou com e-mail e senha. Se você se cadastrar por e-mail, use o código de 6 dígitos que chegar à sua caixa de entrada para confirmar o endereço. Ao criar a conta, você se torna dono de uma nova organização. Se quiser usar a verificação em duas etapas, abra **Configurações** e vá até **Segurança**. Configure um app autenticador e guarde os códigos de recuperação. Nessa mesma seção, você também pode configurar uma chave de acesso (passkey) para entrar sem senha. ## O projeto Pessoal e o primeiro projeto [#o-projeto-pessoal-e-o-primeiro-projeto] Cada pessoa tem um projeto **Pessoal**, que só ela pode ver. Se você criar uma tarefa sem escolher um projeto, ela fica no seu projeto **Pessoal**. Ao criar seu primeiro projeto, escolha quem pode acessá-lo. Um projeto público fica visível para toda a organização. Se for privado, o acesso fica limitado ao dono e aos membros escolhidos. Um subprojeto pode herdar o acesso do projeto ao qual pertence ou ficar restrito às pessoas escolhidas para ele. ## Tarefas [#tarefas] Dê um título à tarefa e acrescente as informações que você precisa para acompanhar o trabalho. Uma tarefa pode ter os seguintes campos e recursos. - **Título** para identificar a tarefa. - **Descrição em Markdown**. Use `@handle` para mencionar alguém e `#número` para citar outra tarefa. - **Data de início e prazo**. Cada um pode ser de dia inteiro ou ter um horário. - **Responsáveis**, que podem ser pessoas ou agentes. - **Labels** e **status**. - **Comentários** e **anexos**. - **Recorrência** e **lembretes**. Veja como configurar os dois no guia de [recorrência e lembretes](/docs/projects/guias/recorrencia-e-lembretes). Para concluir uma tarefa, marque a caixa ao lado dela. Para reabrir a tarefa, desmarque a caixa. Se você apagar uma tarefa, ela vai para a **Lixeira**, de onde pode ser restaurada por 30 dias. ## Hoje, próximos dias e as suas tarefas [#hoje-próximos-dias-e-as-suas-tarefas] Use o menu lateral para acompanhar suas tarefas, seus pedidos de revisão e as tarefas que foram apagadas. - **Hoje** reúne suas tarefas que começam ou vencem até hoje, incluindo as atrasadas, e as que estão em andamento. - **Próximos 7 dias** mostra as tarefas dos próximos sete dias. - **Minhas tarefas** mostra as tarefas abertas pelas quais você é responsável e as que você criou e estão abertas sem responsável. - **Revisões** reúne os pedidos de revisão que envolvem você e os que você fez. - **Lixeira** reúne as tarefas apagadas. Em qualquer quadro de tarefas, você pode escolher entre os layouts **Lista**, **Kanban** e **Gantt**. ## Convidar o time [#convidar-o-time] Em **Configurações**, abra **Organização** e envie o convite por e-mail. A pessoa tem 7 dias para aceitar. O limite é de 2 membros no Free e 5 no Pro da comunidade Lucas Moreira. Confira os detalhes na seção de [planos](/docs/projects#planos). ## Atalhos de teclado [#atalhos-de-teclado] | Tecla | O que faz | | --- | --- | | `n` | Abre uma nova tarefa. | | `/` | Coloca o foco na busca. | | `c` | Conclui ou reabre a tarefa da linha em foco. | | `Ctrl+B` ou `Cmd+B` no Mac | Recolhe ou abre o menu lateral. | Os atalhos funcionam quando o foco está fora de um campo de texto. ## Próximo passo [#próximo-passo] Para conectar o Claude Code, o Codex ou outro agente compatível com MCP ao fazer.ai projects, siga o guia de [Agentes e MCP](/docs/projects/guias/agentes-e-mcp). # Instalar com Docker Compose (/docs/projects/self-host/docker-compose) O lançamento da versão instalável ainda está pendente. Hoje você pode usar o fazer.ai projects em [projects.fazer.ai](https://projects.fazer.ai). O endereço da imagem e a tag usados neste exemplo são os atuais e podem mudar no lançamento. Com este Compose, você sobe o fazer.ai projects e o PostgreSQL no mesmo servidor. Configure o proxy reverso com HTTPS à parte. Você pode usar Caddy, Traefik ou nginx para receber as conexões externas e encaminhá-las para `127.0.0.1:3000`. ## Antes de começar [#antes-de-começar] - Tenha um servidor com Docker e Docker Compose. - Separe o domínio que você vai usar no endereço público da instalação. - Tenha o `openssl` disponível para gerar os segredos. - Para configurar a primeira conta pelo `/setup`, tenha um cliente OAuth do Google. Para criar a conta pelo terminal e definir a senha por e-mail, configure o e-mail transacional. Veja os requisitos e as opções de configuração na [visão geral do self-host](/docs/projects/self-host). ## O compose [#o-compose] Salve o arquivo do Compose em uma pasta no servidor. O Compose lê o `.env` dessa pasta e exige todas as variáveis obrigatórias para iniciar os serviços. ```yaml title="compose.yaml" services: app: image: git.fazer.ai/fazer-ai/projects:v1.15.0 restart: unless-stopped depends_on: postgres: condition: service_healthy environment: NODE_ENV: production PORT: "3000" PUBLIC_URL: ${PUBLIC_URL:?defina PUBLIC_URL no .env} CORS_ORIGIN: ${CORS_ORIGIN:?defina CORS_ORIGIN no .env} DATABASE_URL: postgres://projects:${POSTGRES_PASSWORD:?defina POSTGRES_PASSWORD no .env}@postgres:5432/projects JWT_SECRET: ${JWT_SECRET:?defina JWT_SECRET no .env} ENCRYPTION_KEY: ${ENCRYPTION_KEY:?defina ENCRYPTION_KEY no .env} GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-} GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-} SIGNUP_ENABLED: ${SIGNUP_ENABLED:-false} ports: - "127.0.0.1:3000:3000" healthcheck: test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000/api/health/ready || exit 1"] interval: 10s timeout: 5s retries: 5 start_period: 30s postgres: image: postgres:18-alpine restart: unless-stopped environment: POSTGRES_DB: projects POSTGRES_USER: projects POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?defina POSTGRES_PASSWORD no .env} volumes: - postgres:/var/lib/postgresql healthcheck: test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U projects -d projects"] interval: 10s timeout: 5s retries: 10 volumes: postgres: ``` O serviço `postgres` usa a imagem `postgres:18-alpine`, cria o banco e o usuário `projects` e guarda os dados no volume `postgres`. O serviço `app` usa a imagem `git.fazer.ai/fazer-ai/projects:v1.15.0`, publica a porta `3000` apenas em `127.0.0.1` e espera o banco ficar saudável para iniciar. O healthcheck consulta `/api/health/ready`, que retorna HTTP 200 apenas quando o banco responde. Use esse endpoint para verificar se o app está pronto durante uma atualização. ## As variáveis [#as-variáveis] Crie o `.env` na pasta do Compose com o comando abaixo. Para usar o login com Google, crie um cliente OAuth do tipo “Aplicativo da Web” no Google Cloud e adicione o endereço de `PUBLIC_URL` às origens JavaScript autorizadas. ```bash cat > .env < projects-$(date +%F).dump ``` Troque a tag da imagem do `app` por uma tag de versão no formato `vX.Y.Z`, nunca `latest`, que muda a versão sem ninguém decidir. Depois baixe a imagem e suba o serviço para que o novo contêiner aplique as migrações. ```bash # em compose.yaml, troque a tag: image: git.fazer.ai/fazer-ai/projects:vX.Y.Z docker compose pull app docker compose up -d ``` Confira a versão em `/api/health`. Para voltar à versão anterior, recoloque a tag antiga e suba o serviço de novo. O banco mantém as migrações aplicadas pela versão nova. Se elas deixarem o banco incompatível com a versão anterior, restaure o backup feito antes da atualização. A restauração descarta os dados gravados depois do backup. # Tutorial: self-host na Hostinger (/docs/projects/self-host/hostinger) A versão para instalar no próprio servidor ainda não foi lançada. Hoje o fazer.ai projects existe como SaaS em [projects.fazer.ai](https://projects.fazer.ai). Este tutorial vai mostrar a instalação completa numa VPS da Hostinger, do servidor ao primeiro agente. A base dele é a página [Instalar com Docker Compose](/docs/projects/self-host/docker-compose), que já traz o compose, as variáveis e o primeiro acesso. ## O que esta página vai cobrir [#o-que-esta-página-vai-cobrir] - Contratar e preparar a VPS na Hostinger - Apontar o domínio - Subir o PostgreSQL e o app com o Docker Compose - Configurar o login com Google - Primeiro acesso pelo /setup e o primeiro agente - Backup diário e como conferir # Visão geral do self-host (/docs/projects/self-host) A versão para instalar no próprio servidor ainda não foi lançada, e hoje você pode usar o fazer.ai projects como SaaS em [projects.fazer.ai](https://projects.fazer.ai). Esta seção descreve como a instalação vai funcionar. O self-host é para você que quer rodar o fazer.ai projects no seu servidor e manter os dados da aplicação nele. Você prepara o ambiente, configura como o time entra e cuida das atualizações e dos backups. ## As versões [#as-versões] - **Pro.** Versão para instalar no seu servidor, destinada a membros da [comunidade Lucas Moreira](https://lucasmoreira.ai/?utm_source=docs-fazer-ai&utm_medium=docs&utm_campaign=projects). - **Free.** Versão de código aberto para instalar no próprio servidor. As duas versões ainda estão em planejamento e seguem sem data de lançamento. ## O que você vai precisar [#o-que-você-vai-precisar] - Um servidor Linux com Docker. Para um time, 2 vCPUs e 2 GB de memória dão conta. Com 2 GB, vale ativar swap. - PostgreSQL 18. O Docker Compose de exemplo já inclui uma instância do PostgreSQL. - Um domínio e um proxy reverso com HTTPS na frente da porta `3000`. Você pode usar Traefik, Caddy ou nginx. - Pelo menos uma forma de entrar. Configure o login com Google via OAuth do Google Cloud ou um provedor de e-mail transacional, como Resend ou SMTP. Sem Google e sem e-mail, a aplicação sobe, mas ninguém consegue entrar. - Um bucket S3 privado, caso você queira usá-lo para guardar anexos. O bucket é opcional. ## Como a instalação funciona [#como-a-instalação-funciona] A aplicação roda em uma imagem Docker. Fixe sempre a imagem em uma tag de versão no formato `vX.Y.Z`. A tag `latest` deixa a versão em aberto. Toda vez que o contêiner inicia, ele aplica as migrações de banco de dados da versão em execução. Quando o banco está vazio, a aplicação escreve no log um endereço de uso único no formato `/setup?token=...`. Abra esse endereço e entre com o Google. A conta que você usar vira administradora. Sem login com Google, rode `bun set-admin ` dentro do contêiner para criar a conta de administrador. Depois, use **Esqueci a senha** para definir a senha dessa conta. Esse fluxo precisa do e-mail transacional configurado. ## Configuração [#configuração] As opções de configuração ficam na página [Docker Compose](/docs/projects/self-host/docker-compose). Gere o `JWT_SECRET`, a `ENCRYPTION_KEY` e a senha do banco uma única vez e guarde esses valores. Se você trocar o `JWT_SECRET`, todo mundo sai da sessão. Se trocar a `ENCRYPTION_KEY`, os dados já cifrados ficam ilegíveis. Se usar uma senha nova com o volume antigo do banco, a aplicação perde o acesso aos dados. ## Atualizar, backup e voltar versão [#atualizar-backup-e-voltar-versão] Para atualizar, troque a tag da imagem e suba o contêiner de novo. O novo contêiner aplica as migrações ao iniciar. Para voltar à versão anterior, volte a tag da imagem. As migrações que a versão mais nova aplicou continuam no banco. Por isso, faça um backup antes de toda atualização. Use `pg_dump` diariamente para gerar um backup em formato custom e guarde o arquivo fora do servidor. Para conferir se o backup funciona, restaure o arquivo em um banco descartável. Use apenas esse banco para testar a restauração. ## Próximos passos [#próximos-passos] Em breve. Exemplo de Compose e opções de configuração. Em breve. Passo a passo para instalar em um servidor da Hostinger. # Who am I (/docs/projects/api/principals/getV1Me) The authenticated principal: the user (human or agent), how it authenticated (`WEB` session cookie or `API_KEY` Bearer), the effective scopes, `today` as the calendar date in the user's timezone, and `todayWeekday`, the weekday of that date (ISO, lowercase English, `monday` to `sunday`). For an agent, `user.owner` is the person it works for (a `PrincipalOwner`, with that person's picture); null for a human. `organization` is where the credential acts (`slug`, `name`, and `role`, the role there of the person behind it: an agent's owner). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/me", "operation": { "tags": [ "Principals" ], "summary": "Who am I", "description": "The authenticated principal: the user (human or agent), how it authenticated (`WEB` session cookie or `API_KEY` Bearer), the effective scopes, `today` as the calendar date in the user's timezone, and `todayWeekday`, the weekday of that date (ISO, lowercase English, `monday` to `sunday`). For an agent, `user.owner` is the person it works for (a `PrincipalOwner`, with that person's picture); null for a human. `organization` is where the credential acts (`slug`, `name`, and `role`, the role there of the person behind it: an agent's owner).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Me", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update my profile (/docs/projects/api/principals/patchV1Me) Partial: omitted fields are untouched, `name: null` (or a blank name) clears the name. `handle` is lowercased and must be unique regardless of case (409 otherwise); `timezone` is an IANA name and moves `today` and `todayWeekday` with it. An agent cannot change its own `handle` here (403): its owner sets it once, when the agent is created. A patch that changes nothing answers 200 and records no activity. Answers the same body as `GET /me`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/me", "operation": { "tags": [ "Principals" ], "summary": "Update my profile", "description": "Partial: omitted fields are untouched, `name: null` (or a blank name) clears the name. `handle` is lowercased and must be unique regardless of case (409 otherwise); `timezone` is an IANA name and moves `today` and `todayWeekday` with it. An agent cannot change its own `handle` here (403): its owner sets it once, when the agent is created. A patch that changes nothing answers 200 and records no activity. Answers the same body as `GET /me`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "handle": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,31}$", "minLength": 2, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "handle": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,31}$", "minLength": 2, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "handle": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{1,31}$", "minLength": 2, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } } } }, "operationId": "patchV1Me", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update my owner's profile (/docs/projects/api/principals/patchV1MeOwner) For an agent's key: the name and timezone of the person it works for, as `PATCH /me` changes the caller's own, and recorded as the agent's doing. Not the handle, which mentions resolve (403 when sent), nor the e-mail, which is the Google account. A browser session has no owner (403). Answers the person as `GET /people/:handle` does. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/me/owner", "operation": { "tags": [ "Principals" ], "summary": "Update my owner's profile", "description": "For an agent's key: the name and timezone of the person it works for, as `PATCH /me` changes the caller's own, and recorded as the agent's doing. Not the handle, which mentions resolve (403 when sent), nor the e-mail, which is the Google account. A browser session has no owner (403). Answers the person as `GET /people/:handle` does. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "handle": { "maxLength": 32, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "handle": { "maxLength": 32, "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 200, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "handle": { "maxLength": 32, "type": "string" } } } } } }, "operationId": "patchV1MeOwner", "security": [ { "bearerToken": [] } ] } } ] } ``` # Search people (/docs/projects/api/principals/getV1People) Members of the organization and their agents that are active, matched by substring on name, email and handle (case-insensitive). Without `q` lists everyone. `kind` (`HUMAN` or `AGENT`) keeps one of the two. `limit` defaults to 50 and is capped at 200. Each agent carries `owner`, the person it works for (a `PrincipalOwner`, with that person's picture); a human has `owner: null`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people", "operation": { "tags": [ "Principals" ], "summary": "Search people", "description": "Members of the organization and their agents that are active, matched by substring on name, email and handle (case-insensitive). Without `q` lists everyone. `kind` (`HUMAN` or `AGENT`) keeps one of the two. `limit` defaults to 50 and is capped at 200. Each agent carries `owner`, the person it works for (a `PrincipalOwner`, with that person's picture); a human has `owner: null`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "HUMAN", "AGENT" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1People", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person by handle (/docs/projects/api/principals/getV1PeopleByHandle) One active member of the organization, or an agent of one, named by handle (a leading `@` is accepted): `{ id, handle, name, kind, timezone, avatarUrl, owner }`, where `owner` is the person an agent works for (a `PrincipalOwner`: `{ id, handle, name, avatarUrl }`, the picture the agent's avatar shows in its corner badge) and null for a human. It is what the person card shows. A handle nobody has, or a deactivated account, is a 404. Their tasks are under `GET /people/{handle}/tasks`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}", "operation": { "tags": [ "Principals" ], "summary": "A person by handle", "description": "One active member of the organization, or an agent of one, named by handle (a leading `@` is accepted): `{ id, handle, name, kind, timezone, avatarUrl, owner }`, where `owner` is the person an agent works for (a `PrincipalOwner`: `{ id, handle, name, avatarUrl }`, the picture the agent's avatar shows in its corner badge) and null for a human. It is what the person card shows. A handle nobody has, or a deactivated account, is a 404. Their tasks are under `GET /people/{handle}/tasks`.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandle", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove my profile photo (/docs/projects/api/principals/deleteV1MePhoto) Back to the Google picture, or to initials when there is none (the bot glyph for an agent). The photo is deleted. Nothing to remove answers the same. Answers `{ avatarUrl }`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/me/photo", "operation": { "tags": [ "Principals" ], "summary": "Remove my profile photo", "description": "Back to the Google picture, or to initials when there is none (the bot glyph for an agent). The photo is deleted. Nothing to remove answers the same. Answers `{ avatarUrl }`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "deleteV1MePhoto", "security": [ { "bearerToken": [] } ] } } ] } ``` # Upload my profile photo (/docs/projects/api/principals/putV1MePhoto) My photo, shown everywhere I am drawn ahead of my Google picture (or, for an agent, of its bot glyph). An agent's key sets the agent's own photo; its owner can also set it in Settings (`PUT /agents/:id/photo`), and `PUT /me/owner/photo` is the owner's own. The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes the two renditions the app draws, 64 and 256 px in WebP, and keeps them in the attachments bucket (`avatars//`) or, with no bucket configured, in the database. Answers `{ avatarUrl }`, the new `GET /photos/:id`. The photo it replaces is deleted. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/me/photo", "operation": { "tags": [ "Principals" ], "summary": "Upload my profile photo", "description": "My photo, shown everywhere I am drawn ahead of my Google picture (or, for an agent, of its bot glyph). An agent's key sets the agent's own photo; its owner can also set it in Settings (`PUT /agents/:id/photo`), and `PUT /me/owner/photo` is the owner's own. The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes the two renditions the app draws, 64 and 256 px in WebP, and keeps them in the attachments bucket (`avatars//`) or, with no bucket configured, in the database. Answers `{ avatarUrl }`, the new `GET /photos/:id`. The photo it replaces is deleted.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Error.", "content": { "application/json": { "schema": { "description": "Error.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "putV1MePhoto", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove my owner's profile photo (/docs/projects/api/principals/deleteV1MeOwnerPhoto) For an agent's key: the person it works for goes back to their Google picture, or initials. A browser session has no owner (403). Answers `{ avatarUrl }`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/me/owner/photo", "operation": { "tags": [ "Principals" ], "summary": "Remove my owner's profile photo", "description": "For an agent's key: the person it works for goes back to their Google picture, or initials. A browser session has no owner (403). Answers `{ avatarUrl }`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "deleteV1MeOwnerPhoto", "security": [ { "bearerToken": [] } ] } } ] } ``` # Upload my owner's profile photo (/docs/projects/api/principals/putV1MeOwnerPhoto) For an agent's key: the photo of the person it works for, recorded as the agent's doing. A browser session has no owner (403). The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes the two renditions the app draws, 64 and 256 px in WebP, and keeps them in the attachments bucket (`avatars//`) or, with no bucket configured, in the database. Answers `{ avatarUrl }`, the new `GET /photos/:id`. The photo it replaces is deleted. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/me/owner/photo", "operation": { "tags": [ "Principals" ], "summary": "Upload my owner's profile photo", "description": "For an agent's key: the photo of the person it works for, recorded as the agent's doing. A browser session has no owner (403). The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes the two renditions the app draws, 64 and 256 px in WebP, and keeps them in the attachments bucket (`avatars//`) or, with no bucket configured, in the database. Answers `{ avatarUrl }`, the new `GET /photos/:id`. The photo it replaces is deleted.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Error.", "content": { "application/json": { "schema": { "description": "Error.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "putV1MeOwnerPhoto", "security": [ { "bearerToken": [] } ] } } ] } ``` # A profile photo (/docs/projects/api/principals/getV1PhotosById) The image behind an `avatarUrl` that is a photo: 256 px, or 64 with `?size=64`, WebP. Any signed-in principal may see it, as anyone can see a person's name. A redirect to a short-lived link on the bucket, or the bytes when photos live in the database. A photo that was replaced or removed is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/photos/{id}", "operation": { "tags": [ "Principals" ], "summary": "A profile photo", "description": "The image behind an `avatarUrl` that is a photo: 256 px, or 64 with `?size=64`, WebP. Any signed-in principal may see it, as anyone can see a person's name. A redirect to a short-lived link on the bucket, or the bytes when photos live in the database. A photo that was replaced or removed is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "64", "256" ] } } ], "operationId": "getV1PhotosById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Get the current organization (/docs/projects/api/organizations/getV1Organization) The organization the request acts in: the session's `X-Organization` header (or `org` parameter), or the credential's own for a key or an OAuth token (docs/organizations.md, section 2.4). `{ id, slug, name, role }`, `role` being the caller's (an agent's owner's). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/organization", "operation": { "tags": [ "Organizations" ], "summary": "Get the current organization", "description": "The organization the request acts in: the session's `X-Organization` header (or `org` parameter), or the credential's own for a key or an OAuth token (docs/organizations.md, section 2.4). `{ id, slug, name, role }`, `role` being the caller's (an agent's owner's).", "responses": { "400": { "description": "Bad request: validation failed or the input was malformed.", "content": { "application/json": { "schema": { "description": "Bad request: validation failed or the input was malformed.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Organization", "security": [ { "bearerToken": [] } ] } } ] } ``` # List the organization's members (/docs/projects/api/organizations/getV1OrganizationMembers) Every member with their role (`owner`, `admin`, `member`) and their agents, owners first. The e-mail only for an owner or admin. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/organization/members", "operation": { "tags": [ "Organizations" ], "summary": "List the organization's members", "description": "Every member with their role (`owner`, `admin`, `member`) and their agents, owners first. The e-mail only for an owner or admin.", "responses": { "400": { "description": "Bad request: validation failed or the input was malformed.", "content": { "application/json": { "schema": { "description": "Bad request: validation failed or the input was malformed.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1OrganizationMembers", "security": [ { "bearerToken": [] } ] } } ] } ``` # Read the organization's usage (/docs/projects/api/usage/getV1OrganizationUsage) fazer-ai/projects#697 and #804. The caller's organization against its limits: seats (`occupied` by owners, admins and members, `reserved` by open invites for those roles, `allowed` null for no limit), the attachments' storage (`allowedBytes` null for no ceiling), the live agents of the member who owns the most against the agents one person may own, and the API requests of the last 30 days (UTC) against the request budget, which is one per person (`perMinutePerPerson`, null for none): `days` are the caller's own, every key and OAuth token of the agents of the person the caller is (or acts for), with how many the budget refused; `people` lists every person with requests in those days when the caller's person is an owner or admin of the organization, through any of their credentials, and is null otherwise. Browser sessions never count. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/organization/usage", "operation": { "tags": [ "Usage" ], "summary": "Read the organization's usage", "description": "fazer-ai/projects#697 and #804. The caller's organization against its limits: seats (`occupied` by owners, admins and members, `reserved` by open invites for those roles, `allowed` null for no limit), the attachments' storage (`allowedBytes` null for no ceiling), the live agents of the member who owns the most against the agents one person may own, and the API requests of the last 30 days (UTC) against the request budget, which is one per person (`perMinutePerPerson`, null for none): `days` are the caller's own, every key and OAuth token of the agents of the person the caller is (or acts for), with how many the budget refused; `people` lists every person with requests in those days when the caller's person is an owner or admin of the organization, through any of their credentials, and is null otherwise. Browser sessions never count.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1OrganizationUsage", "security": [ { "bearerToken": [] } ] } } ] } ``` # What changed since a cursor (/docs/projects/api/activity/getV1Changes) Activities in id order, oldest first, only the ones the caller may see: activities on a USER entity (API keys, profile, agents) reach that person and callers with `admin`, and those on a project reach whoever can open it. `nextCursor` is the last `id` of the page; an empty page moves it past what was examined, or echoes `since` when nothing is new, so a poller can store it and come back. A `since` past the signed 64-bit ceiling is a 422. Rows are withheld until 2000 ms after they were WRITTEN (`created_at` is the insert's own clock, not the transaction's start): ids are handed out before a transaction commits, so a write that commits later can carry an id below one already read, and a reader that passed it would never see that row again. The guarantee is exact: a row is never skipped as long as its transaction commits within the window after writing it, which every producer does because the activity is its last statement. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/changes", "operation": { "tags": [ "Activity" ], "summary": "What changed since a cursor", "description": "Activities in id order, oldest first, only the ones the caller may see: activities on a USER entity (API keys, profile, agents) reach that person and callers with `admin`, and those on a project reach whoever can open it. `nextCursor` is the last `id` of the page; an empty page moves it past what was examined, or echoes `since` when nothing is new, so a poller can store it and come back. A `since` past the signed 64-bit ceiling is a 422. Rows are withheld until 2000 ms after they were WRITTEN (`created_at` is the insert's own clock, not the transaction's start): ids are handed out before a transaction commits, so a write that commits later can carry an id below one already read, and a reader that passed it would never see that row again. The guarantee is exact: a row is never skipped as long as its transaction commits within the window after writing it, which every producer does because the activity is its last statement.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 500, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 500, "multipleOf": 1, "type": "number" } ] } }, { "name": "entityType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TASK", "PROJECT", "PAGE", "USER", "LABEL", "STATUS", "WORKFLOW", "JOB", "SAVED_VIEW", "LINK" ] } } ], "operationId": "getV1Changes", "security": [ { "bearerToken": [] } ] } } ] } ``` # The project tree (/docs/projects/api/projects/getV1ProjectsTree) Every project the caller can see, as a flat list ordered by `parentId` (roots first), `sortOrder` and `title`. A sub-project inherits who sees it from its parent unless it is restricted, so a restricted node can carry a `parentId` the caller did not receive: show it at the root. `access` is `PUBLIC` or `PRIVATE` at the root and `INHERIT` or `RESTRICTED` below it, `visibility` says who that lets in (`public` or `members`), and `accessFromId`, for an `INHERIT` project, names the ancestor its access comes from (the nearest private one, or the root when the chain above is public), null when the caller cannot see it. Archived projects (merged ones included) are left out unless `includeArchived=true`. The caller's personal project is created on their first read. `openCount` is the number of open tasks the caller can see in the project itself; `subtreeOpenCount` adds those of every sub-project in this same answer, at any depth, so a sub-project the caller does not receive (restricted away from them, or archived while archived projects are left out) never counts, and a node whose parent is not in the answer starts its own sum; `hasClosedTasks` says whether a completed or cancelled task still sits in the project (deleting a project trashes those too, so a caller offering deletion as safe needs both counts, not just `openCount`); `canManage` says whether the caller may delete the project and change its privacy or members (its owner, or a credential with the admin scope). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/tree", "operation": { "tags": [ "Projects" ], "summary": "The project tree", "description": "Every project the caller can see, as a flat list ordered by `parentId` (roots first), `sortOrder` and `title`. A sub-project inherits who sees it from its parent unless it is restricted, so a restricted node can carry a `parentId` the caller did not receive: show it at the root. `access` is `PUBLIC` or `PRIVATE` at the root and `INHERIT` or `RESTRICTED` below it, `visibility` says who that lets in (`public` or `members`), and `accessFromId`, for an `INHERIT` project, names the ancestor its access comes from (the nearest private one, or the root when the chain above is public), null when the caller cannot see it. Archived projects (merged ones included) are left out unless `includeArchived=true`. The caller's personal project is created on their first read. `openCount` is the number of open tasks the caller can see in the project itself; `subtreeOpenCount` adds those of every sub-project in this same answer, at any depth, so a sub-project the caller does not receive (restricted away from them, or archived while archived projects are left out) never counts, and a node whose parent is not in the answer starts its own sum; `hasClosedTasks` says whether a completed or cancelled task still sits in the project (deleting a project trashes those too, so a caller offering deletion as safe needs both counts, not just `openCount`); `canManage` says whether the caller may delete the project and change its privacy or members (its owner, or a credential with the admin scope).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } } ], "operationId": "getV1ProjectsTree", "security": [ { "bearerToken": [] } ] } } ] } ``` # Create a project (/docs/projects/api/projects/postV1Projects) The caller owns it. `sortOrder` is the last sibling's plus 1024. A private project always has its creator among `memberIds`. `access` sets who sees it: at the root `PUBLIC` (the default) or `PRIVATE`; under a parent `INHERIT` (the default: whoever sees the parent, plus its own members) or `RESTRICTED` (its own people only), where `PRIVATE` is read as `RESTRICTED`, and `PUBLIC` as `INHERIT` when every ancestor is public. `INHERIT` or `RESTRICTED` at the root, and `PUBLIC` under a parent that is not public, are a 422. `isPrivate` is still accepted as an alias (true is `PRIVATE` at the root and `RESTRICTED` below it); sending both with different meanings is a 422. `parentId` must be a project the caller can see (404 otherwise) that is neither a personal project nor a merged project (422). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects", "operation": { "tags": [ "Projects" ], "summary": "Create a project", "description": "The caller owns it. `sortOrder` is the last sibling's plus 1024. A private project always has its creator among `memberIds`. `access` sets who sees it: at the root `PUBLIC` (the default) or `PRIVATE`; under a parent `INHERIT` (the default: whoever sees the parent, plus its own members) or `RESTRICTED` (its own people only), where `PRIVATE` is read as `RESTRICTED`, and `PUBLIC` as `INHERIT` when every ancestor is public. `INHERIT` or `RESTRICTED` at the root, and `PUBLIC` under a parent that is not public, are a 422. `isPrivate` is still accepted as an alias (true is `PRIVATE` at the root and `RESTRICTED` below it); sending both with different meanings is a 422. `parentId` must be a project the caller can see (404 otherwise) that is neither a personal project nor a merged project (422). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } } }, "operationId": "postV1Projects", "security": [ { "bearerToken": [] } ] } } ] } ``` # Get a project (/docs/projects/api/projects/getV1ProjectsById) The node plus `description` (markdown), `ownerId` and `path`: the ancestors the caller can see, from the root down to the parent. A merged project still answers, with `mergedIntoId` naming where it went. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}", "operation": { "tags": [ "Projects" ], "summary": "Get a project", "description": "The node plus `description` (markdown), `ownerId` and `path`: the ancestors the caller can see, from the root down to the parent. A merged project still answers, with `mergedIntoId` naming where it went.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1ProjectsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update a project (/docs/projects/api/projects/patchV1ProjectsById) Partial: an omitted field is untouched and `null` clears `description` or `color`. `icon` is what the project is drawn as in place of its colored circle: `{ kind: "emoji", emoji }` (exactly one emoji, else 422) or `{ kind: "color" }` for the circle again; either drops an uploaded image (`PUT /projects/:id/icon` uploads one), and the color is kept. `memberIds` replaces the members; `addMemberIds`/`removeMemberIds` edit them and cannot be combined with it (422). `access` (or its alias `isPrivate`) follows the rules of the create route, read at the project's current place, and the personal project refuses any change of it (422). Changing it or the members needs the owner or an admin (403); making a project private always adds its author to the members. Every sub-project that inherits from this one follows a change of its privacy or members. A patch that changes nothing records nothing. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/projects/{id}", "operation": { "tags": [ "Projects" ], "summary": "Update a project", "description": "Partial: an omitted field is untouched and `null` clears `description` or `color`. `icon` is what the project is drawn as in place of its colored circle: `{ kind: \"emoji\", emoji }` (exactly one emoji, else 422) or `{ kind: \"color\" }` for the circle again; either drops an uploaded image (`PUT /projects/:id/icon` uploads one), and the color is kept. `memberIds` replaces the members; `addMemberIds`/`removeMemberIds` edit them and cannot be combined with it (422). `access` (or its alias `isPrivate`) follows the rules of the create route, read at the project's current place, and the personal project refuses any change of it (422). Changing it or the members needs the owner or an admin (403); making a project private always adds its author to the members. Every sub-project that inherits from this one follows a change of its privacy or members. A patch that changes nothing records nothing. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "icon": { "anyOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "color", "type": "string" } } }, { "type": "object", "required": [ "kind", "emoji" ], "properties": { "kind": { "const": "emoji", "type": "string" }, "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "icon": { "anyOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "color", "type": "string" } } }, { "type": "object", "required": [ "kind", "emoji" ], "properties": { "kind": { "const": "emoji", "type": "string" }, "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 200, "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "icon": { "anyOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "color", "type": "string" } } }, { "type": "object", "required": [ "kind", "emoji" ], "properties": { "kind": { "const": "emoji", "type": "string" }, "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } ] }, "isPrivate": { "type": "boolean" }, "access": { "type": "string", "enum": [ "PUBLIC", "PRIVATE", "INHERIT", "RESTRICTED" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "memberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeMemberIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } } }, "operationId": "patchV1ProjectsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a project (/docs/projects/api/projects/deleteV1ProjectsById) Soft delete: the row stays with `deletedAt` and the project answers 404 from then on. Only the owner or an admin (403), only without sub-projects that are not deleted (422), never a personal project (422). Its tasks go to the trash, unless `ifEmpty: true` is sent, in which case any task still in the project (added since the caller last read it) is a 422 instead of being trashed. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/projects/{id}", "operation": { "tags": [ "Projects" ], "summary": "Delete a project", "description": "Soft delete: the row stays with `deletedAt` and the project answers 404 from then on. Only the owner or an admin (403), only without sub-projects that are not deleted (422), never a personal project (422). Its tasks go to the trash, unless `ifEmpty: true` is sent, in which case any task still in the project (added since the caller last read it) is a 422 instead of being trashed. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ifEmpty": { "type": "boolean" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "ifEmpty": { "type": "boolean" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "ifEmpty": { "type": "boolean" } } } } } }, "operationId": "deleteV1ProjectsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Who can see a project (/docs/projects/api/projects/getV1ProjectsByIdAudience) `{ everyone, admins, people }`. `everyone` is true when every active user sees it (its access chain is public). `admins` is true for every project but a personal one, which only its owner sees. `people` lists the active people (humans) with a role in the branch; an agent sees what its owner sees, so it is never listed and its own membership lets nobody in. Each entry is `{ id, handle, name, kind, sources }`, each source saying where that access comes from: `owner` or `member` of the project itself, or `ancestorOwner` / `ancestorMember` of an ancestor it inherits from, named by `projectId` and `title` only when the caller can see that ancestor (null otherwise). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}/audience", "operation": { "tags": [ "Projects" ], "summary": "Who can see a project", "description": "`{ everyone, admins, people }`. `everyone` is true when every active user sees it (its access chain is public). `admins` is true for every project but a personal one, which only its owner sees. `people` lists the active people (humans) with a role in the branch; an agent sees what its owner sees, so it is never listed and its own membership lets nobody in. Each entry is `{ id, handle, name, kind, sources }`, each source saying where that access comes from: `owner` or `member` of the project itself, or `ancestorOwner` / `ancestorMember` of an ancestor it inherits from, named by `projectId` and `title` only when the caller can see that ancestor (null otherwise).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1ProjectsByIdAudience", "security": [ { "bearerToken": [] } ] } } ] } ``` # Move a project (/docs/projects/api/projects/postV1ProjectsByIdMove) Under `parentId` (`null` for the root), before the sibling `beforeId` or last without it; the new siblings are reindexed in steps of 1024. A move under the project itself or one of its descendants is a 422, and so is a move of or into a personal project. The answer is the moved project plus `audienceChanged`: true when the people who can see it are not the same after the move (an `INHERIT` project takes the access of the branch it lands in). A move that changes who sees the project, or any project that inherits from it, is a change of privacy: only its owner or an admin may make it (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects/{id}/move", "operation": { "tags": [ "Projects" ], "summary": "Move a project", "description": "Under `parentId` (`null` for the root), before the sibling `beforeId` or last without it; the new siblings are reindexed in steps of 1024. A move under the project itself or one of its descendants is a 422, and so is a move of or into a personal project. The answer is the moved project plus `audienceChanged`: true when the people who can see it are not the same after the move (an `INHERIT` project takes the access of the branch it lands in). A move that changes who sees the project, or any project that inherits from it, is a change of privacy: only its owner or an admin may make it (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "parentId" ], "properties": { "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "beforeId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "parentId" ], "properties": { "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "beforeId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "parentId" ], "properties": { "parentId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "beforeId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] } } } } } }, "operationId": "postV1ProjectsByIdMove", "security": [ { "bearerToken": [] } ] } } ] } ``` # Merge a project into another (/docs/projects/api/projects/postV1ProjectsByIdMerge) Moves the source's tasks and sub-projects into `intoId`, then archives the source with `mergedIntoId` set: it keeps answering GET so a client can follow the redirect. Both must be visible (404), neither a personal project, the same project, an already merged one or, for the target, a descendant of the source (422). When the move changes who sees a re-parented sub-project or what inherits from it, only the source's owner or an admin may merge (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects/{id}/merge", "operation": { "tags": [ "Projects" ], "summary": "Merge a project into another", "description": "Moves the source's tasks and sub-projects into `intoId`, then archives the source with `mergedIntoId` set: it keeps answering GET so a client can follow the redirect. Both must be visible (404), neither a personal project, the same project, an already merged one or, for the target, a descendant of the source (422). When the move changes who sees a re-parented sub-project or what inherits from it, only the source's owner or an admin may merge (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "intoId" ], "properties": { "intoId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "intoId" ], "properties": { "intoId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "intoId" ], "properties": { "intoId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1ProjectsByIdMerge", "security": [ { "bearerToken": [] } ] } } ] } ``` # Archive a project (/docs/projects/api/projects/postV1ProjectsByIdArchive) Idempotent. Its sub-projects are not archived. The personal project is a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects/{id}/archive", "operation": { "tags": [ "Projects" ], "summary": "Archive a project", "description": "Idempotent. Its sub-projects are not archived. The personal project is a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1ProjectsByIdArchive", "security": [ { "bearerToken": [] } ] } } ] } ``` # Unarchive a project (/docs/projects/api/projects/postV1ProjectsByIdUnarchive) Idempotent. The personal project or a merged project is a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects/{id}/unarchive", "operation": { "tags": [ "Projects" ], "summary": "Unarchive a project", "description": "Idempotent. The personal project or a merged project is a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1ProjectsByIdUnarchive", "security": [ { "bearerToken": [] } ] } } ] } ``` # Upload a project's icon (/docs/projects/api/projects/putV1ProjectsByIdIcon) fazer-ai/projects#441. An image the project is drawn as in place of its colored circle, mainly a client's or a product's logo; the color is kept. The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, SVG included, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes 64 and 256 px renditions in WebP and keeps them in the attachments bucket (`project-icons//`) or, with no bucket configured, in the database. Whoever sees the project may change it (404 otherwise). The emoji or image it replaces goes. Answers the project, whose `icon.url` serves the image only to whoever sees the project. `PATCH` with `icon: { kind: "color" }` goes back to the circle. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/projects/{id}/icon", "operation": { "tags": [ "Projects" ], "summary": "Upload a project's icon", "description": "fazer-ai/projects#441. An image the project is drawn as in place of its colored circle, mainly a client's or a product's logo; the color is kept. The body is the image itself, JPEG, PNG or WebP, at most 5 MB (413 past it; 422 for anything that does not decode as one of the three, SVG included, whatever its `Content-Type` says). The client is expected to crop it to a square; the server makes 64 and 256 px renditions in WebP and keeps them in the attachments bucket (`project-icons//`) or, with no bucket configured, in the database. Whoever sees the project may change it (404 otherwise). The emoji or image it replaces goes. Answers the project, whose `icon.url` serves the image only to whoever sees the project. `PATCH` with `icon: { kind: \"color\" }` goes back to the circle.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Error.", "content": { "application/json": { "schema": { "description": "Error.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "putV1ProjectsByIdIcon", "security": [ { "bearerToken": [] } ] } } ] } ``` # A project's icon (/docs/projects/api/projects/getV1ProjectsByIdIconByIconId) The image behind a project's `icon.url`: 256 px, or 64 with `?size=64`, WebP. Served by the app itself, from the bucket or the database, and only to whoever sees the project: anyone else, and an icon that was replaced or removed, gets a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}/icon/{iconId}", "operation": { "tags": [ "Projects" ], "summary": "A project's icon", "description": "The image behind a project's `icon.url`: 256 px, or 64 with `?size=64`, WebP. Served by the app itself, from the bucket or the database, and only to whoever sees the project: anyone else, and an icon that was replaced or removed, gets a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "iconId", "in": "path", "required": true, "schema": { "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "64", "256" ] } } ], "operationId": "getV1ProjectsByIdIconByIconId", "security": [ { "bearerToken": [] } ] } } ] } ``` # The emoji the picker offers (/docs/projects/api/projects/getV1Emoji) Every emoji the picker offers (a project's icon, a comment's reaction), in the Unicode order: `{ data: [{ emoji, label, tags, group }] }`, the name and keywords in `locale` (`en` or `pt-BR`, `en` by default). Emoji newer than Emoji 15.0 are left out, since no emoji font is shipped and an older system would draw them as empty boxes. `PATCH /projects/:id` and a reaction take any single emoji all the same. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/emoji", "operation": { "tags": [ "Projects" ], "summary": "The emoji the picker offers", "description": "Every emoji the picker offers (a project's icon, a comment's reaction), in the Unicode order: `{ data: [{ emoji, label, tags, group }] }`, the name and keywords in `locale` (`en` or `pt-BR`, `en` by default). Emoji newer than Emoji 15.0 are left out, since no emoji font is shipped and an older system would draw them as empty boxes. `PATCH /projects/:id` and a reaction take any single emoji all the same.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "locale", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "pt-BR" ] } } ], "operationId": "getV1Emoji", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a project's subscribers (/docs/projects/api/projects/getV1ProjectsByIdSubscribers) `{ data }`, oldest subscription first, active users only. This is the list a new comment on the project is announced to. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the project (`COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}/subscribers", "operation": { "tags": [ "Projects" ], "summary": "List a project's subscribers", "description": "`{ data }`, oldest subscription first, active users only. This is the list a new comment on the project is announced to. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the project (`COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1ProjectsByIdSubscribers", "security": [ { "bearerToken": [] } ] } } ] } ``` # Unsubscribe from a project (/docs/projects/api/projects/deleteV1ProjectsByIdSubscription) Removes the caller from the project's comment thread whatever their reasons. Idempotent. A later comment or mention subscribes them again. Records `subscription.removed` on the project when there was something to remove. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/projects/{id}/subscription", "operation": { "tags": [ "Projects" ], "summary": "Unsubscribe from a project", "description": "Removes the caller from the project's comment thread whatever their reasons. Idempotent. A later comment or mention subscribes them again. Records `subscription.removed` on the project when there was something to remove. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1ProjectsByIdSubscription", "security": [ { "bearerToken": [] } ] } } ] } ``` # Subscribe to a project (/docs/projects/api/projects/putV1ProjectsByIdSubscription) Subscribes the caller to the project's comment thread with the reason `MANUAL`, kept next to any reason they already had. Idempotent. Records `subscription.added` on the project when it changes something. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the project (`COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/projects/{id}/subscription", "operation": { "tags": [ "Projects" ], "summary": "Subscribe to a project", "description": "Subscribes the caller to the project's comment thread with the reason `MANUAL`, kept next to any reason they already had. Idempotent. Records `subscription.added` on the project when it changes something. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the project (`COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "putV1ProjectsByIdSubscription", "security": [ { "bearerToken": [] } ] } } ] } ``` # Search tasks (query string) (/docs/projects/api/search/getV1Tasks) `POST /tasks/search` for a client that can only GET: `filter` is the filter as JSON, `sort` is `dueAt,-priority` (a leading `-` is descending; `field:desc` and the JSON list also work). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks", "operation": { "tags": [ "Search" ], "summary": "Search tasks (query string)", "description": "`POST /tasks/search` for a client that can only GET: `filter` is the filter as JSON, `sort` is `dueAt,-priority` (a leading `-` is descending; `field:desc` and the JSON list also work). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Tasks", "security": [ { "bearerToken": [] } ] } } ] } ``` # Search tasks (/docs/projects/api/search/postV1TasksSearch) Every task the caller can see that matches `filter` (every visible task without one), in `sort` order (default `sortOrder`, or `relevance` when the filter has a `text` condition; tasks without the sorted value come last). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/search", "operation": { "tags": [ "Search" ], "summary": "Search tasks", "description": "Every task the caller can see that matches `filter` (every visible task without one), in `sort` order (default `sortOrder`, or `relevance` when the filter has a `text` condition; tasks without the sorted value come last). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "limit": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] }, "offset": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "limit": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] }, "offset": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "limit": { "minimum": 1, "maximum": 200, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "type": "integer" } ] }, "offset": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" } } } } } }, "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "postV1TasksSearch", "security": [ { "bearerToken": [] } ] } } ], "components": { "schemas": { "FilterNode": { "description": "A task filter: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`. At most 10 levels deep and 200 nodes. `between` is inclusive at both ends.", "anyOf": [ { "additionalProperties": false, "description": "Every child matches.", "type": "object", "required": [ "and" ], "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "At least one child matches.", "type": "object", "required": [ "or" ], "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "The child does not match.", "type": "object", "required": [ "not" ], "properties": { "not": { "$ref": "#/components/schemas/FilterNode" } } }, { "additionalProperties": false, "description": "Project id. `includeChildren: true` also matches every descendant of the project(s).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "project", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] }, "includeChildren": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Task status id.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "status", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] } } }, { "additionalProperties": false, "description": "Category of the task's status.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "statusCategory", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the task is closed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "done", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "`eq` means \"among the assignees\", `neq` \"not among them\"; `empty` means no assignee. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "assignee", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who created the task. `\"me\"` is the caller and their agents: a task one of your agents created counts as yours (for an agent, `\"me\"` is its owner and the owner's agents).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creator", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the creator is a human or an agent.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creatorKind", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "`eq` means \"has the label\"; `empty` means no label at all.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "label", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Priority, 0 (none) to 5.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "priority", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "minimum": 0, "maximum": 5, "type": "integer" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minimum": 0, "maximum": 5, "type": "integer" } } ] } } }, { "additionalProperties": false, "description": "Due date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "dueAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Start date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "startAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was completed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "doneAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was created.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "createdAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "When the task last changed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "updatedAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "Whether the task's own project is archived (not its parent's). The personal views take `false`.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "projectArchived", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Whether the task has a recurrence.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "recurring", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Id of the task in the system it was imported from.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "externalId", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "minLength": 1, "maxLength": 255, "type": "string" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minLength": 1, "maxLength": 255, "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Full-text search over the title and the description.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "text", "type": "string" }, "op": { "const": "contains", "type": "string" }, "value": { "minLength": 1, "maxLength": 200, "type": "string" } } }, { "additionalProperties": false, "description": "A user mentioned in the description. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "mentions", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who the task's open review request is with. `empty` means no open request. `\"me\"` is the caller and their agents: a request made to one of your agents waits on you.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewer", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who asked for the task's open review. `\"me\"` is the caller and their agents.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewRequester", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } } ] }, "TaskSort": { "maxItems": 8, "description": "The order of the results, most significant first. Tasks without a value for a field come last in both directions; the id breaks ties. Default: `sortOrder`, the manual order, or `relevance` when the filter has a `text` condition. `relevance` is a whole order of its own and stands alone (ascending, best match first): a task whose id is the text, then titles that start with the text (accents and case ignored), then the full text rank (title above description), open before closed, most recently updated first. Only a search with a `text` condition takes it.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field" ], "properties": { "field": { "anyOf": [ { "const": "dueAt", "type": "string" }, { "const": "startAt", "type": "string" }, { "const": "priority", "type": "string" }, { "const": "createdAt", "type": "string" }, { "const": "updatedAt", "type": "string" }, { "const": "title", "type": "string" }, { "const": "sortOrder", "type": "string" }, { "const": "relevance", "type": "string" } ] }, "dir": { "default": "asc", "anyOf": [ { "const": "asc", "type": "string" }, { "const": "desc", "type": "string" } ] } } } }, "PrincipalOwner": { "description": "The person an agent works for. Every response that carries a principal has it as `owner`, null for a human.", "type": "object", "required": [ "id", "handle", "name", "avatarUrl" ], "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "description": "The owner's picture, drawn in a badge on the agent's avatar; null without one.", "type": "string" }, { "type": "null" } ] } } } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } } } } ``` # Today (/docs/projects/api/search/getV1ViewsToday) My open tasks due or started by the end of today in `tz`, or in progress, in three buckets: `overdue` (due before today), `today` (the rest with a date by today; `reason` says whether by `due` or `start`) and `inProgress` (by the status alone, `reason: "status"`). A task is in one bucket only, in that order, and a task with an open review request is in none of the three: it is in `awaitingReview` when the request is with me (whatever its dates, and whoever it is assigned to) and in `waiting` when it is mine, or I asked, and it is with someone else, both oldest request first and both `GET /views/reviews`'s lists. Today is `overdue` + `today` + `awaitingReview`: `counts.todayTotal` is its size, the number every "Today" shows (the sidebar, `GET /views/counts`'s `todayTotal`); `inProgress` and `waiting` are separate sections and are not in it. Each list holds up to 200 tasks and `counts` has their full sizes. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/today", "operation": { "tags": [ "Search" ], "summary": "Today", "description": "My open tasks due or started by the end of today in `tz`, or in progress, in three buckets: `overdue` (due before today), `today` (the rest with a date by today; `reason` says whether by `due` or `start`) and `inProgress` (by the status alone, `reason: \"status\"`). A task is in one bucket only, in that order, and a task with an open review request is in none of the three: it is in `awaitingReview` when the request is with me (whatever its dates, and whoever it is assigned to) and in `waiting` when it is mine, or I asked, and it is with someone else, both oldest request first and both `GET /views/reviews`'s lists. Today is `overdue` + `today` + `awaitingReview`: `counts.todayTotal` is its size, the number every \"Today\" shows (the sidebar, `GET /views/counts`'s `todayTotal`); `inProgress` and `waiting` are separate sections and are not in it. Each list holds up to 200 tasks and `counts` has their full sizes. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsToday", "security": [ { "bearerToken": [] } ] } } ] } ``` # Upcoming (/docs/projects/api/search/getV1ViewsUpcoming) My open tasks due or starting in `[tomorrow, tomorrow + days)` (days 1 to 60, default 7) in `tz`, as `{ days: [{ date, tasks }], total }` with one entry per local date of the window. A task is listed once, under the earliest of its dates in the window, with `reason` `due` or `start`. A task overdue or in Today is not listed, even when one of its dates falls in the window: each task is in one of overdue, today and upcoming. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/upcoming", "operation": { "tags": [ "Search" ], "summary": "Upcoming", "description": "My open tasks due or starting in `[tomorrow, tomorrow + days)` (days 1 to 60, default 7) in `tz`, as `{ days: [{ date, tasks }], total }` with one entry per local date of the window. A task is listed once, under the earliest of its dates in the window, with `reason` `due` or `start`. A task overdue or in Today is not listed, even when one of its dates falls in the window: each task is in one of overdue, today and upcoming. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 60, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 60, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsUpcoming", "security": [ { "bearerToken": [] } ] } } ] } ``` # My tasks (/docs/projects/api/search/getV1ViewsMine) Every open task of mine, in any project I can see, dated or not. Each task carries `due`, its group in `tz`: `today` (due or started by the end of today, overdue included: `GET /views/today`'s `overdue` and `today` buckets together, whose size is `todayTotal` in `GET /views/counts`), `next7` (exactly `GET /views/upcoming`: a due or start date in `[tomorrow, tomorrow + 7d)`, and not overdue or today), then the rest: `later` (due after that window) or `noDate` (no due date), neither with a start before the end of that window, so a task with no due date that starts after the window is in `noDate` and still has its start. Each task also carries `overdue`, true for a task of `today` due before today, and `reason`, the date that put it in its group, read as `GET /views/today` and `GET /views/upcoming` read it: `due` or `start` in `today` and `next7`, `due` in `later`, `null` in `noDate`. A task in progress by its status alone is in `next7`, `later` or `noDate` by its dates. `groups` has the size of each group, over the same filter, in the same snapshot. `filter` (the filter as JSON, like `GET /tasks`) narrows the view, and narrows the groups with it; `sort` is `GET /tasks`'s (default: due date, then start date, then priority). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/mine", "operation": { "tags": [ "Search" ], "summary": "My tasks", "description": "Every open task of mine, in any project I can see, dated or not. Each task carries `due`, its group in `tz`: `today` (due or started by the end of today, overdue included: `GET /views/today`'s `overdue` and `today` buckets together, whose size is `todayTotal` in `GET /views/counts`), `next7` (exactly `GET /views/upcoming`: a due or start date in `[tomorrow, tomorrow + 7d)`, and not overdue or today), then the rest: `later` (due after that window) or `noDate` (no due date), neither with a start before the end of that window, so a task with no due date that starts after the window is in `noDate` and still has its start. Each task also carries `overdue`, true for a task of `today` due before today, and `reason`, the date that put it in its group, read as `GET /views/today` and `GET /views/upcoming` read it: `due` or `start` in `today` and `next7`, `due` in `later`, `null` in `noDate`. A task in progress by its status alone is in `next7`, `later` or `noDate` by its dates. `groups` has the size of each group, over the same filter, in the same snapshot. `filter` (the filter as JSON, like `GET /tasks`) narrows the view, and narrows the groups with it; `sort` is `GET /tasks`'s (default: due date, then start date, then priority). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`; `limit` is 1 to 200 (default 50). Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsMine", "security": [ { "bearerToken": [] } ] } } ] } ``` # My tasks: Today (/docs/projects/api/search/getV1ViewsMineToday) `GET /views/today` narrowed and ordered: the same three buckets, each with its `reason`, of the tasks that also match `filter` (the filter as JSON, like `GET /tasks`), and `counts` over the same narrowing, in the same snapshot. `sort` is `GET /tasks`'s and replaces the view's order (due date, then start date, then priority) inside each bucket. `flat=true` adds `order`, the ids of every task listed across the buckets in that order, for a client that groups them another way. `limit` (1 to 200) and `offset` take one page of the three buckets together, in that order, each task still under its bucket, and add `order` (the page's ids in that order) and `total` (the buckets together): read page after page up to `total` for the whole view, however large. Without a page each bucket lists up to 200 tasks. `awaitingReview` and `waiting` are narrowed by `filter` too, are never paged or counted in `total`, and come whole (up to 200) with every page. Without any of them it answers exactly what `GET /views/today` answers. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/mine/today", "operation": { "tags": [ "Search" ], "summary": "My tasks: Today", "description": "`GET /views/today` narrowed and ordered: the same three buckets, each with its `reason`, of the tasks that also match `filter` (the filter as JSON, like `GET /tasks`), and `counts` over the same narrowing, in the same snapshot. `sort` is `GET /tasks`'s and replaces the view's order (due date, then start date, then priority) inside each bucket. `flat=true` adds `order`, the ids of every task listed across the buckets in that order, for a client that groups them another way. `limit` (1 to 200) and `offset` take one page of the three buckets together, in that order, each task still under its bucket, and add `order` (the page's ids in that order) and `total` (the buckets together): read page after page up to `total` for the whole view, however large. Without a page each bucket lists up to 200 tasks. `awaitingReview` and `waiting` are narrowed by `filter` too, are never paged or counted in `total`, and come whole (up to 200) with every page. Without any of them it answers exactly what `GET /views/today` answers. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "flat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsMineToday", "security": [ { "bearerToken": [] } ] } } ] } ``` # My tasks: Next 7 days (/docs/projects/api/search/getV1ViewsMineUpcoming) `GET /views/upcoming` (7 days) narrowed and ordered: the same days, each task under the earliest of its dates in the window with its `reason`, of the tasks that also match `filter` (the filter as JSON, like `GET /tasks`), and `total` over the same narrowing. `sort` is `GET /tasks`'s and orders the tasks inside each day instead of that date. `flat=true` adds `order`, the ids of every task listed across the days in that order (or the view's: due date, then start date, then priority). `limit` (1 to 200) and `offset` take one page of the days' tasks together, in that order, each still under its day, and add `order`: read page after page up to `total` for the whole view, however large. Without `sort` a day lists its tasks by the date that put each one there, then by id, which is not the order the pages come in: sort each day again after putting the pages together. Without a page the days list up to 500 tasks. Without any of them it answers exactly what `GET /views/upcoming` answers. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/mine/upcoming", "operation": { "tags": [ "Search" ], "summary": "My tasks: Next 7 days", "description": "`GET /views/upcoming` (7 days) narrowed and ordered: the same days, each task under the earliest of its dates in the window with its `reason`, of the tasks that also match `filter` (the filter as JSON, like `GET /tasks`), and `total` over the same narrowing. `sort` is `GET /tasks`'s and orders the tasks inside each day instead of that date. `flat=true` adds `order`, the ids of every task listed across the days in that order (or the view's: due date, then start date, then priority). `limit` (1 to 200) and `offset` take one page of the days' tasks together, in that order, each still under its day, and add `order`: read page after page up to `total` for the whole view, however large. Without `sort` a day lists its tasks by the date that put each one there, then by id, which is not the order the pages come in: sort each day again after putting the pages together. Without a page the days list up to 500 tasks. Without any of them it answers exactly what `GET /views/upcoming` answers. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "flat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsMineUpcoming", "security": [ { "bearerToken": [] } ] } } ] } ``` # View counters (/docs/projects/api/search/getV1ViewsCounts) `{ overdue, today, todayTotal, inProgress, upcoming, mine, noDate, awaitingReview, waitingOnOthers }` for the caller in `tz`. `todayTotal` is Today, `overdue` + `today` + `awaitingReview`, the number to show for Today (the sidebar shows it, and no client adds buckets up); `overdue` and `today` are the tasks of mine due or started by today (`today` is the part that is not overdue) that are not under review, `awaitingReview` is what waits on my review whatever its dates (the size of `GET /views/reviews?waitingOn=me`), and `inProgress` (by the status alone) and `waitingOnOthers` (the size of `GET /views/reviews?waitingOn=others`) are not in it. Then the sizes of Upcoming (`days`, 1 to 60, default 7: the window `GET /views/upcoming` takes, and the only counter it changes), of My tasks (`mine`) and of its `noDate` group (no due date and no start before the end of the Upcoming window), counted over the same filters the lists use, in one snapshot. `filter` (the search DSL, as JSON) narrows every counter as it narrows the lists, so the numbers beside a searched list are that list's: with a search that matches nothing, all are 0. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/counts", "operation": { "tags": [ "Search" ], "summary": "View counters", "description": "`{ overdue, today, todayTotal, inProgress, upcoming, mine, noDate, awaitingReview, waitingOnOthers }` for the caller in `tz`. `todayTotal` is Today, `overdue` + `today` + `awaitingReview`, the number to show for Today (the sidebar shows it, and no client adds buckets up); `overdue` and `today` are the tasks of mine due or started by today (`today` is the part that is not overdue) that are not under review, `awaitingReview` is what waits on my review whatever its dates (the size of `GET /views/reviews?waitingOn=me`), and `inProgress` (by the status alone) and `waitingOnOthers` (the size of `GET /views/reviews?waitingOn=others`) are not in it. Then the sizes of Upcoming (`days`, 1 to 60, default 7: the window `GET /views/upcoming` takes, and the only counter it changes), of My tasks (`mine`) and of its `noDate` group (no due date and no start before the end of the Upcoming window), counted over the same filters the lists use, in one snapshot. `filter` (the search DSL, as JSON) narrows every counter as it narrows the lists, so the numbers beside a searched list are that list's: with a search that matches nothing, all are 0. Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "days", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 60, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 60, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsCounts", "security": [ { "bearerToken": [] } ] } } ] } ``` # Review requests (/docs/projects/api/search/getV1ViewsReviews) The open tasks with a review request, oldest request first, `{ data, total, limit, offset }`, each task with its `review` (`{ id, approver, requestedBy, requestedAt, note }`). `waitingOn=me`: the request is with me (or with one of my agents), whatever the task's dates and assignees; it is Today's `awaitingReview` and counts in `todayTotal`. `waitingOn=others`: the request is with someone else and the task is mine, or I (or one of my agents) asked; Today lists it as `waiting` and counts it in nothing. Only tasks the caller can see, outside archived projects. `filter` (the search DSL, as JSON) narrows the list, and `total` is the narrowed list's size. `limit` is 1 to 200 (default 50). Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/views/reviews", "operation": { "tags": [ "Search" ], "summary": "Review requests", "description": "The open tasks with a review request, oldest request first, `{ data, total, limit, offset }`, each task with its `review` (`{ id, approver, requestedBy, requestedAt, note }`). `waitingOn=me`: the request is with me (or with one of my agents), whatever the task's dates and assignees; it is Today's `awaitingReview` and counts in `todayTotal`. `waitingOn=others`: the request is with someone else and the task is mine, or I (or one of my agents) asked; Today lists it as `waiting` and counts it in nothing. Only tasks the caller can see, outside archived projects. `filter` (the search DSL, as JSON) narrows the list, and `total` is the narrowed list's size. `limit` is 1 to 200 (default 50). Mine is assigned to me, or created by me or one of my agents and assigned to nobody; open is not completed and not cancelled. The filter each view is made of is in docs/api.md, so a search or a saved view with it is the same query.", "parameters": [ { "name": "waitingOn", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "me", "others" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1ViewsReviews", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person's tasks (/docs/projects/api/search/getV1PeopleByHandleTasks) Every open task of a person, as `GET /views/mine` answers the caller's own: `{ data, total, limit, offset, groups, meta }`, each task with `due` (`today`, overdue included, `next7`, `later` or `noDate`), `overdue` and `reason`, and `groups` with the size of each group. `filter` and `sort` are `GET /views/mine`'s. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike "mine", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}/tasks", "operation": { "tags": [ "Search" ], "summary": "A person's tasks", "description": "Every open task of a person, as `GET /views/mine` answers the caller's own: `{ data, total, limit, offset, groups, meta }`, each task with `due` (`today`, overdue included, `next7`, `later` or `noDate`), `overdue` and `reason`, and `groups` with the size of each group. `filter` and `sort` are `GET /views/mine`'s. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike \"mine\", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } }, { "name": "agents", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandleTasks", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person's tasks: Today (/docs/projects/api/search/getV1PeopleByHandleTasksToday) A person's Today, as `GET /views/mine/today` answers the caller's own: the buckets `overdue`, `today` and `inProgress`, each task with its `reason`, and `counts` (`todayTotal` is Today, `overdue` + `today`). `filter`, `sort`, `flat`, `limit` and `offset` are that route's. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike "mine", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}/tasks/today", "operation": { "tags": [ "Search" ], "summary": "A person's tasks: Today", "description": "A person's Today, as `GET /views/mine/today` answers the caller's own: the buckets `overdue`, `today` and `inProgress`, each task with its `reason`, and `counts` (`todayTotal` is Today, `overdue` + `today`). `filter`, `sort`, `flat`, `limit` and `offset` are that route's. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike \"mine\", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } }, { "name": "agents", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "flat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandleTasksToday", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person's tasks: Next 7 days (/docs/projects/api/search/getV1PeopleByHandleTasksUpcoming) A person's next 7 days, as `GET /views/mine/upcoming` answers the caller's own: `{ days: [{ date, tasks }], total }`, each task once, under the earliest of its dates in the window, and never one that is overdue or in Today. `filter`, `sort`, `flat`, `limit` and `offset` are that route's. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike "mine", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}/tasks/upcoming", "operation": { "tags": [ "Search" ], "summary": "A person's tasks: Next 7 days", "description": "A person's next 7 days, as `GET /views/mine/upcoming` answers the caller's own: `{ days: [{ date, tasks }], total }`, each task once, under the earliest of its dates in the window, and never one that is overdue or in Today. `filter`, `sort`, `flat`, `limit` and `offset` are that route's. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike \"mine\", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } }, { "name": "agents", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "name": "flat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandleTasksUpcoming", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person's tasks: completed lately (/docs/projects/api/search/getV1PeopleByHandleTasksCompleted) What a person delivered in the last 7 days, newest first, since the start of the day 7 days ago in `tz`, as `{ data, total, limit, offset, meta: { resolved, tz } }` (`limit` 1 to 200, default 50): each task completed for good, and each completion of a recurring task that rolled to its next date (the task stays open, so it comes once per completion). Every row is a task with `completedAt`, when that delivery happened, and `completionId`, the completion of a roll or null for a task closed for good. A completion counts for the person the task is assigned to, as a completed task does, and the one that ended a series is the task's own row, not a second one. A cancelled task is not a completed one. A task completed in a project that was archived since is still listed: the open lists leave an archived project's tasks out, this record of deliveries does not. `filter` narrows the list as it narrows the others. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike "mine", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}/tasks/completed", "operation": { "tags": [ "Search" ], "summary": "A person's tasks: completed lately", "description": "What a person delivered in the last 7 days, newest first, since the start of the day 7 days ago in `tz`, as `{ data, total, limit, offset, meta: { resolved, tz } }` (`limit` 1 to 200, default 50): each task completed for good, and each completion of a recurring task that rolled to its next date (the task stays open, so it comes once per completion). Every row is a task with `completedAt`, when that delivery happened, and `completionId`, the completion of a roll or null for a task closed for good. A completion counts for the person the task is assigned to, as a completed task does, and the one that ended a series is the task's own row, not a second one. A cancelled task is not a completed one. A task completed in a project that was archived since is still listed: the open lists leave an archived project's tasks out, this record of deliveries does not. `filter` narrows the list as it narrows the others. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike \"mine\", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } }, { "name": "agents", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandleTasksCompleted", "security": [ { "bearerToken": [] } ] } } ] } ``` # A person's task counters (/docs/projects/api/search/getV1PeopleByHandleTasksCounts) `{ person, includeAgents, assigneeIds, counts: { overdue, today, todayTotal, upcoming, all, completed } }`: who the person is, whose tasks are counted (the person's id, then their agents' when included: `{ field: "assignee", op: "in", value: assigneeIds }` is the same question as a search filter), and the sizes of their lists, counted over the same filters the lists use, in one snapshot. `todayTotal` is Today (`overdue` + `today`), `upcoming` the next 7 days, `all` every open task and `completed` the last 7 days' deliveries (tasks completed for good plus the completions of recurring tasks: the rows of `/completed`). `includeAgents` is false for an agent, which has no agents of its own. `filter` narrows every counter as it narrows the lists, so the numbers beside a filtered list are that list's: with a search that matches nothing the caller can see, all are 0. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike "mine", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/people/{handle}/tasks/counts", "operation": { "tags": [ "Search" ], "summary": "A person's task counters", "description": "`{ person, includeAgents, assigneeIds, counts: { overdue, today, todayTotal, upcoming, all, completed } }`: who the person is, whose tasks are counted (the person's id, then their agents' when included: `{ field: \"assignee\", op: \"in\", value: assigneeIds }` is the same question as a search filter), and the sizes of their lists, counted over the same filters the lists use, in one snapshot. `todayTotal` is Today (`overdue` + `today`), `upcoming` the next 7 days, `all` every open task and `completed` the last 7 days' deliveries (tasks completed for good plus the completions of recurring tasks: the rows of `/completed`). `includeAgents` is false for an agent, which has no agents of its own. `filter` narrows every counter as it narrows the lists, so the numbers beside a filtered list are that list's: with a search that matches nothing the caller can see, all are 0. The tasks are the ones assigned to the person named by `handle` (a human or an agent; unlike \"mine\", a task they created with nobody assigned is not included, and neither is an open task of an archived project), plus the ones assigned to their agents with `agents=true`. Anyone can ask about anyone, and the answer holds only what the CALLER can see: a task in a project the caller cannot access (the person's Personal project, a private project the caller is not in, a sub-project that inherits from one or is restricted to people the caller is not among) is in no list and in no number, so these differ from what the person reads in their own views. Dates are read in `tz` (default: the caller's timezone). A handle nobody has, or a deactivated account, is a 404. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`.", "parameters": [ { "name": "handle", "in": "path", "required": true, "schema": { "minLength": 1, "maxLength": 33, "type": "string" } }, { "name": "agents", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "filter", "in": "query", "required": false, "schema": { "maxLength": 20000, "type": "string" } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1PeopleByHandleTasksCounts", "security": [ { "bearerToken": [] } ] } } ] } ``` # List saved views (/docs/projects/api/search/getV1Saved-views) Mine, then the shared ones, each by name: `{ data: [{ id, ownerId, shared, name, slug, filter, sort, groupBy, layout, externalId, createdAt, updatedAt }] }`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/saved-views", "operation": { "tags": [ "Search" ], "summary": "List saved views", "description": "Mine, then the shared ones, each by name: `{ data: [{ id, ownerId, shared, name, slug, filter, sort, groupBy, layout, externalId, createdAt, updatedAt }] }`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Saved-views", "security": [ { "bearerToken": [] } ] } } ] } ``` # Save a view (/docs/projects/api/search/postV1Saved-views) `slug` defaults to the name in lowercase words joined by hyphens and is unique per owner (the shared views are one namespace): a repeat is a 409. `layout` is `list` (default), `kanban` or `gantt`; `groupBy` is `status`, `assignee`, `priority` or `label`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. Records `saved_view.created`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/saved-views", "operation": { "tags": [ "Search" ], "summary": "Save a view", "description": "`slug` defaults to the name in lowercase words joined by hyphens and is unique per owner (the shared views are one namespace): a repeat is a 409. `layout` is `list` (default), `kanban` or `gantt`; `groupBy` is `status`, `assignee`, `priority` or `label`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. The filter DSL is documented as the `FilterNode` schema and in docs/api.md: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`, at most 10 levels and 200 nodes. Relative dates (`today`, `amanhã+2d`, `endOfWeek`...) and `YYYY-MM-DD` resolve in `tz` (default: the caller's timezone), and `meta.resolved` shows what each became. A filter or sort that cannot be read is a 422 with `path` (a JSON Pointer into the request, such as `/filter/and/1`) and `code`. Records `saved_view.created`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "filter" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "shared": { "type": "boolean" }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "name", "filter" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "shared": { "type": "boolean" }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "name", "filter" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "shared": { "type": "boolean" }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } } } }, "operationId": "postV1Saved-views", "security": [ { "bearerToken": [] } ] } } ], "components": { "schemas": { "FilterNode": { "description": "A task filter: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`. At most 10 levels deep and 200 nodes. `between` is inclusive at both ends.", "anyOf": [ { "additionalProperties": false, "description": "Every child matches.", "type": "object", "required": [ "and" ], "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "At least one child matches.", "type": "object", "required": [ "or" ], "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "The child does not match.", "type": "object", "required": [ "not" ], "properties": { "not": { "$ref": "#/components/schemas/FilterNode" } } }, { "additionalProperties": false, "description": "Project id. `includeChildren: true` also matches every descendant of the project(s).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "project", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] }, "includeChildren": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Task status id.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "status", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] } } }, { "additionalProperties": false, "description": "Category of the task's status.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "statusCategory", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the task is closed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "done", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "`eq` means \"among the assignees\", `neq` \"not among them\"; `empty` means no assignee. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "assignee", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who created the task. `\"me\"` is the caller and their agents: a task one of your agents created counts as yours (for an agent, `\"me\"` is its owner and the owner's agents).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creator", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the creator is a human or an agent.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creatorKind", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "`eq` means \"has the label\"; `empty` means no label at all.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "label", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Priority, 0 (none) to 5.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "priority", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "minimum": 0, "maximum": 5, "type": "integer" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minimum": 0, "maximum": 5, "type": "integer" } } ] } } }, { "additionalProperties": false, "description": "Due date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "dueAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Start date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "startAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was completed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "doneAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was created.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "createdAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "When the task last changed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "updatedAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "Whether the task's own project is archived (not its parent's). The personal views take `false`.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "projectArchived", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Whether the task has a recurrence.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "recurring", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Id of the task in the system it was imported from.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "externalId", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "minLength": 1, "maxLength": 255, "type": "string" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minLength": 1, "maxLength": 255, "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Full-text search over the title and the description.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "text", "type": "string" }, "op": { "const": "contains", "type": "string" }, "value": { "minLength": 1, "maxLength": 200, "type": "string" } } }, { "additionalProperties": false, "description": "A user mentioned in the description. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "mentions", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who the task's open review request is with. `empty` means no open request. `\"me\"` is the caller and their agents: a request made to one of your agents waits on you.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewer", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who asked for the task's open review. `\"me\"` is the caller and their agents.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewRequester", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } } ] }, "TaskSort": { "maxItems": 8, "description": "The order of the results, most significant first. Tasks without a value for a field come last in both directions; the id breaks ties. Default: `sortOrder`, the manual order, or `relevance` when the filter has a `text` condition. `relevance` is a whole order of its own and stands alone (ascending, best match first): a task whose id is the text, then titles that start with the text (accents and case ignored), then the full text rank (title above description), open before closed, most recently updated first. Only a search with a `text` condition takes it.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field" ], "properties": { "field": { "anyOf": [ { "const": "dueAt", "type": "string" }, { "const": "startAt", "type": "string" }, { "const": "priority", "type": "string" }, { "const": "createdAt", "type": "string" }, { "const": "updatedAt", "type": "string" }, { "const": "title", "type": "string" }, { "const": "sortOrder", "type": "string" }, { "const": "relevance", "type": "string" } ] }, "dir": { "default": "asc", "anyOf": [ { "const": "asc", "type": "string" }, { "const": "desc", "type": "string" } ] } } } }, "PrincipalOwner": { "description": "The person an agent works for. Every response that carries a principal has it as `owner`, null for a human.", "type": "object", "required": [ "id", "handle", "name", "avatarUrl" ], "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "description": "The owner's picture, drawn in a badge on the agent's avatar; null without one.", "type": "string" }, { "type": "null" } ] } } } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } } } } ``` # Get a saved view (/docs/projects/api/search/getV1Saved-viewsById) A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/saved-views/{id}", "operation": { "tags": [ "Search" ], "summary": "Get a saved view", "description": "A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Saved-viewsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update a saved view (/docs/projects/api/search/patchV1Saved-viewsById) Partial: an omitted field never changes, `null` clears `groupBy` and `externalId`; a patch that changes nothing records nothing. Whether a view is shared is fixed at creation. Records `saved_view.updated` with only the fields that changed. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/saved-views/{id}", "operation": { "tags": [ "Search" ], "summary": "Update a saved view", "description": "Partial: an omitted field never changes, `null` clears `groupBy` and `externalId`; a patch that changes nothing records nothing. Whether a view is shared is fixed at creation. Records `saved_view.updated` with only the fields that changed. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "slug": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "maxLength": 64, "type": "string" }, "filter": { "$ref": "#/components/schemas/FilterNode" }, "sort": { "$ref": "#/components/schemas/TaskSort" }, "groupBy": { "type": [ "string", "null" ], "enum": [ "status", "assignee", "priority", "label" ] }, "layout": { "type": "string", "enum": [ "list", "kanban", "gantt" ] }, "externalId": { "minLength": 1, "maxLength": 255, "type": [ "string", "null" ] } } } } } }, "operationId": "patchV1Saved-viewsById", "security": [ { "bearerToken": [] } ] } } ], "components": { "schemas": { "FilterNode": { "description": "A task filter: `{ and: [...] }`, `{ or: [...] }`, `{ not: node }` or a condition `{ field, op, value }`. At most 10 levels deep and 200 nodes. `between` is inclusive at both ends.", "anyOf": [ { "additionalProperties": false, "description": "Every child matches.", "type": "object", "required": [ "and" ], "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "At least one child matches.", "type": "object", "required": [ "or" ], "properties": { "or": { "type": "array", "items": { "$ref": "#/components/schemas/FilterNode" } } } }, { "additionalProperties": false, "description": "The child does not match.", "type": "object", "required": [ "not" ], "properties": { "not": { "$ref": "#/components/schemas/FilterNode" } } }, { "additionalProperties": false, "description": "Project id. `includeChildren: true` also matches every descendant of the project(s).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "project", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] }, "includeChildren": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Task status id.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "status", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } } ] } } }, { "additionalProperties": false, "description": "Category of the task's status.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "statusCategory", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "BACKLOG", "type": "string" }, { "const": "TODO", "type": "string" }, { "const": "IN_PROGRESS", "type": "string" }, { "const": "DONE", "type": "string" }, { "const": "CANCELED", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the task is closed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "done", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "`eq` means \"among the assignees\", `neq` \"not among them\"; `empty` means no assignee. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "assignee", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who created the task. `\"me\"` is the caller and their agents: a task one of your agents created counts as yours (for an agent, `\"me\"` is its owner and the owner's agents).", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creator", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } }, { "additionalProperties": false, "description": "Whether the creator is a human or an agent.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "creatorKind", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "HUMAN", "type": "string" }, { "const": "AGENT", "type": "string" } ] } } ] } } }, { "additionalProperties": false, "description": "`eq` means \"has the label\"; `empty` means no label at all.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "label", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Priority, 0 (none) to 5.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "priority", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "minimum": 0, "maximum": 5, "type": "integer" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minimum": 0, "maximum": 5, "type": "integer" } } ] } } }, { "additionalProperties": false, "description": "Due date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "dueAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Start date.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "startAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was completed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "doneAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "When the task was created.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "createdAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "When the task last changed.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "updatedAt", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "lt", "type": "string" }, { "const": "lte", "type": "string" }, { "const": "gt", "type": "string" }, { "const": "gte", "type": "string" }, { "const": "between", "type": "string" } ] }, "value": { "anyOf": [ { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" }, { "minItems": 2, "maxItems": 2, "type": "array", "items": { "description": "A relative date (`now`, `today`/`hoje`, `tomorrow`/`amanhã`, `yesterday`/`ontem`, `startOfWeek`, `endOfWeek`, `startOfMonth`, `endOfMonth`, optionally followed by `+N` or `-N` and `d`, `w` or `m`), a calendar date `YYYY-MM-DD` (the start of that day in the caller's time zone), or an ISO 8601 instant with an offset.", "type": "string" } } ] } } }, { "additionalProperties": false, "description": "Whether the task's own project is archived (not its parent's). The personal views take `false`.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "projectArchived", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Whether the task has a recurrence.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "recurring", "type": "string" }, "op": { "const": "eq", "type": "string" }, "value": { "type": "boolean" } } }, { "additionalProperties": false, "description": "Id of the task in the system it was imported from.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "externalId", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "minLength": 1, "maxLength": 255, "type": "string" }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "minLength": 1, "maxLength": 255, "type": "string" } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Full-text search over the title and the description.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "text", "type": "string" }, "op": { "const": "contains", "type": "string" }, "value": { "minLength": 1, "maxLength": 200, "type": "string" } } }, { "additionalProperties": false, "description": "A user mentioned in the description. `\"me\"` is the caller.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "mentions", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who the task's open review request is with. `empty` means no open request. `\"me\"` is the caller and their agents: a request made to one of your agents waits on you.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewer", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" }, { "const": "empty", "type": "string" }, { "const": "notEmpty", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } }, { "type": "null" } ] } } }, { "additionalProperties": false, "description": "Who asked for the task's open review. `\"me\"` is the caller and their agents.", "type": "object", "required": [ "field", "op" ], "properties": { "field": { "const": "reviewRequester", "type": "string" }, "op": { "anyOf": [ { "const": "eq", "type": "string" }, { "const": "neq", "type": "string" }, { "const": "in", "type": "string" }, { "const": "nin", "type": "string" } ] }, "value": { "anyOf": [ { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] }, { "minItems": 1, "maxItems": 200, "type": "array", "items": { "anyOf": [ { "const": "me", "type": "string" }, { "anyOf": [ { "pattern": "^[0-9]{1,40}$", "type": "string" }, { "minimum": 1, "type": "integer" } ] } ] } } ] } } } ] }, "TaskSort": { "maxItems": 8, "description": "The order of the results, most significant first. Tasks without a value for a field come last in both directions; the id breaks ties. Default: `sortOrder`, the manual order, or `relevance` when the filter has a `text` condition. `relevance` is a whole order of its own and stands alone (ascending, best match first): a task whose id is the text, then titles that start with the text (accents and case ignored), then the full text rank (title above description), open before closed, most recently updated first. Only a search with a `text` condition takes it.", "type": "array", "items": { "additionalProperties": false, "type": "object", "required": [ "field" ], "properties": { "field": { "anyOf": [ { "const": "dueAt", "type": "string" }, { "const": "startAt", "type": "string" }, { "const": "priority", "type": "string" }, { "const": "createdAt", "type": "string" }, { "const": "updatedAt", "type": "string" }, { "const": "title", "type": "string" }, { "const": "sortOrder", "type": "string" }, { "const": "relevance", "type": "string" } ] }, "dir": { "default": "asc", "anyOf": [ { "const": "asc", "type": "string" }, { "const": "desc", "type": "string" } ] } } } }, "PrincipalOwner": { "description": "The person an agent works for. Every response that carries a principal has it as `owner`, null for a human.", "type": "object", "required": [ "id", "handle", "name", "avatarUrl" ], "properties": { "id": { "type": "string" }, "handle": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "avatarUrl": { "anyOf": [ { "description": "The owner's picture, drawn in a badge on the agent's avatar; null without one.", "type": "string" }, { "type": "null" } ] } } } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } } } } ``` # Delete a saved view (/docs/projects/api/search/deleteV1Saved-viewsById) Records `saved_view.deleted`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/saved-views/{id}", "operation": { "tags": [ "Search" ], "summary": "Delete a saved view", "description": "Records `saved_view.deleted`. A view is its owner's alone (anyone else gets a 404, an admin too); `shared: true` makes a view everyone reads and only the admin scope creates, changes or deletes (403 otherwise). A shared view is read with the reader's `me` and time zone. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1Saved-viewsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Tasks of a saved view (/docs/projects/api/search/getV1Saved-viewsByIdTasks) `POST /tasks/search` with the view's filter and sort, for the reader in `tz` (default: the reader's timezone). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/saved-views/{id}/tasks", "operation": { "tags": [ "Search" ], "summary": "Tasks of a saved view", "description": "`POST /tasks/search` with the view's filter and sort, for the reader in `tz` (default: the reader's timezone). Answers `{ data, total, limit, offset, meta: { resolved, tz } }`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } }, { "name": "tz", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 64, "type": "string" } } ], "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "content": { "application/json": { "schema": { "description": "Unprocessable: a field failed validation, or the filter, sort or tz cannot be read (`path` points at it, `code` says why).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Saved-viewsByIdTasks", "security": [ { "bearerToken": [] } ] } } ] } ``` # Create a task (/docs/projects/api/tasks/postV1Tasks) Without `projectId` the task lands in the caller's personal project: a person's own, or, for an agent, its owner's (the agent is still the author). A project the caller cannot see is a 404; someone else's personal project and a merged project are a 422. `statusId` defaults to the default status; a DONE status creates the task completed. `timezone` defaults to the caller's. `startAt`/`dueAt` take an ISO timestamp with an offset (that exact time, `allDay: false`), a `YYYY-MM-DD` date (that whole day, stored as 12:00 in the task's `timezone`) or `hoje`, `amanhã`, `today`, `tomorrow` (the caller's today or tomorrow, whole). Both dates share one `allDay`, so a whole day next to an exact time is a 422. Output is always ISO with the task's offset. The description is markdown: `@handle`s of existing users become `mentionUserIds`, and `descriptionText` is the text without markup. Records `task.created` and one `task.assigned` per assignee. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks", "operation": { "tags": [ "Tasks" ], "summary": "Create a task", "description": "Without `projectId` the task lands in the caller's personal project: a person's own, or, for an agent, its owner's (the agent is still the author). A project the caller cannot see is a 404; someone else's personal project and a merged project are a 422. `statusId` defaults to the default status; a DONE status creates the task completed. `timezone` defaults to the caller's. `startAt`/`dueAt` take an ISO timestamp with an offset (that exact time, `allDay: false`), a `YYYY-MM-DD` date (that whole day, stored as 12:00 in the task's `timezone`) or `hoje`, `amanhã`, `today`, `tomorrow` (the caller's today or tomorrow, whole). Both dates share one `allDay`, so a whole day next to an exact time is a 422. Output is always ISO with the task's offset. The description is markdown: `@handle`s of existing users become `mentionUserIds`, and `descriptionText` is the text without markup. Records `task.created` and one `task.assigned` per assignee. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "projectId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "projectId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "projectId": { "pattern": "^[0-9]{1,40}$", "type": [ "string", "null" ] }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } } }, "operationId": "postV1Tasks", "security": [ { "bearerToken": [] } ] } } ] } ``` # Reorder tasks (/docs/projects/api/tasks/postV1TasksReorder) `ids` (tasks of one project, 422 otherwise) take the order given, as a block where the first of them sits today; the others keep their places. Values are spaced within the gap between the block's neighbours, and when that gap runs out every task of the project is renumbered in steps of 1024. With `statusId` every listed task moves to that status, which completes or reopens it like a PATCH would, including `completionId` per task for one it rolled or closed. `occurrences`, keyed by task id, binds a listed task ALSO moving into DONE to the occurrence it is displaying (its dueAt, or its startAt when it has none) the same way `/complete`'s own `occurrence` does: given, a task whose CURRENT occurrence no longer matches answers with its state as it is instead of rolling it again. Records one `task.reordered` on the first id, with `meta.ids`. Answers `{ data }`: the listed tasks, in the order given. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/reorder", "operation": { "tags": [ "Tasks" ], "summary": "Reorder tasks", "description": "`ids` (tasks of one project, 422 otherwise) take the order given, as a block where the first of them sits today; the others keep their places. Values are spaced within the gap between the block's neighbours, and when that gap runs out every task of the project is renumbered in steps of 1024. With `statusId` every listed task moves to that status, which completes or reopens it like a PATCH would, including `completionId` per task for one it rolled or closed. `occurrences`, keyed by task id, binds a listed task ALSO moving into DONE to the occurrence it is displaying (its dueAt, or its startAt when it has none) the same way `/complete`'s own `occurrence` does: given, a task whose CURRENT occurrence no longer matches answers with its state as it is instead of rolling it again. Records one `task.reordered` on the first id, with `meta.ids`. Answers `{ data }`: the listed tasks, in the order given. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "occurrences": { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 64, "type": [ "string", "null" ] } } } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "occurrences": { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 64, "type": [ "string", "null" ] } } } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "occurrences": { "type": "object", "patternProperties": { "^(.*)$": { "maxLength": 64, "type": [ "string", "null" ] } } } } } } } }, "operationId": "postV1TasksReorder", "security": [ { "bearerToken": [] } ] } } ] } ``` # Get a task (/docs/projects/api/tasks/getV1TasksById) By its id, the task's number in the organization (`#123`), which never changes, not even when the task moves to another project. Carries `project { id, title, kind }` (`kind` is `PERSONAL` for the personal project), `status`, `assignees`, `labels`, `createdBy { id, handle, kind, name, avatarUrl, owner }` (`owner` is whose agent it is, null for a person) and `createdVia`. `recurrence` is the task's rule (null without one); `linksCount`, `commentsCount` and `attachmentsCount` (complete files that are not removed) count what the reader can see, and `completionsCount` the occurrences recorded as completed (the history a recurring task keeps, also after its rule is removed). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Get a task", "description": "By its id, the task's number in the organization (`#123`), which never changes, not even when the task moves to another project. Carries `project { id, title, kind }` (`kind` is `PERSONAL` for the personal project), `status`, `assignees`, `labels`, `createdBy { id, handle, kind, name, avatarUrl, owner }` (`owner` is whose agent it is, null for a person) and `createdVia`. `recurrence` is the task's rule (null without one); `linksCount`, `commentsCount` and `attachmentsCount` (complete files that are not removed) count what the reader can see, and `completionsCount` the occurrences recorded as completed (the history a recurring task keeps, also after its rule is removed).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1TasksById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update a task (/docs/projects/api/tasks/patchV1TasksById) Partial for real: an omitted field never changes. `null` clears `description`, `startAt`, `dueAt` and sets `priority` back to 0; it is a 422 on a required field (`title`, `statusId`, `timezone`). `assigneeIds`/`labelIds` replace the set; `addAssigneeIds`/`removeAssigneeIds` and `addLabelIds`/`removeLabelIds` edit it and may come together, but not next to the replacement (422). Moving `statusId` into a DONE status completes the task and out of DONE reopens it, exactly like `/complete`, including `completionId` on the response for a recurring task and, when the PATCH rolled it, `rolled` (`{ previousDueAt, nextDueAt }`) -- `occurrence` binds it to the occurrence identity the caller is looking at (its dueAt, or its startAt when it has none) the same way, and does the same thing when it no longer matches. `startAt`/`dueAt` take an ISO timestamp with an offset (that exact time, `allDay: false`), a `YYYY-MM-DD` date (that whole day, stored as 12:00 in the task's `timezone`) or `hoje`, `amanhã`, `today`, `tomorrow` (the caller's today or tomorrow, whole). Both dates share one `allDay`, so a whole day next to an exact time is a 422. Output is always ISO with the task's offset. Changing `timezone` keeps a whole day on the same calendar date. A patch that changes nothing records nothing; `task.updated` carries only the fields that changed. `ifUpdatedAt` (the task's `updatedAt` as the caller saw it, an ISO instant compared to the millisecond) makes the PATCH conditional: when the task changed since, nothing is written, not even for a patch that would change nothing, and the answer is a 409 with `current`, the task as it is now. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/tasks/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Update a task", "description": "Partial for real: an omitted field never changes. `null` clears `description`, `startAt`, `dueAt` and sets `priority` back to 0; it is a 422 on a required field (`title`, `statusId`, `timezone`). `assigneeIds`/`labelIds` replace the set; `addAssigneeIds`/`removeAssigneeIds` and `addLabelIds`/`removeLabelIds` edit it and may come together, but not next to the replacement (422). Moving `statusId` into a DONE status completes the task and out of DONE reopens it, exactly like `/complete`, including `completionId` on the response for a recurring task and, when the PATCH rolled it, `rolled` (`{ previousDueAt, nextDueAt }`) -- `occurrence` binds it to the occurrence identity the caller is looking at (its dueAt, or its startAt when it has none) the same way, and does the same thing when it no longer matches. `startAt`/`dueAt` take an ISO timestamp with an offset (that exact time, `allDay: false`), a `YYYY-MM-DD` date (that whole day, stored as 12:00 in the task's `timezone`) or `hoje`, `amanhã`, `today`, `tomorrow` (the caller's today or tomorrow, whole). Both dates share one `allDay`, so a whole day next to an exact time is a 422. Output is always ISO with the task's offset. Changing `timezone` keeps a whole day on the same calendar date. A patch that changes nothing records nothing; `task.updated` carries only the fields that changed. `ifUpdatedAt` (the task's `updatedAt` as the caller saw it, an ISO instant compared to the millisecond) makes the PATCH conditional: when the task changed since, nothing is written, not even for a patch that would change nothing, and the answer is a 409 with `current`, the task as it is now. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: the task changed since `ifUpdatedAt` (then with `current`), or the idempotency key is still running.", "content": { "application/json": { "schema": { "description": "Conflict: the task changed since `ifUpdatedAt` (then with `current`), or the idempotency key is still running.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "current": { "description": "With `ifUpdatedAt`, when the task changed since: the task as it is now, in the shape this route answers." } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] }, "ifUpdatedAt": { "format": "date-time", "maxLength": 64, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] }, "ifUpdatedAt": { "format": "date-time", "maxLength": 64, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 500, "type": "string" }, "statusId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "description": { "maxLength": 50000, "type": [ "string", "null" ] }, "priority": { "anyOf": [ { "minimum": 0, "maximum": 5, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 5, "type": "integer" } ] }, { "type": "null" } ] }, "startAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "dueAt": { "minLength": 1, "maxLength": 64, "type": [ "string", "null" ] }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "assigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeAssigneeIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "labelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "addLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "removeLabelIds": { "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] }, "ifUpdatedAt": { "format": "date-time", "maxLength": 64, "type": "string" } } } } } }, "operationId": "patchV1TasksById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a task (/docs/projects/api/tasks/deleteV1TasksById) Soft delete: the row stays with `deletedAt`, and the task answers 404 and leaves every list from then on. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Delete a task", "description": "Soft delete: the row stays with `deletedAt`, and the task answers 404 and leaves every list from then on. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksById", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's activity (/docs/projects/api/tasks/getV1TasksByIdActivity) The task's own history, newest first, in the shape of `GET /changes` (`id`, `at`, `actor`, `via`, `action`, `before`, `after`, `meta`): every activity whose entity is this task, comments included, except who subscribed or unsubscribed and who reacted to a comment. `{ data, total, limit, offset }`; `limit` defaults to 50 and is capped at 200. A task the caller cannot see is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/activity", "operation": { "tags": [ "Tasks" ], "summary": "List a task's activity", "description": "The task's own history, newest first, in the shape of `GET /changes` (`id`, `at`, `actor`, `via`, `action`, `before`, `after`, `meta`): every activity whose entity is this task, comments included, except who subscribed or unsubscribed and who reacted to a comment. `{ data, total, limit, offset }`; `limit` defaults to 50 and is capped at 200. A task the caller cannot see is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksByIdActivity", "security": [ { "bearerToken": [] } ] } } ] } ``` # List the trash (/docs/projects/api/tasks/getV1TasksTrash) The deleted tasks this caller may see (their project's privacy, deleted projects included), newest deletion first, `{ data, total, limit, offset }`. Each is `{ id, title, project: { id, title, kind, deleted, archived }, deletedAt, deletedBy, purgeAt }`: `purgeAt` is when the task is removed for good, 30 days after its deletion. `limit` defaults to 50 and is capped at 200. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/trash", "operation": { "tags": [ "Tasks" ], "summary": "List the trash", "description": "The deleted tasks this caller may see (their project's privacy, deleted projects included), newest deletion first, `{ data, total, limit, offset }`. Each is `{ id, title, project: { id, title, kind, deleted, archived }, deletedAt, deletedBy, purgeAt }`: `purgeAt` is when the task is removed for good, 30 days after its deletion. `limit` defaults to 50 and is capped at 200.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksTrash", "security": [ { "bearerToken": [] } ] } } ] } ``` # Tick a box of the description (/docs/projects/api/tasks/postV1TasksByIdDescriptionCheckbox) Flips one box of a task list (`- [ ] item`, `- [x] item`): `index` is the box's position among the task list items of the markdown in document order, as the markdown parser reads them (a `[ ]` inside code is not an item; one in a quote or a nested list is), `checked` the state the caller saw it in, `text` the item's text as the caller saw it (what `MarkdownView` shows, without the markup). The current markdown is read again under the lock, and only the character between that item's brackets changes. When that item is no longer there as the caller saw it (someone edited in between), nothing is written and the answer is a 409 with `current`. Anyone who may edit the task may tick its boxes. The write is a description edit: `task.updated` with `description` before and after, the same notifications, and an edit acts only on the mentions it adds, so a box never notifies a mention again. Answers the task. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/description/checkbox", "operation": { "tags": [ "Tasks" ], "summary": "Tick a box of the description", "description": "Flips one box of a task list (`- [ ] item`, `- [x] item`): `index` is the box's position among the task list items of the markdown in document order, as the markdown parser reads them (a `[ ]` inside code is not an item; one in a quote or a nested list is), `checked` the state the caller saw it in, `text` the item's text as the caller saw it (what `MarkdownView` shows, without the markup). The current markdown is read again under the lock, and only the character between that item's brackets changes. When that item is no longer there as the caller saw it (someone edited in between), nothing is written and the answer is a 409 with `current`. Anyone who may edit the task may tick its boxes. The write is a description edit: `task.updated` with `description` before and after, the same notifications, and an edit acts only on the mentions it adds, so a box never notifies a mention again. Answers the task. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: the item is no longer there as the caller saw it (then with `current`), or the idempotency key is still running.", "content": { "application/json": { "schema": { "description": "Conflict: the item is no longer there as the caller saw it (then with `current`), or the idempotency key is still running.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "current": { "description": "When the item changed since: the task as it is now, in the shape this route answers." } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } } } }, "operationId": "postV1TasksByIdDescriptionCheckbox", "security": [ { "bearerToken": [] } ] } } ] } ``` # Restore a task from the trash (/docs/projects/api/tasks/postV1TasksByIdRestore) Brings the task back as it was, with its comments, links, files, labels, assignees, dates and the notifications that were unread. A task of a deleted or archived project goes to the project it was merged into when the caller sees that one, otherwise to the caller's personal project. A subtask whose parent is still in the trash comes back on its own, and is a subtask again once the parent is restored. A review request the deletion ended stays ended. A task that is not in the trash answers as it is. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/restore", "operation": { "tags": [ "Tasks" ], "summary": "Restore a task from the trash", "description": "Brings the task back as it was, with its comments, links, files, labels, assignees, dates and the notifications that were unread. A task of a deleted or archived project goes to the project it was merged into when the caller sees that one, otherwise to the caller's personal project. A subtask whose parent is still in the trash comes back on its own, and is a subtask again once the parent is restored. A review request the deletion ended stays ended. A task that is not in the trash answers as it is. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1TasksByIdRestore", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a task in the trash for good (/docs/projects/api/tasks/postV1TasksByIdPurge) Removes a task in the trash now, as the 30-day purge does: its comments, links, activity, notifications, reminders, completions and review requests, and its files with the next attachments sweep. Irreversible. A task outside the trash answers 404. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/purge", "operation": { "tags": [ "Tasks" ], "summary": "Delete a task in the trash for good", "description": "Removes a task in the trash now, as the 30-day purge does: its comments, links, activity, notifications, reminders, completions and review requests, and its files with the next attachments sweep. Irreversible. A task outside the trash answers 404. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1TasksByIdPurge", "security": [ { "bearerToken": [] } ] } } ] } ``` # Complete a task (/docs/projects/api/tasks/postV1TasksByIdComplete) Stamps `doneAt` and `doneById` and moves the task to the first DONE status by `sortOrder`. Idempotent: completing a task that is already done, whoever asks, answers 200 with it as it is and records nothing. `note` is kept on the `task.completed` activity. Answers `{ task, rolled }`. A task with a recurrence rule rolls instead: the occurrence is recorded in its completions, the task moves to its next date and stays open, `task.rolled` is recorded and `rolled` is `{ previousDueAt, nextDueAt }` (null otherwise); completing an occurrence already completed changes nothing, and a series with no next date completes the task. Moving it into a DONE status through PATCH or reorder does the same. `occurrence` binds the request to the occurrence identity the caller is looking at (its dueAt, or its startAt when it has no due date -- so a due-less recurring task is covered too): given, a task whose CURRENT occurrence no longer matches answers 200 with the task as it is instead of rolling it, exactly like completing an occurrence already completed -- this is what keeps a lost response's retry from rolling the NEXT occurrence too. Omitted, nothing changes from before this field existed. For a recurring task, also answers `completionId`: the completion this call recorded or found, to pass back as `undoCompletionId` on `/reopen` so that undo can check it is still undoing THIS completion, not just whichever is last. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/complete", "operation": { "tags": [ "Tasks" ], "summary": "Complete a task", "description": "Stamps `doneAt` and `doneById` and moves the task to the first DONE status by `sortOrder`. Idempotent: completing a task that is already done, whoever asks, answers 200 with it as it is and records nothing. `note` is kept on the `task.completed` activity. Answers `{ task, rolled }`. A task with a recurrence rule rolls instead: the occurrence is recorded in its completions, the task moves to its next date and stays open, `task.rolled` is recorded and `rolled` is `{ previousDueAt, nextDueAt }` (null otherwise); completing an occurrence already completed changes nothing, and a series with no next date completes the task. Moving it into a DONE status through PATCH or reorder does the same. `occurrence` binds the request to the occurrence identity the caller is looking at (its dueAt, or its startAt when it has no due date -- so a due-less recurring task is covered too): given, a task whose CURRENT occurrence no longer matches answers 200 with the task as it is instead of rolling it, exactly like completing an occurrence already completed -- this is what keeps a lost response's retry from rolling the NEXT occurrence too. Omitted, nothing changes from before this field existed. For a recurring task, also answers `completionId`: the completion this call recorded or found, to pass back as `undoCompletionId` on `/reopen` so that undo can check it is still undoing THIS completion, not just whichever is last. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "maxLength": 5000, "type": "string" }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "note": { "maxLength": 5000, "type": "string" }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "note": { "maxLength": 5000, "type": "string" }, "occurrence": { "maxLength": 64, "type": [ "string", "null" ] } } } } } }, "operationId": "postV1TasksByIdComplete", "security": [ { "bearerToken": [] } ] } } ] } ``` # Reopen a task (/docs/projects/api/tasks/postV1TasksByIdReopen) Clears `doneAt` and `doneById` and moves the task back to the default status; a cancelled task also goes back to the default status, recorded as a `task.updated` of `statusId` (it had no `doneAt`). Idempotent: an open task (neither done nor in a DONE or CANCELED status) answers 200 as it is, except a recurring one, where reopen undoes the last roll (the dates go back and that completion is deleted) while the task still has the date the roll gave it, and is a 422 otherwise. `undoCompletionId` (the `completionId` a prior `complete` answered with) makes that check exact instead of "whatever roll is last": given, a completion no longer in that position (superseded by a later one) also answers the 422, so a stale toast can never undo the WRONG roll. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/reopen", "operation": { "tags": [ "Tasks" ], "summary": "Reopen a task", "description": "Clears `doneAt` and `doneById` and moves the task back to the default status; a cancelled task also goes back to the default status, recorded as a `task.updated` of `statusId` (it had no `doneAt`). Idempotent: an open task (neither done nor in a DONE or CANCELED status) answers 200 as it is, except a recurring one, where reopen undoes the last roll (the dates go back and that completion is deleted) while the task still has the date the roll gave it, and is a 422 otherwise. `undoCompletionId` (the `completionId` a prior `complete` answered with) makes that check exact instead of \"whatever roll is last\": given, a completion no longer in that position (superseded by a later one) also answers the 422, so a stale toast can never undo the WRONG roll. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "undoCompletionId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "undoCompletionId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "undoCompletionId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1TasksByIdReopen", "security": [ { "bearerToken": [] } ] } } ] } ``` # Move a task to another project (/docs/projects/api/tasks/postV1TasksByIdMove) The id stays the same, so `#123` keeps resolving. The task goes last in the target. A project the caller cannot see is a 404; someone else's personal project (even for an admin) and a merged project are a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/move", "operation": { "tags": [ "Tasks" ], "summary": "Move a task to another project", "description": "The id stays the same, so `#123` keeps resolving. The task goes last in the target. A project the caller cannot see is a 404; someone else's personal project (even for an admin) and a merged project are a 422. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "projectId" ], "properties": { "projectId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "projectId" ], "properties": { "projectId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "projectId" ], "properties": { "projectId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1TasksByIdMove", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a project's tasks (/docs/projects/api/tasks/getV1ProjectsByIdTasks) The tasks of one project in manual order (`sortOrder`, then id), `{ data, total, limit, offset }`. `done=false` keeps the open ones, `done=true` the closed ones (completed, or in a CANCELED status), and without it both. `limit` defaults to 50 and is capped at 200. Deleted tasks never appear. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}/tasks", "operation": { "tags": [ "Tasks" ], "summary": "List a project's tasks", "description": "The tasks of one project in manual order (`sortOrder`, then id), `{ data, total, limit, offset }`. `done=false` keeps the open ones, `done=true` the closed ones (completed, or in a CANCELED status), and without it both. `limit` defaults to 50 and is capped at 200. Deleted tasks never appear.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "done", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1ProjectsByIdTasks", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's links (/docs/projects/api/tasks/getV1TasksByIdLinks) `{ data }`, oldest first. A link is `{ id, kind, direction, task: { id, title, projectId, doneAt }, createdAt }` from the point of view of the task in the path: for `B` of an `A BLOCKS B`, `kind` is `BLOCKED_BY` and `direction` is `in`. A link whose other task the caller cannot see (a private project, the trash) is never shown, counted or named. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/links", "operation": { "tags": [ "Tasks" ], "summary": "List a task's links", "description": "`{ data }`, oldest first. A link is `{ id, kind, direction, task: { id, title, projectId, doneAt }, createdAt }` from the point of view of the task in the path: for `B` of an `A BLOCKS B`, `kind` is `BLOCKED_BY` and `direction` is `in`. A link whose other task the caller cannot see (a private project, the trash) is never shown, counted or named.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1TasksByIdLinks", "security": [ { "bearerToken": [] } ] } } ] } ``` # Link two tasks (/docs/projects/api/tasks/postV1TasksByIdLinks) `kind` is one of the canonical kinds (`RELATED`, `SUBTASK_OF`, `BLOCKS`, `PRECEDES`, `DUPLICATE_OF`, `COPIED_FROM`, `REFERENCES`) or an inverse (`PARENT_OF`, `BLOCKED_BY`, `FOLLOWS`, `DUPLICATED_BY`, `COPIED_TO`, `REFERENCED_BY`), which is stored as its canonical kind with the sides swapped; `RELATED` is symmetric and stored once. 201 with the new link, 200 with the existing one when the same link already exists in either spelling. A task linked to itself, and a `SUBTASK_OF` that would close a cycle at any depth, are a 422; a task the caller cannot see, on either side, is a 404. Records `link.created` on the link, with both sides and the canonical kind in `meta`. A link is `{ id, kind, direction, task: { id, title, projectId, doneAt }, createdAt }` from the point of view of the task in the path: for `B` of an `A BLOCKS B`, `kind` is `BLOCKED_BY` and `direction` is `in`. A link whose other task the caller cannot see (a private project, the trash) is never shown, counted or named. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/links", "operation": { "tags": [ "Tasks" ], "summary": "Link two tasks", "description": "`kind` is one of the canonical kinds (`RELATED`, `SUBTASK_OF`, `BLOCKS`, `PRECEDES`, `DUPLICATE_OF`, `COPIED_FROM`, `REFERENCES`) or an inverse (`PARENT_OF`, `BLOCKED_BY`, `FOLLOWS`, `DUPLICATED_BY`, `COPIED_TO`, `REFERENCED_BY`), which is stored as its canonical kind with the sides swapped; `RELATED` is symmetric and stored once. 201 with the new link, 200 with the existing one when the same link already exists in either spelling. A task linked to itself, and a `SUBTASK_OF` that would close a cycle at any depth, are a 422; a task the caller cannot see, on either side, is a 404. Records `link.created` on the link, with both sides and the canonical kind in `meta`. A link is `{ id, kind, direction, task: { id, title, projectId, doneAt }, createdAt }` from the point of view of the task in the path: for `B` of an `A BLOCKS B`, `kind` is `BLOCKED_BY` and `direction` is `in`. A link whose other task the caller cannot see (a private project, the trash) is never shown, counted or named. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "toTaskId", "kind" ], "properties": { "toTaskId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "kind": { "type": "string", "enum": [ "RELATED", "SUBTASK_OF", "BLOCKS", "PRECEDES", "DUPLICATE_OF", "COPIED_FROM", "REFERENCES", "PARENT_OF", "BLOCKED_BY", "FOLLOWS", "DUPLICATED_BY", "COPIED_TO", "REFERENCED_BY" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "toTaskId", "kind" ], "properties": { "toTaskId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "kind": { "type": "string", "enum": [ "RELATED", "SUBTASK_OF", "BLOCKS", "PRECEDES", "DUPLICATE_OF", "COPIED_FROM", "REFERENCES", "PARENT_OF", "BLOCKED_BY", "FOLLOWS", "DUPLICATED_BY", "COPIED_TO", "REFERENCED_BY" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "toTaskId", "kind" ], "properties": { "toTaskId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "kind": { "type": "string", "enum": [ "RELATED", "SUBTASK_OF", "BLOCKS", "PRECEDES", "DUPLICATE_OF", "COPIED_FROM", "REFERENCES", "PARENT_OF", "BLOCKED_BY", "FOLLOWS", "DUPLICATED_BY", "COPIED_TO", "REFERENCED_BY" ] } } } } } }, "operationId": "postV1TasksByIdLinks", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove a link (/docs/projects/api/tasks/deleteV1TasksByIdLinksByLinkId) From either of its two tasks. A link that is not the task's, or whose other task the caller cannot see, is a 404. Records `link.deleted` with both sides and the canonical kind. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}/links/{linkId}", "operation": { "tags": [ "Tasks" ], "summary": "Remove a link", "description": "From either of its two tasks. A link that is not the task's, or whose other task the caller cannot see, is a 404. Records `link.deleted` with both sides and the canonical kind. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "linkId", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksByIdLinksByLinkId", "security": [ { "bearerToken": [] } ] } } ] } ``` # Resolve task and project references (/docs/projects/api/tasks/getV1References) What the `#123` references and the pasted app links of a markdown text stand for: `tasks` and `projects` are comma-separated ids, up to 100 of each. Answers `{ data: { tasks: [{ id, title, projectId, closed }], projects: [{ id, title, kind }] } }`, where `closed` is `DONE`, `CANCELED` or `null`. An id the caller cannot see (none such, in the trash, in a project hidden from them) is left out, the same way in every case, so the answer never says that a hidden task or project exists. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/references", "operation": { "tags": [ "Tasks" ], "summary": "Resolve task and project references", "description": "What the `#123` references and the pasted app links of a markdown text stand for: `tasks` and `projects` are comma-separated ids, up to 100 of each. Answers `{ data: { tasks: [{ id, title, projectId, closed }], projects: [{ id, title, kind }] } }`, where `closed` is `DONE`, `CANCELED` or `null`. An id the caller cannot see (none such, in the trash, in a project hidden from them) is left out, the same way in every case, so the answer never says that a hidden task or project exists.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "tasks", "in": "query", "required": false, "schema": { "pattern": "^[0-9]{1,40}(,[0-9]{1,40}){0,99}$", "type": "string" } }, { "name": "projects", "in": "query", "required": false, "schema": { "pattern": "^[0-9]{1,40}(,[0-9]{1,40}){0,99}$", "type": "string" } } ], "operationId": "getV1References", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's subscribers (/docs/projects/api/tasks/getV1TasksByIdSubscribers) `{ data }`, oldest subscription first, active users only. This is the list a new comment is announced to. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the task (`AUTHOR`, `ASSIGNEE`, `COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/subscribers", "operation": { "tags": [ "Tasks" ], "summary": "List a task's subscribers", "description": "`{ data }`, oldest subscription first, active users only. This is the list a new comment is announced to. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the task (`AUTHOR`, `ASSIGNEE`, `COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1TasksByIdSubscribers", "security": [ { "bearerToken": [] } ] } } ] } ``` # Unsubscribe from a task (/docs/projects/api/tasks/deleteV1TasksByIdSubscription) Removes the caller whatever their reasons. Idempotent. A later assignment, mention or comment subscribes them again. Records `subscription.removed` when there was something to remove. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}/subscription", "operation": { "tags": [ "Tasks" ], "summary": "Unsubscribe from a task", "description": "Removes the caller whatever their reasons. Idempotent. A later assignment, mention or comment subscribes them again. Records `subscription.removed` when there was something to remove. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksByIdSubscription", "security": [ { "bearerToken": [] } ] } } ] } ``` # Subscribe to a task (/docs/projects/api/tasks/putV1TasksByIdSubscription) Subscribes the caller with the reason `MANUAL`, kept next to any reason they already had. Idempotent. Records `subscription.added` when it changes something. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the task (`AUTHOR`, `ASSIGNEE`, `COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/tasks/{id}/subscription", "operation": { "tags": [ "Tasks" ], "summary": "Subscribe to a task", "description": "Subscribes the caller with the reason `MANUAL`, kept next to any reason they already had. Idempotent. Records `subscription.added` when it changes something. A subscriber is `{ user: { id, handle, name, kind }, reason, reasons, createdAt }`: `reasons` are every reason the person follows the task (`AUTHOR`, `ASSIGNEE`, `COMMENTER`, `MENTIONED`, `MANUAL`) in the order they were acquired, and `reason` is the most recent of them. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "putV1TasksByIdSubscription", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's reminders (/docs/projects/api/tasks/getV1TasksByIdReminders) `{ data }`, oldest first. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/reminders", "operation": { "tags": [ "Tasks" ], "summary": "List a task's reminders", "description": "`{ data }`, oldest first. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1TasksByIdReminders", "security": [ { "bearerToken": [] } ] } } ] } ``` # Add a reminder to a task (/docs/projects/api/tasks/postV1TasksByIdReminders) `{ remindAt }` (an ISO instant with its offset, in the future) or `{ relativeTo, relativeSeconds }` (`-3600` is an hour before). `userId` names who is reminded, an active person who can see the task; by default the caller (an agent reminds its owner). At most 20 per task. Records `reminder.added`. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/reminders", "operation": { "tags": [ "Tasks" ], "summary": "Add a reminder to a task", "description": "`{ remindAt }` (an ISO instant with its offset, in the future) or `{ relativeTo, relativeSeconds }` (`-3600` is an hour before). `userId` names who is reminded, an active person who can see the task; by default the caller (an agent reminds its owner). At most 20 per task. Records `reminder.added`. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A reminder rule refused the body (`code` names it), or the body failed the schema.", "content": { "application/json": { "schema": { "description": "A reminder rule refused the body (`code` names it), or the body failed the schema.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "reminder_shape", "reminder_in_past", "reminder_offset", "reminder_recipient", "reminder_not_a_member", "reminder_limit" ] } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1TasksByIdReminders", "security": [ { "bearerToken": [] } ] } } ] } ``` # Change a reminder (/docs/projects/api/tasks/patchV1TasksByIdRemindersByReminderId) Any subset of the POST's fields. `remindAt` makes it absolute and `relativeTo`/`relativeSeconds` relative, replacing the other shape's fields; a relative one can change only its anchor or only its offset. `remindAt` must be in the future when it is sent; `userId` is checked like the POST's when it changes. The reminder keeps its id, and what it had scheduled moves with it: it never fires at the old moment, and an occurrence that already fired does not fire again. A body that changes nothing writes nothing. Records `reminder.updated` with `before` and `after`. Whoever may remove a reminder may change it. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/tasks/{id}/reminders/{reminderId}", "operation": { "tags": [ "Tasks" ], "summary": "Change a reminder", "description": "Any subset of the POST's fields. `remindAt` makes it absolute and `relativeTo`/`relativeSeconds` relative, replacing the other shape's fields; a relative one can change only its anchor or only its offset. `remindAt` must be in the future when it is sent; `userId` is checked like the POST's when it changes. The reminder keeps its id, and what it had scheduled moves with it: it never fires at the old moment, and an occurrence that already fired does not fire again. A body that changes nothing writes nothing. Records `reminder.updated` with `before` and `after`. Whoever may remove a reminder may change it. A reminder is `{ id, taskId, user, kind, remindAt, relativeTo, relativeSeconds, nextFireAt, createdById, createdAt }`. `ABSOLUTE` fires once at `remindAt`; `RELATIVE` fires at the task's due (`DUE`) or start (`START`) date plus `relativeSeconds` (negative is before), once per occurrence: completing a recurring task moves it to the next one. `nextFireAt` is when it fires for the task as it is now, null when it will not (a closed task, an empty date, a moment already past). It reaches the person on the channels they keep for reminders. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "A reminder rule refused the body (`code` names it), or the body failed the schema.", "content": { "application/json": { "schema": { "description": "A reminder rule refused the body (`code` names it), or the body failed the schema.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "reminder_shape", "reminder_in_past", "reminder_offset", "reminder_recipient", "reminder_not_a_member", "reminder_limit" ] } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "reminderId", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "properties": { "remindAt": { "maxLength": 40, "type": "string" }, "relativeTo": { "type": "string", "enum": [ "DUE", "START" ] }, "relativeSeconds": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "userId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "patchV1TasksByIdRemindersByReminderId", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove a reminder (/docs/projects/api/tasks/deleteV1TasksByIdRemindersByReminderId) Cancels whatever it still had scheduled. Records `reminder.removed`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}/reminders/{reminderId}", "operation": { "tags": [ "Tasks" ], "summary": "Remove a reminder", "description": "Cancels whatever it still had scheduled. Records `reminder.removed`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "reminderId", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksByIdRemindersByReminderId", "security": [ { "bearerToken": [] } ] } } ] } ``` # Request a review of a task (/docs/projects/api/tasks/postV1TasksByIdReview) Asks `approverId`, a person or an agent, to approve the task. Anyone who can edit the task can ask. `onApprove` says what approving will do: `complete` completes the task as the approver (a recurring task records the occurrence and rolls), `return` ends the request as approved and leaves the task open, back with whoever asked, who is notified. Omitted, it is `return` when whoever asks is one of the task's assignees (an agent counts as its owner) and `complete` otherwise; any other value is a 422. Refused with a 422 for yourself or one of your own agents (an agent may ask its owner), for someone who is not an active user, for someone who cannot see the task (asking never grants access) and on a closed task; a 409 while another request is open. The task stays open, with its status and assignees, and leaves Today for whoever is assigned or asked. Records `review.requested`, and the approver is notified. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/review", "operation": { "tags": [ "Tasks" ], "summary": "Request a review of a task", "description": "Asks `approverId`, a person or an agent, to approve the task. Anyone who can edit the task can ask. `onApprove` says what approving will do: `complete` completes the task as the approver (a recurring task records the occurrence and rolls), `return` ends the request as approved and leaves the task open, back with whoever asked, who is notified. Omitted, it is `return` when whoever asks is one of the task's assignees (an agent counts as its owner) and `complete` otherwise; any other value is a 422. Refused with a 422 for yourself or one of your own agents (an agent may ask its owner), for someone who is not an active user, for someone who cannot see the task (asking never grants access) and on a closed task; a 409 while another request is open. The task stays open, with its status and assignees, and leaves Today for whoever is assigned or asked. Records `review.requested`, and the approver is notified. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "approverId" ], "properties": { "approverId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 2000, "type": [ "string", "null" ] }, "onApprove": { "maxLength": 32, "description": "`complete` or `return`: what approving will do. Omitted or null: `return` when you are (as a person, an agent counting as its owner) one of the task's assignees, `complete` otherwise.", "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "required": [ "approverId" ], "properties": { "approverId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 2000, "type": [ "string", "null" ] }, "onApprove": { "maxLength": 32, "description": "`complete` or `return`: what approving will do. Omitted or null: `return` when you are (as a person, an agent counting as its owner) one of the task's assignees, `complete` otherwise.", "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "required": [ "approverId" ], "properties": { "approverId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 2000, "type": [ "string", "null" ] }, "onApprove": { "maxLength": 32, "description": "`complete` or `return`: what approving will do. Omitted or null: `return` when you are (as a person, an agent counting as its owner) one of the task's assignees, `complete` otherwise.", "type": [ "string", "null" ] } } } } } }, "operationId": "postV1TasksByIdReview", "security": [ { "bearerToken": [] } ] } } ] } ``` # Cancel a task's review request (/docs/projects/api/tasks/deleteV1TasksByIdReview) Only whoever asked (or one of their agents) cancels; anyone else is a 403. Idempotent: with no open request it answers the task as it is and records nothing. `?reviewId=` is optional here: sent, the open request has to be that one, or the call is a 409 and nothing is cancelled. Records `review.canceled`, and the approver is notified. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}/review", "operation": { "tags": [ "Tasks" ], "summary": "Cancel a task's review request", "description": "Only whoever asked (or one of their agents) cancels; anyone else is a 403. Idempotent: with no open request it answers the task as it is and records nothing. `?reviewId=` is optional here: sent, the open request has to be that one, or the call is a 409 and nothing is cancelled. Records `review.canceled`, and the approver is notified. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "reviewId", "in": "query", "required": false, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksByIdReview", "security": [ { "bearerToken": [] } ] } } ] } ``` # Approve a task under review (/docs/projects/api/tasks/postV1TasksByIdReviewApprove) Approving does what the request declared (`review.onApprove`), and the answer says which in `effect`. With `return` the request ends as approved and the task stays open, on the same occurrence, nothing completed and nothing rolled, with its assignees as they were: it answers `{ task, rolled: null, effect: "return" }`, and whoever asked is notified that it is back with them. With `complete` approving completes the task, as the approver, through `POST /tasks/:id/complete`'s own path: it answers the same `{ task, rolled, completionId }` with `effect: "complete"`, a recurring task records the occurrence (whose completion keeps `review`, who approved and who asked) and rolls to its next date with no request, "repeat from completion" counts from now, and `POST /tasks/:id/reopen` undoes it, restoring the occurrence open and without the request. Only the approver named in the request (or one of their agents): anyone else is a 403, and a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. `note` is kept on both activities. Records `review.approved` and the completion's own activity, and whoever asked is notified. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/review/approve", "operation": { "tags": [ "Tasks" ], "summary": "Approve a task under review", "description": "Approving does what the request declared (`review.onApprove`), and the answer says which in `effect`. With `return` the request ends as approved and the task stays open, on the same occurrence, nothing completed and nothing rolled, with its assignees as they were: it answers `{ task, rolled: null, effect: \"return\" }`, and whoever asked is notified that it is back with them. With `complete` approving completes the task, as the approver, through `POST /tasks/:id/complete`'s own path: it answers the same `{ task, rolled, completionId }` with `effect: \"complete\"`, a recurring task records the occurrence (whose completion keeps `review`, who approved and who asked) and rolls to its next date with no request, \"repeat from completion\" counts from now, and `POST /tasks/:id/reopen` undoes it, restoring the occurrence open and without the request. Only the approver named in the request (or one of their agents): anyone else is a 403, and a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. `note` is kept on both activities. Records `review.approved` and the completion's own activity, and whoever asked is notified. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 5000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 5000, "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "note": { "maxLength": 5000, "type": "string" } } } } } }, "operationId": "postV1TasksByIdReviewApprove", "security": [ { "bearerToken": [] } ] } } ] } ``` # Ask for changes on a task under review (/docs/projects/api/tasks/postV1TasksByIdReviewRequest-changes) `comment` is required (a blank one is a 422) and is written as a comment on the task, by the approver. The request is cleared and the task stays open, in its status and with its assignees, who are notified along with whoever asked; nothing rolls. Only the approver named in the request (or one of their agents): anyone else is a 403, and a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. Records `comment.created` and `review.changes_requested`. Answers `{ task, comment }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/review/request-changes", "operation": { "tags": [ "Tasks" ], "summary": "Ask for changes on a task under review", "description": "`comment` is required (a blank one is a 422) and is written as a comment on the task, by the approver. The request is cleared and the task stays open, in its status and with its assignees, who are notified along with whoever asked; nothing rolls. Only the approver named in the request (or one of their agents): anyone else is a 403, and a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. Records `comment.created` and `review.changes_requested`. Answers `{ task, comment }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId", "comment" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "comment": { "maxLength": 50000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId", "comment" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "comment": { "maxLength": 50000, "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId", "comment" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "comment": { "maxLength": 50000, "type": "string" } } } } } }, "operationId": "postV1TasksByIdReviewRequest-changes", "security": [ { "bearerToken": [] } ] } } ] } ``` # Tell the approver again about a review request (/docs/projects/api/tasks/postV1TasksByIdReviewNudge) "Cobrar": whoever asked (or one of their agents) has the approver notified again. Anyone else is a 403, a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. At most one signal a day reaches the approver from a request, on the approver's own calendar: on a day the request was made, a reminder went out or it was already nudged, this is a 409 that says so, with `nudgeAvailableAt`, the start of the approver's next day, when one can go again. It also restarts the count to the approver's next reminder (every 2 business days while the request sits). Records `review.nudged`; the task reads the same. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/review/nudge", "operation": { "tags": [ "Tasks" ], "summary": "Tell the approver again about a review request", "description": "\"Cobrar\": whoever asked (or one of their agents) has the approver notified again. Anyone else is a 403, a task with no open request a 409. `reviewId` is the `review.id` the caller read on the task: an answer is to that request, and if the task's open request is another one by now (the one answered ended and a new one was made) nothing is written and the call is a 409, so read the task again. At most one signal a day reaches the approver from a request, on the approver's own calendar: on a day the request was made, a reminder went out or it was already nudged, this is a 409 that says so, with `nudgeAvailableAt`, the start of the approver's next day, when one can go again. It also restarts the count to the approver's next reminder (every 2 business days while the request sits). Records `review.nudged`; the task reads the same. Answers `{ task }`. A task under review stays open and carries `review`: `{ id, approver, requestedBy, requestedAt, note, onApprove, approverToldToday, nudgeAvailableAt }`, null without an open request; `onApprove` is what approving will do (`complete` or `return`, as whoever asked declared it), and `requestedBy.owner` the person behind an agent that asked; `approverToldToday` says the approver already heard of the request today (it was made, a reminder went out or it was nudged), so `POST /tasks/:id/review/nudge` would be a 409 until `nudgeAvailableAt`, the start of the approver's next day on their calendar (null while a nudge can go). A task has at most one. Who a request is with, and whose it is, is a person: an agent acts for its owner, so the approver's agents answer for them and the requester's agents cancel for them, and nobody else does, an admin included. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: no open request, or the approver was already told today (then with `nudgeAvailableAt`).", "content": { "application/json": { "schema": { "description": "Conflict: no open request, or the approver was already told today (then with `nudgeAvailableAt`).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "nudgeAvailableAt": { "format": "date-time", "description": "On a refusal for the day: when a nudge can go again, the start of the approver's next day on their calendar.", "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "required": [ "reviewId" ], "properties": { "reviewId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1TasksByIdReviewNudge", "security": [ { "bearerToken": [] } ] } } ] } ``` # Who can review a task (/docs/projects/api/tasks/getV1TasksByIdReviewApprovers) The people and agents `POST /tasks/:id/review` would accept as the approver of this task, searched like `GET /people` (`q`, `kind`, `limit`, `offset`, the same page): active, able to see the task (an agent through its owner), and neither the caller nor one of the caller's agents. A task the caller cannot see is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/review/approvers", "operation": { "tags": [ "Tasks" ], "summary": "Who can review a task", "description": "The people and agents `POST /tasks/:id/review` would accept as the approver of this task, searched like `GET /people` (`q`, `kind`, `limit`, `offset`, the same page): active, able to see the task (an agent through its owner), and neither the caller nor one of the caller's agents. A task the caller cannot see is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "q", "in": "query", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "HUMAN", "AGENT" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksByIdReviewApprovers", "security": [ { "bearerToken": [] } ] } } ] } ``` # List task statuses (/docs/projects/api/tasks/getV1Statuses) The statuses of a workflow, in order: `{ data: [{ id, workflowId, name, category, color, sortOrder, isDefault, externalId }], defaultWorkflowId }`. `category` is one of BACKLOG, TODO, IN_PROGRESS, DONE, CANCELED. Without `projectId`, the default workflow's; with it, the statuses a task of that project can take (404 when the project is not visible). With `all=true`, every workflow's, the default one's first: a task's statuses are those whose `workflowId` is its status's. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/statuses", "operation": { "tags": [ "Tasks" ], "summary": "List task statuses", "description": "The statuses of a workflow, in order: `{ data: [{ id, workflowId, name, category, color, sortOrder, isDefault, externalId }], defaultWorkflowId }`. `category` is one of BACKLOG, TODO, IN_PROGRESS, DONE, CANCELED. Without `projectId`, the default workflow's; with it, the statuses a task of that project can take (404 when the project is not visible). With `all=true`, every workflow's, the default one's first: a task's statuses are those whose `workflowId` is its status's.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "all", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } } ], "operationId": "getV1Statuses", "security": [ { "bearerToken": [] } ] } } ] } ``` # Replace the task statuses (/docs/projects/api/tasks/putV1Statuses) The default workflow's whole list, bare or as `{ statuses }` or `{ data }` (what GET answers). An entry with `id` updates that status, one without creates a status, and a status left out is deleted. The order is the list's, or `sortOrder` when every entry carries one; either way stored in steps of 1024. A 422 changes nothing: exactly one default is required and it cannot be DONE or CANCELED, at least one DONE status is required, an id must exist and appear once, a status that tasks use cannot be removed nor move into or out of DONE. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/statuses", "operation": { "tags": [ "Tasks" ], "summary": "Replace the task statuses", "description": "The default workflow's whole list, bare or as `{ statuses }` or `{ data }` (what GET answers). An entry with `id` updates that status, one without creates a status, and a status left out is deleted. The order is the list's, or `sortOrder` when every entry carries one; either way stored in steps of 1024. A 422 changes nothing: exactly one default is required and it cannot be DONE or CANCELED, at least one DONE status is required, an id must exist and appear once, a status that tasks use cannot be removed nor move into or out of DONE. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } } } }, "operationId": "putV1Statuses", "security": [ { "bearerToken": [] } ] } } ] } ``` # List workflows (/docs/projects/api/tasks/getV1Workflows) Every workflow, the default one first. A workflow is an ordered list of statuses that projects use (docs/data-model.md): `{ id, name, isDefault, statuses, projectCount, projects, canEdit }`, where `projects` are the ones the caller sees and `canEdit` whether the caller may rename it, change its statuses or delete it (an admin, or the owner of every project using it; a workflow no project uses, any writer; the default workflow, an admin only). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/workflows", "operation": { "tags": [ "Tasks" ], "summary": "List workflows", "description": "Every workflow, the default one first. A workflow is an ordered list of statuses that projects use (docs/data-model.md): `{ id, name, isDefault, statuses, projectCount, projects, canEdit }`, where `projects` are the ones the caller sees and `canEdit` whether the caller may rename it, change its statuses or delete it (an admin, or the owner of every project using it; a workflow no project uses, any writer; the default workflow, an admin only).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Workflows", "security": [ { "bearerToken": [] } ] } } ] } ``` # Create a workflow (/docs/projects/api/tasks/postV1Workflows) A new workflow named `name` with a copy of the statuses of `copyFromId` (a project's `workflowId` duplicates that project's statuses), or of the default workflow. It starts with no project; put one on it with `PUT /projects/:id/workflow`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/workflows", "operation": { "tags": [ "Tasks" ], "summary": "Create a workflow", "description": "A new workflow named `name` with a copy of the statuses of `copyFromId` (a project's `workflowId` duplicates that project's statuses), or of the default workflow. It starts with no project; put one on it with `PUT /projects/:id/workflow`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "copyFromId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "copyFromId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "copyFromId": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } }, "operationId": "postV1Workflows", "security": [ { "bearerToken": [] } ] } } ] } ``` # Get a workflow (/docs/projects/api/tasks/getV1WorkflowsById) A workflow is an ordered list of statuses that projects use (docs/data-model.md): `{ id, name, isDefault, statuses, projectCount, projects, canEdit }`, where `projects` are the ones the caller sees and `canEdit` whether the caller may rename it, change its statuses or delete it (an admin, or the owner of every project using it; a workflow no project uses, any writer; the default workflow, an admin only). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/workflows/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Get a workflow", "description": "A workflow is an ordered list of statuses that projects use (docs/data-model.md): `{ id, name, isDefault, statuses, projectCount, projects, canEdit }`, where `projects` are the ones the caller sees and `canEdit` whether the caller may rename it, change its statuses or delete it (an admin, or the owner of every project using it; a workflow no project uses, any writer; the default workflow, an admin only).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1WorkflowsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Rename a workflow (/docs/projects/api/tasks/patchV1WorkflowsById) 403 when the caller may not change it (`canEdit`). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/workflows/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Rename a workflow", "description": "403 when the caller may not change it (`canEdit`). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "minLength": 1, "maxLength": 100, "type": "string" } } } } } }, "operationId": "patchV1WorkflowsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a workflow (/docs/projects/api/tasks/deleteV1WorkflowsById) Only one no project uses, and never the default one (422). 403 when the caller may not change it. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/workflows/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Delete a workflow", "description": "Only one no project uses, and never the default one (422). 403 when the caller may not change it. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1WorkflowsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Replace a workflow's statuses (/docs/projects/api/tasks/putV1WorkflowsByIdStatuses) The whole list, with the rules of `PUT /statuses` (one open default, a DONE status, a status in use neither removed nor moved into or out of DONE). 403 when the caller may not change the workflow (`canEdit`). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/workflows/{id}/statuses", "operation": { "tags": [ "Tasks" ], "summary": "Replace a workflow's statuses", "description": "The whole list, with the rules of `PUT /statuses` (one open default, a DONE status, a status in use neither removed nor moved into or out of DONE). 403 when the caller may not change the workflow (`canEdit`). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } }, "application/x-www-form-urlencoded": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } }, "multipart/form-data": { "schema": { "anyOf": [ { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } }, { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } }, { "type": "object", "required": [ "data" ], "properties": { "data": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "required": [ "name", "category" ], "properties": { "id": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "name": { "minLength": 1, "maxLength": 100, "type": "string" }, "category": { "type": "string", "enum": [ "BACKLOG", "TODO", "IN_PROGRESS", "DONE", "CANCELED" ] }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] }, "sortOrder": { "minimum": -2147483648, "maximum": 2147483647, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -2147483648, "maximum": 2147483647, "type": "integer" } ] }, "isDefault": { "type": "boolean" }, "externalId": { "maxLength": 200, "type": [ "string", "null" ] } } } } } } ] } } } }, "operationId": "putV1WorkflowsByIdStatuses", "security": [ { "bearerToken": [] } ] } } ] } ``` # Put a project on a workflow (/docs/projects/api/tasks/putV1ProjectsByIdWorkflow) Every task of the project (the trash included) moves to a status of the new workflow: the one with the same name and category, else the first of the category, else the default (a done task stays done; a cancelled one in a workflow without CANCELED goes to the default). Answers `{ projectId, workflowId, remap: [{ from, to, tasks }], applied }`; with `dryRun: true` only the plan, nothing written. Only the project's owner or an admin (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/projects/{id}/workflow", "operation": { "tags": [ "Tasks" ], "summary": "Put a project on a workflow", "description": "Every task of the project (the trash included) moves to a status of the new workflow: the one with the same name and category, else the first of the category, else the default (a done task stays done; a cancelled one in a workflow without CANCELED goes to the default). Answers `{ projectId, workflowId, remap: [{ from, to, tasks }], applied }`; with `dryRun: true` only the plan, nothing written. Only the project's owner or an admin (403). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflowId" ], "properties": { "workflowId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "dryRun": { "type": "boolean" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "workflowId" ], "properties": { "workflowId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "dryRun": { "type": "boolean" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "workflowId" ], "properties": { "workflowId": { "pattern": "^[0-9]{1,40}$", "type": "string" }, "dryRun": { "type": "boolean" } } } } } }, "operationId": "putV1ProjectsByIdWorkflow", "security": [ { "bearerToken": [] } ] } } ] } ``` # List labels (/docs/projects/api/tasks/getV1Labels) Every label of the organization, ordered by title without regard to case: `{ data: [{ id, title, color }] }`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/labels", "operation": { "tags": [ "Tasks" ], "summary": "List labels", "description": "Every label of the organization, ordered by title without regard to case: `{ data: [{ id, title, color }] }`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1Labels", "security": [ { "bearerToken": [] } ] } } ] } ``` # Create a label (/docs/projects/api/tasks/postV1Labels) A title is unique in the organization regardless of case: `Bug` next to an existing `bug` is a 409. `color` is `#rrggbb`, stored lowercase. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/labels", "operation": { "tags": [ "Tasks" ], "summary": "Create a label", "description": "A title is unique in the organization regardless of case: `Bug` next to an existing `bug` is a 409. `color` is `#rrggbb`, stored lowercase. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } } } }, "operationId": "postV1Labels", "security": [ { "bearerToken": [] } ] } } ] } ``` # Update a label (/docs/projects/api/tasks/patchV1LabelsById) Partial; `color: null` clears the color. A title taken by another label (without regard to case) is a 409. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/labels/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Update a label", "description": "Partial; `color: null` clears the color. A title taken by another label (without regard to case) is a 409. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "title": { "minLength": 1, "maxLength": 100, "type": "string" }, "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": [ "string", "null" ] } } } } } }, "operationId": "patchV1LabelsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a label (/docs/projects/api/tasks/deleteV1LabelsById) Removes it from every task that had it; each of those tasks records a `task.updated` of its `labelIds`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/labels/{id}", "operation": { "tags": [ "Tasks" ], "summary": "Delete a label", "description": "Removes it from every task that had it; each of those tasks records a `task.updated` of its `labelIds`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1LabelsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's comments (/docs/projects/api/comments/getV1TasksByIdComments) The root comments, oldest first, `{ data, total, limit, offset }`: `total`, `limit` and `offset` count roots. Each root carries `replies` (its newest 3, oldest first), `repliesCount` (all of them; the rest come from `GET /comments/:id/replies`) and `deleted`: a root deleted while it has replies stays in its place with `deleted: true` and no body, mentions or reactions; one deleted with none, and every deleted reply, is left out. Every comment has `parentId`, the root it answers or null. `limit` defaults to 50 and is capped at 200. An entity the caller cannot see is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/comments", "operation": { "tags": [ "Comments" ], "summary": "List a task's comments", "description": "The root comments, oldest first, `{ data, total, limit, offset }`: `total`, `limit` and `offset` count roots. Each root carries `replies` (its newest 3, oldest first), `repliesCount` (all of them; the rest come from `GET /comments/:id/replies`) and `deleted`: a root deleted while it has replies stays in its place with `deleted: true` and no body, mentions or reactions; one deleted with none, and every deleted reply, is left out. Every comment has `parentId`, the root it answers or null. `limit` defaults to 50 and is capped at 200. An entity the caller cannot see is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksByIdComments", "security": [ { "bearerToken": [] } ] } } ] } ``` # Comment on a task (/docs/projects/api/comments/postV1TasksByIdComments) 201 with the comment and its `mentionedHandles`. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. A body with no text is a 422, and so is a `parentId` or `replyToCommentId`: a comment here is a root, and a reply goes to `POST /comments/:id/replies`. Records `comment.created` on the task, with `meta.commentId`, `meta.mentionedUserIds` and `meta.excerpt` (the first 200 characters). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/comments", "operation": { "tags": [ "Comments" ], "summary": "Comment on a task", "description": "201 with the comment and its `mentionedHandles`. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. A body with no text is a 422, and so is a `parentId` or `replyToCommentId`: a comment here is a root, and a reply goes to `POST /comments/:id/replies`. Records `comment.created` on the task, with `meta.commentId`, `meta.mentionedUserIds` and `meta.excerpt` (the first 200 characters). Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } } } }, "operationId": "postV1TasksByIdComments", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a project's comments (/docs/projects/api/comments/getV1ProjectsByIdComments) The root comments, oldest first, `{ data, total, limit, offset }`: `total`, `limit` and `offset` count roots. Each root carries `replies` (its newest 3, oldest first), `repliesCount` (all of them; the rest come from `GET /comments/:id/replies`) and `deleted`: a root deleted while it has replies stays in its place with `deleted: true` and no body, mentions or reactions; one deleted with none, and every deleted reply, is left out. Every comment has `parentId`, the root it answers or null. `limit` defaults to 50 and is capped at 200. An entity the caller cannot see is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/projects/{id}/comments", "operation": { "tags": [ "Comments" ], "summary": "List a project's comments", "description": "The root comments, oldest first, `{ data, total, limit, offset }`: `total`, `limit` and `offset` count roots. Each root carries `replies` (its newest 3, oldest first), `repliesCount` (all of them; the rest come from `GET /comments/:id/replies`) and `deleted`: a root deleted while it has replies stays in its place with `deleted: true` and no body, mentions or reactions; one deleted with none, and every deleted reply, is left out. Every comment has `parentId`, the root it answers or null. `limit` defaults to 50 and is capped at 200. An entity the caller cannot see is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1ProjectsByIdComments", "security": [ { "bearerToken": [] } ] } } ] } ``` # Comment on a project (/docs/projects/api/comments/postV1ProjectsByIdComments) The same rules as a task's comments. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. Records `comment.created` on the project. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/projects/{id}/comments", "operation": { "tags": [ "Comments" ], "summary": "Comment on a project", "description": "The same rules as a task's comments. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. Records `comment.created` on the project. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" }, "parentId": { "not": {} }, "replyToCommentId": { "not": {} } } } } } }, "operationId": "postV1ProjectsByIdComments", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a comment's replies (/docs/projects/api/comments/getV1CommentsByIdReplies) Every reply of a root comment, oldest first, without deleted ones, `{ data, total, limit, offset }` (fazer-ai/projects#458). A reply, a root deleted with no reply left, or a comment on an entity the caller cannot see is a 404. `limit` defaults to 50 and is capped at 200. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/comments/{id}/replies", "operation": { "tags": [ "Comments" ], "summary": "List a comment's replies", "description": "Every reply of a root comment, oldest first, without deleted ones, `{ data, total, limit, offset }` (fazer-ai/projects#458). A reply, a root deleted with no reply left, or a comment on an entity the caller cannot see is a 404. `limit` defaults to 50 and is capped at 200.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1CommentsByIdReplies", "security": [ { "bearerToken": [] } ] } } ] } ``` # Reply to a comment (/docs/projects/api/comments/postV1CommentsByIdReplies) 201 with the reply, whose `parentId` is the root of the thread (fazer-ai/projects#458): replies are one level deep, so answering a reply adds to the same root. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. Anyone who can see the comment may reply. A deleted root whose replies are not all deleted still takes replies (it stays in the thread as a placeholder); a deleted reply, a deleted root with no live reply, or a comment on an entity the caller cannot see is a 404; a body with no text is a 422. Records `comment.created` on the entity with `meta.parentId` and `meta.threadUserIds` (the root's author and whoever replied in the thread, an agent standing for its owner, the replier aside), who hear of it besides the entity's subscribers. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/comments/{id}/replies", "operation": { "tags": [ "Comments" ], "summary": "Reply to a comment", "description": "201 with the reply, whose `parentId` is the root of the thread (fazer-ai/projects#458): replies are one level deep, so answering a reply adds to the same root. The body is markdown. Every `@handle` of an existing, active user (a person or an agent) outside code (inline backticks or a fenced block) is a mention, case-insensitive and counted once: it lands in `mentionUserIds` and `mentionedHandles`, and subscribes that user to the entity. An unknown handle stays text. The author is subscribed as COMMENTER. Anyone who can see the comment may reply. A deleted root whose replies are not all deleted still takes replies (it stays in the thread as a placeholder); a deleted reply, a deleted root with no live reply, or a comment on an entity the caller cannot see is a 404; a body with no text is a 422. Records `comment.created` on the entity with `meta.parentId` and `meta.threadUserIds` (the root's author and whoever replied in the thread, an agent standing for its owner, the replier aside), who hear of it besides the entity's subscribers. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } } } }, "operationId": "postV1CommentsByIdReplies", "security": [ { "bearerToken": [] } ] } } ] } ``` # Edit a comment (/docs/projects/api/comments/patchV1CommentsById) The author, the person who owns the agent that wrote it, the agent of the person who wrote it (not a sibling agent of the same owner), or an admin (the `admin` scope of the credential) rewrites the body: 403 for anyone else, 404 for a deleted comment or one on an entity the caller cannot see. Stamps `editedAt` and `editedBy` and reads the mentions again; only a mention the edit ADDS subscribes that user and goes in `meta.mentionedUserIds` of `comment.updated`. The same body again changes nothing and records nothing. Answers the comment with `notifications`: what the mentions the edit took out did to the notifications they had caused, in the same write (`[]` when no mention was taken out). Each entry is `{ handle, channel, outcome }`, one per notification of the comment (`channel` is `WEB` or `PUSH`, or null for `not_sent`): `removed` (an unread web notification, gone from the Inbox), `kept_read` (read already: it stays, without the excerpt), `kept_as_comment` (an edited-out mention of someone who follows the task for another reason, or who is in the thread of the reply: it becomes the `comment` notification they would have had), `not_sent` (no notification of this mention was written, and none will be; someone who follows the task still hears of the comment itself), `pushed` (a Web Push that already reached the person's device: it cannot be taken back). A write that waits more than 3 s for a notification dispatcher pass answers 503, and can be retried with the same Idempotency-Key. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/comments/{id}", "operation": { "tags": [ "Comments" ], "summary": "Edit a comment", "description": "The author, the person who owns the agent that wrote it, the agent of the person who wrote it (not a sibling agent of the same owner), or an admin (the `admin` scope of the credential) rewrites the body: 403 for anyone else, 404 for a deleted comment or one on an entity the caller cannot see. Stamps `editedAt` and `editedBy` and reads the mentions again; only a mention the edit ADDS subscribes that user and goes in `meta.mentionedUserIds` of `comment.updated`. The same body again changes nothing and records nothing. Answers the comment with `notifications`: what the mentions the edit took out did to the notifications they had caused, in the same write (`[]` when no mention was taken out). Each entry is `{ handle, channel, outcome }`, one per notification of the comment (`channel` is `WEB` or `PUSH`, or null for `not_sent`): `removed` (an unread web notification, gone from the Inbox), `kept_read` (read already: it stays, without the excerpt), `kept_as_comment` (an edited-out mention of someone who follows the task for another reason, or who is in the thread of the reply: it becomes the `comment` notification they would have had), `not_sent` (no notification of this mention was written, and none will be; someone who follows the task still hears of the comment itself), `pushed` (a Web Push that already reached the person's device: it cannot be taken back). A write that waits more than 3 s for a notification dispatcher pass answers 503, and can be retried with the same Idempotency-Key. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "minLength": 1, "maxLength": 50000, "type": "string" } } } } } }, "operationId": "patchV1CommentsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Delete a comment (/docs/projects/api/comments/deleteV1CommentsById) Soft delete by whoever may edit it (the author, the person who owns the agent that wrote it, the agent of the person who wrote it, or an admin with the `admin` scope): the comment leaves the list and answers 404 from then on; the row keeps `deletedAt`. Answers `{ success: true, notifications }`: what the deletion did, in the same write, to each notification the comment caused (`[]` when it caused none). Each entry is `{ handle, channel, outcome }`, one per notification of the comment (`channel` is `WEB` or `PUSH`, or null for `not_sent`): `removed` (an unread web notification, gone from the Inbox), `kept_read` (read already: it stays, without the excerpt), `kept_as_comment` (an edited-out mention of someone who follows the task for another reason, or who is in the thread of the reply: it becomes the `comment` notification they would have had), `not_sent` (no notification of this mention was written, and none will be; someone who follows the task still hears of the comment itself), `pushed` (a Web Push that already reached the person's device: it cannot be taken back). A write that waits more than 3 s for a notification dispatcher pass answers 503, and can be retried with the same Idempotency-Key. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/comments/{id}", "operation": { "tags": [ "Comments" ], "summary": "Delete a comment", "description": "Soft delete by whoever may edit it (the author, the person who owns the agent that wrote it, the agent of the person who wrote it, or an admin with the `admin` scope): the comment leaves the list and answers 404 from then on; the row keeps `deletedAt`. Answers `{ success: true, notifications }`: what the deletion did, in the same write, to each notification the comment caused (`[]` when it caused none). Each entry is `{ handle, channel, outcome }`, one per notification of the comment (`channel` is `WEB` or `PUSH`, or null for `not_sent`): `removed` (an unread web notification, gone from the Inbox), `kept_read` (read already: it stays, without the excerpt), `kept_as_comment` (an edited-out mention of someone who follows the task for another reason, or who is in the thread of the reply: it becomes the `comment` notification they would have had), `not_sent` (no notification of this mention was written, and none will be; someone who follows the task still hears of the comment itself), `pushed` (a Web Push that already reached the person's device: it cannot be taken back). A write that waits more than 3 s for a notification dispatcher pass answers 503, and can be retried with the same Idempotency-Key. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1CommentsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Tick a box of a comment (/docs/projects/api/comments/postV1CommentsByIdCheckbox) Flips one box of a task list (`- [ ] item`, `- [x] item`): `index` is the box's position among the task list items of the markdown in document order, as the markdown parser reads them (a `[ ]` inside code is not an item; one in a quote or a nested list is), `checked` the state the caller saw it in, `text` the item's text as the caller saw it (what `MarkdownView` shows, without the markup). The current markdown is read again under the lock, and only the character between that item's brackets changes. When that item is no longer there as the caller saw it (someone edited in between), nothing is written and the answer is a 409 with `current`. Only whoever may edit the comment may tick its boxes (the author, the person who owns the agent that wrote it, the agent of the person who wrote it, or an admin): ticking one rewrites what the author wrote, so anyone else gets a 403, like an edit. The write is an edit: `editedAt`, `comment.updated` with the body before and after, and only an added mention notifies. Answers the comment; the 409's `current` is the comment as it is now. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/comments/{id}/checkbox", "operation": { "tags": [ "Comments" ], "summary": "Tick a box of a comment", "description": "Flips one box of a task list (`- [ ] item`, `- [x] item`): `index` is the box's position among the task list items of the markdown in document order, as the markdown parser reads them (a `[ ]` inside code is not an item; one in a quote or a nested list is), `checked` the state the caller saw it in, `text` the item's text as the caller saw it (what `MarkdownView` shows, without the markup). The current markdown is read again under the lock, and only the character between that item's brackets changes. When that item is no longer there as the caller saw it (someone edited in between), nothing is written and the answer is a 409 with `current`. Only whoever may edit the comment may tick its boxes (the author, the person who owns the agent that wrote it, the agent of the person who wrote it, or an admin): ticking one rewrites what the author wrote, so anyone else gets a 403, like an edit. The write is an edit: `editedAt`, `comment.updated` with the body before and after, and only an added mention notifies. Answers the comment; the 409's `current` is the comment as it is now. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: the item is no longer there as the caller saw it (then with `current`), or the idempotency key is still running.", "content": { "application/json": { "schema": { "description": "Conflict: the item is no longer there as the caller saw it (then with `current`), or the idempotency key is still running.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "current": { "description": "When the item changed since: the comment as it is now, in the shape this route answers." } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "index", "checked", "text" ], "properties": { "index": { "minimum": 0, "maximum": 50000, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 50000, "type": "integer" } ] }, "checked": { "type": "boolean" }, "text": { "maxLength": 50000, "type": "string" } } } } } }, "operationId": "postV1CommentsByIdCheckbox", "security": [ { "bearerToken": [] } ] } } ] } ``` # React to a comment (/docs/projects/api/comments/postV1CommentsByIdReactions) Any one emoji, fully qualified as a picker hands it over (`❤️`, a skin tone, a flag or a sequence included); anything else, two emoji or text, is a 422. The quick ones the screens offer first are 👍 ❤️ 😄 🎉 👀 ✅. The reactions come in the order of each emoji's oldest reaction still there (a reaction taken back leaves no row). Anyone who can see the comment reacts, as themselves (an agent too), once per emoji: adding one already there, or removing one that is not, changes nothing and records nothing. A change records `comment.reacted` or `comment.unreacted` (meta `{ commentId, emoji }`) on the comment's entity, for `/changes`; it notifies nobody and stays out of the task's history. Answers the comment with `reactions` (`[{ emoji, count, users }]`). 404 for a deleted comment or one on an entity the caller cannot see. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/comments/{id}/reactions", "operation": { "tags": [ "Comments" ], "summary": "React to a comment", "description": "Any one emoji, fully qualified as a picker hands it over (`❤️`, a skin tone, a flag or a sequence included); anything else, two emoji or text, is a 422. The quick ones the screens offer first are 👍 ❤️ 😄 🎉 👀 ✅. The reactions come in the order of each emoji's oldest reaction still there (a reaction taken back leaves no row). Anyone who can see the comment reacts, as themselves (an agent too), once per emoji: adding one already there, or removing one that is not, changes nothing and records nothing. A change records `comment.reacted` or `comment.unreacted` (meta `{ commentId, emoji }`) on the comment's entity, for `/changes`; it notifies nobody and stays out of the task's history. Answers the comment with `reactions` (`[{ emoji, count, users }]`). 404 for a deleted comment or one on an entity the caller cannot see. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } } } }, "operationId": "postV1CommentsByIdReactions", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove a reaction from a comment (/docs/projects/api/comments/deleteV1CommentsByIdReactions) The caller's own reaction with that emoji, given in the body or as `?emoji=` (for a client that sends no body with a DELETE). Any one emoji, fully qualified as a picker hands it over (`❤️`, a skin tone, a flag or a sequence included); anything else, two emoji or text, is a 422. The quick ones the screens offer first are 👍 ❤️ 😄 🎉 👀 ✅. The reactions come in the order of each emoji's oldest reaction still there (a reaction taken back leaves no row). Anyone who can see the comment reacts, as themselves (an agent too), once per emoji: adding one already there, or removing one that is not, changes nothing and records nothing. A change records `comment.reacted` or `comment.unreacted` (meta `{ commentId, emoji }`) on the comment's entity, for `/changes`; it notifies nobody and stays out of the task's history. Answers the comment with `reactions` (`[{ emoji, count, users }]`). 404 for a deleted comment or one on an entity the caller cannot see. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/comments/{id}/reactions", "operation": { "tags": [ "Comments" ], "summary": "Remove a reaction from a comment", "description": "The caller's own reaction with that emoji, given in the body or as `?emoji=` (for a client that sends no body with a DELETE). Any one emoji, fully qualified as a picker hands it over (`❤️`, a skin tone, a flag or a sequence included); anything else, two emoji or text, is a 422. The quick ones the screens offer first are 👍 ❤️ 😄 🎉 👀 ✅. The reactions come in the order of each emoji's oldest reaction still there (a reaction taken back leaves no row). Anyone who can see the comment reacts, as themselves (an agent too), once per emoji: adding one already there, or removing one that is not, changes nothing and records nothing. A change records `comment.reacted` or `comment.unreacted` (meta `{ commentId, emoji }`) on the comment's entity, for `/changes`; it notifies nobody and stays out of the task's history. Answers the comment with `reactions` (`[{ emoji, count, users }]`). 404 for a deleted comment or one on an entity the caller cannot see. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "emoji", "in": "query", "required": false, "schema": { "minLength": 1, "maxLength": 40, "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "emoji" ], "properties": { "emoji": { "minLength": 1, "maxLength": 40, "type": "string" } } } } } }, "operationId": "deleteV1CommentsByIdReactions", "security": [ { "bearerToken": [] } ] } } ] } ``` # Whether attachments are on, and their limits (/docs/projects/api/attachments/getV1AttachmentsLimits) `configured` is false without the `ATTACHMENTS_S3_*` variables. `maxBytes` bounds the presigned upload, `inlineMaxBytes` the MCP tool that carries the bytes in the call, and `urlTtlSeconds` how long a presigned URL lives. Never 503 for the feature being off, so a client can say so before anything else. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/attachments/limits", "operation": { "tags": [ "Attachments" ], "summary": "Whether attachments are on, and their limits", "description": "`configured` is false without the `ATTACHMENTS_S3_*` variables. `maxBytes` bounds the presigned upload, `inlineMaxBytes` the MCP tool that carries the bytes in the call, and `urlTtlSeconds` how long a presigned URL lives. Never 503 for the feature being off, so a client can say so before anything else.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1AttachmentsLimits", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's attachments (/docs/projects/api/attachments/getV1TasksByIdAttachments) The complete files that are not removed, oldest first, `{ data }`. Each carries `url`, the app's content route, and `preview` (true for a png, jpeg, gif or webp, which the content route may serve inline). A task the caller cannot see, or in the trash, is a 404. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/attachments", "operation": { "tags": [ "Attachments" ], "summary": "List a task's attachments", "description": "The complete files that are not removed, oldest first, `{ data }`. Each carries `url`, the app's content route, and `preview` (true for a png, jpeg, gif or webp, which the content route may serve inline). A task the caller cannot see, or in the trash, is a 404. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1TasksByIdAttachments", "security": [ { "bearerToken": [] } ] } } ] } ``` # Begin an upload (/docs/projects/api/attachments/postV1TasksByIdAttachments) Step 1 of 3. Declares the file (`fileName`, `contentType`, `size` in bytes and, optionally, `sha256` in hex) and answers 201 with the PENDING `attachment` and `upload`: a presigned PUT straight to the bucket, bound to an opaque key and to the declared length, type and hash, with the `headers` to send and `expiresAt` (a few minutes). Step 2 is that PUT, from the browser or `curl -T`; step 3 is `POST /attachments/:id/complete`. A file over the size limit (100 MB per file by default, `ATTACHMENTS_MAX_BYTES`) is a 413 before any URL exists. A file that would take the organization past its storage (`ATTACHMENTS_ORG_MAX_BYTES`, unset by default: no ceiling; the trash counts until the sweep purges it) is a 413 with `code: storage_quota`, `usedBytes` and `allowedBytes`; nothing is ever deleted for being over it. A PENDING upload nobody completes is deleted, with its object, after an hour. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. A replay answers the same attachment with a fresh `upload` (null once it completed). Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/tasks/{id}/attachments", "operation": { "tags": [ "Attachments" ], "summary": "Begin an upload", "description": "Step 1 of 3. Declares the file (`fileName`, `contentType`, `size` in bytes and, optionally, `sha256` in hex) and answers 201 with the PENDING `attachment` and `upload`: a presigned PUT straight to the bucket, bound to an opaque key and to the declared length, type and hash, with the `headers` to send and `expiresAt` (a few minutes). Step 2 is that PUT, from the browser or `curl -T`; step 3 is `POST /attachments/:id/complete`. A file over the size limit (100 MB per file by default, `ATTACHMENTS_MAX_BYTES`) is a 413 before any URL exists. A file that would take the organization past its storage (`ATTACHMENTS_ORG_MAX_BYTES`, unset by default: no ceiling; the trash counts until the sweep purges it) is a 413 with `code: storage_quota`, `usedBytes` and `allowedBytes`; nothing is ever deleted for being over it. A PENDING upload nobody completes is deleted, with its object, after an hour. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. A replay answers the same attachment with a fresh `upload` (null once it completed). Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Payload too large: the file is over the per-file limit, or would take the organization past its storage (`code: storage_quota`, `usedBytes`, `allowedBytes`).", "content": { "application/json": { "schema": { "description": "Payload too large: the file is over the per-file limit, or would take the organization past its storage (`code: storage_quota`, `usedBytes`, `allowedBytes`).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "const": "storage_quota", "type": "string" }, "usedBytes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowedBytes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fileName", "size" ], "properties": { "fileName": { "minLength": 1, "maxLength": 1000, "type": "string" }, "contentType": { "maxLength": 255, "type": "string" }, "size": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "sha256": { "maxLength": 64, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "fileName", "size" ], "properties": { "fileName": { "minLength": 1, "maxLength": 1000, "type": "string" }, "contentType": { "maxLength": 255, "type": "string" }, "size": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "sha256": { "maxLength": 64, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "fileName", "size" ], "properties": { "fileName": { "minLength": 1, "maxLength": 1000, "type": "string" }, "contentType": { "maxLength": 255, "type": "string" }, "size": { "minimum": 0, "maximum": 9007199254740991, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "type": "integer" } ] }, "sha256": { "maxLength": 64, "type": "string" } } } } } }, "operationId": "postV1TasksByIdAttachments", "security": [ { "bearerToken": [] } ] } } ] } ``` # Complete an upload (/docs/projects/api/attachments/postV1AttachmentsByIdComplete) Step 3 of 3. Checks the object in the bucket against the declaration (size, type and the hash when one was declared), records the SHA-256 of the stored bytes in `sha256` and marks the attachment READY, recording `task.attachment_added` on the task with `meta { attachmentId, fileName, contentType, size }`. 422 when the bytes have not arrived or do not match. The real size is checked against the organization's storage again, so two uploads begun when each fit are refused here when together they do not (413 `storage_quota`). Only the uploader completes; anyone else, and anyone who cannot see the task, gets a 404. Completing a READY attachment again answers it unchanged. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/attachments/{id}/complete", "operation": { "tags": [ "Attachments" ], "summary": "Complete an upload", "description": "Step 3 of 3. Checks the object in the bucket against the declaration (size, type and the hash when one was declared), records the SHA-256 of the stored bytes in `sha256` and marks the attachment READY, recording `task.attachment_added` on the task with `meta { attachmentId, fileName, contentType, size }`. 422 when the bytes have not arrived or do not match. The real size is checked against the organization's storage again, so two uploads begun when each fit are refused here when together they do not (413 `storage_quota`). Only the uploader completes; anyone else, and anyone who cannot see the task, gets a 404. Completing a READY attachment again answers it unchanged. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "413": { "description": "Payload too large: the file is over the per-file limit, or would take the organization past its storage (`code: storage_quota`, `usedBytes`, `allowedBytes`).", "content": { "application/json": { "schema": { "description": "Payload too large: the file is over the per-file limit, or would take the organization past its storage (`code: storage_quota`, `usedBytes`, `allowedBytes`).", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "const": "storage_quota", "type": "string" }, "usedBytes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] }, "allowedBytes": { "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "type": "integer" } ] } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1AttachmentsByIdComplete", "security": [ { "bearerToken": [] } ] } } ] } ``` # Download an attachment (/docs/projects/api/attachments/getV1AttachmentsByIdContent) Checks that the caller sees the task now and answers 302 to a presigned GET on the bucket that lives `urlTtlSeconds` (a few minutes): a copied link stops working, this URL keeps working for whoever can see the task. A png, jpeg, gif or webp is served `inline` for previews; HTML, SVG, PDF and anything else always as `attachment` with the original file name, and `?download=1` makes an image an attachment too. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/attachments/{id}/content", "operation": { "tags": [ "Attachments" ], "summary": "Download an attachment", "description": "Checks that the caller sees the task now and answers 302 to a presigned GET on the bucket that lives `urlTtlSeconds` (a few minutes): a copied link stops working, this URL keeps working for whoever can see the task. A png, jpeg, gif or webp is served `inline` for previews; HTML, SVG, PDF and anything else always as `attachment` with the original file name, and `?download=1` makes an image an attachment too. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "download", "in": "query", "required": false, "schema": { "maxLength": 5, "type": "string" } } ], "operationId": "getV1AttachmentsByIdContent", "security": [ { "bearerToken": [] } ] } } ] } ``` # Preview link of a PDF, an audio or a video (/docs/projects/api/attachments/getV1AttachmentsByIdPreview) For the in-app viewer (fazer-ai/projects#268, #294): checks that the caller sees the task now and answers `{ url, expiresAt }`, a presigned GET on the bucket's own origin that serves the file `inline` for `urlTtlSeconds`, as `application/pdf` for a PDF and as an audio or video type from a fixed list (mp3, m4a, aac, ogg, opus, wav, webm, flac, mp4, mov) for media. Data, never a redirect: the app's own URL never serves a document inline, and `GET /attachments/:id/content` keeps answering `attachment` for these. Any other type is a 422 (`previewKind` says which have one), and a file the caller cannot see is the same 404 as the content route. `previewKind` on an attachment says which files open in the viewer. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/attachments/{id}/preview", "operation": { "tags": [ "Attachments" ], "summary": "Preview link of a PDF, an audio or a video", "description": "For the in-app viewer (fazer-ai/projects#268, #294): checks that the caller sees the task now and answers `{ url, expiresAt }`, a presigned GET on the bucket's own origin that serves the file `inline` for `urlTtlSeconds`, as `application/pdf` for a PDF and as an audio or video type from a fixed list (mp3, m4a, aac, ogg, opus, wav, webm, flac, mp4, mov) for media. Data, never a redirect: the app's own URL never serves a document inline, and `GET /attachments/:id/content` keeps answering `attachment` for these. Any other type is a 422 (`previewKind` says which have one), and a file the caller cannot see is the same 404 as the content route. `previewKind` on an attachment says which files open in the viewer. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1AttachmentsByIdPreview", "security": [ { "bearerToken": [] } ] } } ] } ``` # Text of a text, code, markdown, CSV or JSON file (/docs/projects/api/attachments/getV1AttachmentsByIdText) For the in-app viewer (fazer-ai/projects#294): checks that the caller sees the task now and answers the file's text from the app's own origin as `text/plain; charset=utf-8` with `nosniff` and `no-store`, never a redirect. At most the first 1 MiB, cut on a character boundary: `X-Attachment-Size` is the whole file's size in bytes, `X-Attachment-Shown` the bytes returned and `X-Attachment-Truncated` is `1` when the text stops before the file does. A file that is not UTF-8 text is a 422, as is any type without a text preview (`previewKind` text, markdown, csv, tsv or json has one); a file the caller cannot see is the same 404 as the content route. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/attachments/{id}/text", "operation": { "tags": [ "Attachments" ], "summary": "Text of a text, code, markdown, CSV or JSON file", "description": "For the in-app viewer (fazer-ai/projects#294): checks that the caller sees the task now and answers the file's text from the app's own origin as `text/plain; charset=utf-8` with `nosniff` and `no-store`, never a redirect. At most the first 1 MiB, cut on a character boundary: `X-Attachment-Size` is the whole file's size in bytes, `X-Attachment-Shown` the bytes returned and `X-Attachment-Truncated` is `1` when the text stops before the file does. A file that is not UTF-8 text is a 422, as is any type without a text preview (`previewKind` text, markdown, csv, tsv or json has one); a file the caller cannot see is the same 404 as the content route. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "getV1AttachmentsByIdText", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove an attachment (/docs/projects/api/attachments/deleteV1AttachmentsById) Anyone who sees the task removes it: it leaves the list and answers 404, and `task.attachment_removed` is recorded. The object stays in the bucket for 7 days, so `POST /attachments/:id/restore` can undo it, and is then deleted for good. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/attachments/{id}", "operation": { "tags": [ "Attachments" ], "summary": "Remove an attachment", "description": "Anyone who sees the task removes it: it leaves the list and answers 404, and `task.attachment_removed` is recorded. The object stays in the bucket for 7 days, so `POST /attachments/:id/restore` can undo it, and is then deleted for good. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1AttachmentsById", "security": [ { "bearerToken": [] } ] } } ] } ``` # Restore a removed attachment (/docs/projects/api/attachments/postV1AttachmentsByIdRestore) Undoes a removal inside the 7 days before its object is deleted, recording `task.attachment_restored`. An attachment that was not removed answers unchanged; one already deleted for good is a 404. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/attachments/{id}/restore", "operation": { "tags": [ "Attachments" ], "summary": "Restore a removed attachment", "description": "Undoes a removal inside the 7 days before its object is deleted, recording `task.attachment_restored`. An attachment that was not removed answers unchanged; one already deleted for good is a 404. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. Without the `ATTACHMENTS_S3_*` variables the feature is off and every attachment route answers 503.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "postV1AttachmentsByIdRestore", "security": [ { "bearerToken": [] } ] } } ] } ``` # Remove a task's recurrence (/docs/projects/api/recurrence/deleteV1TasksByIdRecurrence) The task stops rolling and becomes a plain task; the history of its completions stays. Removing a rule that is not there answers 200 and records nothing; otherwise records `recurrence.removed`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "DELETE", "path": "/v1/tasks/{id}/recurrence", "operation": { "tags": [ "Recurrence" ], "summary": "Remove a task's recurrence", "description": "The task stops rolling and becomes a plain task; the history of its completions stays. Removing a rule that is not there answers 200 and records nothing; otherwise records `recurrence.removed`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "operationId": "deleteV1TasksByIdRecurrence", "security": [ { "bearerToken": [] } ] } } ] } ``` # Set a task's recurrence (/docs/projects/api/recurrence/putV1TasksByIdRecurrence) Replaces the task's rule. `spec` is a shorthand (`daily`, `weekly`, `weekly:sex`, `monthly`, `monthly:10`, `monthly:-1`, `monthly-last`, `yearly`, `every:30d`, `every:2w`) or a raw RRULE (`FREQ=MONTHLY;BYDAY=-1TH`), and a trailing `!` counts the next date from the completion (`every:30d!`, only on a plain interval); `rrule` takes a raw RRULE only. Send exactly one of them. `offsetDays` moves every date of the series, in the rule's own space: `FREQ=MONTHLY;BYDAY=-1TH` with `-2` is the Tuesday before the last Thursday. Grammar in docs/recurrence.md. `dtstart` (`YYYY-MM-DD`) anchors the series and defaults to the local date of the task's due date (its start date when it has no due date); `timezone` defaults to the task's. A task with no date is a 422, and so is a rule with no date ahead of the task. The task's own dates are not moved: completing it rolls it to the next date, and a PATCH of its dates never touches the rule. Answers the rule and `next`, the dates of its next five rolls if each occurrence is completed on its own date. Records `recurrence.set` when the rule changes. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PUT", "path": "/v1/tasks/{id}/recurrence", "operation": { "tags": [ "Recurrence" ], "summary": "Set a task's recurrence", "description": "Replaces the task's rule. `spec` is a shorthand (`daily`, `weekly`, `weekly:sex`, `monthly`, `monthly:10`, `monthly:-1`, `monthly-last`, `yearly`, `every:30d`, `every:2w`) or a raw RRULE (`FREQ=MONTHLY;BYDAY=-1TH`), and a trailing `!` counts the next date from the completion (`every:30d!`, only on a plain interval); `rrule` takes a raw RRULE only. Send exactly one of them. `offsetDays` moves every date of the series, in the rule's own space: `FREQ=MONTHLY;BYDAY=-1TH` with `-2` is the Tuesday before the last Thursday. Grammar in docs/recurrence.md. `dtstart` (`YYYY-MM-DD`) anchors the series and defaults to the local date of the task's due date (its start date when it has no due date); `timezone` defaults to the task's. A task with no date is a 422, and so is a rule with no date ahead of the task. The task's own dates are not moved: completing it rolls it to the next date, and a PATCH of its dates never touches the rule. Answers the rule and `next`, the dates of its next five rolls if each occurrence is completed on its own date. Records `recurrence.set` when the rule changes. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" } } } } } }, "operationId": "putV1TasksByIdRecurrence", "security": [ { "bearerToken": [] } ] } } ] } ``` # Preview a task's recurrence (/docs/projects/api/recurrence/getV1TasksByIdRecurrencePreview) The task's rule and `next`: the dates of its next `count` rolls (5 by default, 366 at most) if each occurrence is completed on its own date, in the task's zone. An overdue task starts from the future, like the roll does. A task without a rule is a 404. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/recurrence/preview", "operation": { "tags": [ "Recurrence" ], "summary": "Preview a task's recurrence", "description": "The task's rule and `next`: the dates of its next `count` rolls (5 by default, 366 at most) if each occurrence is completed on its own date, in the task's zone. An overdue task starts from the future, like the roll does. A task without a rule is a 404.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "count", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 366, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 366, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksByIdRecurrencePreview", "security": [ { "bearerToken": [] } ] } } ] } ``` # Preview a recurrence spec (/docs/projects/api/recurrence/postV1RecurrencePreview) A rule that belongs to no task yet, for the UI while a spec is typed and for an agent checking one before it sets it. `spec` is a shorthand (`daily`, `weekly`, `weekly:sex`, `monthly`, `monthly:10`, `monthly:-1`, `monthly-last`, `yearly`, `every:30d`, `every:2w`) or a raw RRULE (`FREQ=MONTHLY;BYDAY=-1TH`), and a trailing `!` counts the next date from the completion (`every:30d!`, only on a plain interval); `rrule` takes a raw RRULE only. Send exactly one of them. `offsetDays` moves every date of the series, in the rule's own space: `FREQ=MONTHLY;BYDAY=-1TH` with `-2` is the Tuesday before the last Thursday. Grammar in docs/recurrence.md. Answers the rule as it would be stored (`rrule` normalized, `shorthand`, `mode`) and `next`: the first `count` dates of the series (5 by default, 366 at most) from `dtstart` on, that day included, at 12:00 in the rule's zone. `dtstart` defaults to today and `tz` (or `timezone`) to the caller's zone. Changes nothing. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/recurrence/preview", "operation": { "tags": [ "Recurrence" ], "summary": "Preview a recurrence spec", "description": "A rule that belongs to no task yet, for the UI while a spec is typed and for an agent checking one before it sets it. `spec` is a shorthand (`daily`, `weekly`, `weekly:sex`, `monthly`, `monthly:10`, `monthly:-1`, `monthly-last`, `yearly`, `every:30d`, `every:2w`) or a raw RRULE (`FREQ=MONTHLY;BYDAY=-1TH`), and a trailing `!` counts the next date from the completion (`every:30d!`, only on a plain interval); `rrule` takes a raw RRULE only. Send exactly one of them. `offsetDays` moves every date of the series, in the rule's own space: `FREQ=MONTHLY;BYDAY=-1TH` with `-2` is the Tuesday before the last Thursday. Grammar in docs/recurrence.md. Answers the rule as it would be stored (`rrule` normalized, `shorthand`, `mode`) and `next`: the first `count` dates of the series (5 by default, 366 at most) from `dtstart` on, that day included, at 12:00 in the rule's zone. `dtstart` defaults to today and `tz` (or `timezone`) to the caller's zone. Changes nothing.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "count": { "minimum": 1, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 366, "type": "integer" } ] } } } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "count": { "minimum": 1, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 366, "type": "integer" } ] } } } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "spec": { "minLength": 1, "maxLength": 500, "type": "string" }, "rrule": { "minLength": 1, "maxLength": 500, "type": "string" }, "offsetDays": { "minimum": -366, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": -366, "maximum": 366, "type": "integer" } ] }, "mode": { "type": "string", "enum": [ "CALENDAR", "FROM_COMPLETION" ] }, "dtstart": { "minLength": 1, "maxLength": 32, "type": "string" }, "tz": { "minLength": 1, "maxLength": 64, "type": "string" }, "timezone": { "minLength": 1, "maxLength": 64, "type": "string" }, "count": { "minimum": 1, "maximum": 366, "anyOf": [ { "format": "integer", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 366, "type": "integer" } ] } } } } } }, "operationId": "postV1RecurrencePreview", "security": [ { "bearerToken": [] } ] } } ] } ``` # List a task's completions (/docs/projects/api/recurrence/getV1TasksByIdCompletions) The history of a recurring task, one row per completed occurrence, newest first: `occurrenceDueAt` (the date the occurrence had when it was completed), `nextDueAt` (where the roll took the task, null when the series ended there), `completedAt`, `completedBy`, `via` and `note`. `{ data, total, limit, offset }`; `limit` defaults to 50 and is capped at 200. The history outlives the rule. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/tasks/{id}/completions", "operation": { "tags": [ "Recurrence" ], "summary": "List a task's completions", "description": "The history of a recurring task, one row per completed occurrence, newest first: `occurrenceDueAt` (the date the occurrence had when it was completed), `nextDueAt` (where the roll took the task, null when the series ended there), `completedAt`, `completedBy`, `via` and `note`. `{ data, total, limit, offset }`; `limit` defaults to 50 and is capped at 200. The history outlives the rule.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "description": "Not found.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: the request failed the route's schema (a required field missing, or a field of the wrong type). Answered before the route runs, with an error naming the field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1TasksByIdCompletions", "security": [ { "bearerToken": [] } ] } } ] } ``` # List my notifications (/docs/projects/api/notifications/getV1Notifications) The caller's web notifications (an agent's are its owner's), newest first, `{ data, total, unread, kindUnread, limit, offset }`. `unread=true` keeps the unread ones, `kind` is a comma-separated list, `archived=true` lists only the archived ones (they are left out otherwise), `ids` is a comma-separated list of at most 200 ids to read just those, `unreadFirst=true` puts the unread ones before the read ones (each newest first). `unread` is always the whole unread count; `kindUnread` is the unread count of the kinds `kind` names (the whole one without `kind`). A notification about a task or a project the caller cannot open, the trash included, is neither listed nor counted. A notification is `{ id, kind, actor, entityType, entityId, path, task, project, excerpt, dueAt, readAt, archivedAt, createdAt }`: `kind` is `mention`, `assignment`, `agent_created`, `comment`, `reminder` or `review`; `actor` is who caused it (null for a reminder), with its `owner` when it is an agent; a `review` notification carries `review: { event }`, one of `requested` (someone asked for my review), `approved`, `changes_requested`, `canceled`, `no_longer_needed` (the task was completed, closed or deleted by someone else) `access_lost` (the approver I asked can no longer see the task), `reminder` (a request still waits on my review), `stalled` (a request I made still waits; `POST /tasks/:id/review/nudge` tells the approver again) and `nudged` (whoever asked is asking again), with `review.id` the request's id, `review.approver` and `review.requestedBy` (`{ id, handle, name }`: who the request is with and who asked, as named when the notification was made; all three null on an older row) and `review.nudge`, read at the time of the call and only on `stalled`: `available` when a nudge can go now, `told_today` when the approver already heard today and one would be a 409 until `review.nudgeAvailableAt` (the start of the approver's next day, null otherwise), null once that request is over, and it is null for every other kind; `path` is the in-app address it opens, with the place inside it as a fragment: `/t/#c-` for a comment or a mention in one (and for changes requested, the comment that carries them), `/t/#descricao` for a mention in the description, `/t/#revisao` for the other review events, the bare `/t/` for an assignment, an agent's task or a due reminder, and `/p/#c-` for a comment on a project; `task`, `project`, `excerpt` and `dueAt` are what they were when the notification was made. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/notifications", "operation": { "tags": [ "Notifications" ], "summary": "List my notifications", "description": "The caller's web notifications (an agent's are its owner's), newest first, `{ data, total, unread, kindUnread, limit, offset }`. `unread=true` keeps the unread ones, `kind` is a comma-separated list, `archived=true` lists only the archived ones (they are left out otherwise), `ids` is a comma-separated list of at most 200 ids to read just those, `unreadFirst=true` puts the unread ones before the read ones (each newest first). `unread` is always the whole unread count; `kindUnread` is the unread count of the kinds `kind` names (the whole one without `kind`). A notification about a task or a project the caller cannot open, the trash included, is neither listed nor counted. A notification is `{ id, kind, actor, entityType, entityId, path, task, project, excerpt, dueAt, readAt, archivedAt, createdAt }`: `kind` is `mention`, `assignment`, `agent_created`, `comment`, `reminder` or `review`; `actor` is who caused it (null for a reminder), with its `owner` when it is an agent; a `review` notification carries `review: { event }`, one of `requested` (someone asked for my review), `approved`, `changes_requested`, `canceled`, `no_longer_needed` (the task was completed, closed or deleted by someone else) `access_lost` (the approver I asked can no longer see the task), `reminder` (a request still waits on my review), `stalled` (a request I made still waits; `POST /tasks/:id/review/nudge` tells the approver again) and `nudged` (whoever asked is asking again), with `review.id` the request's id, `review.approver` and `review.requestedBy` (`{ id, handle, name }`: who the request is with and who asked, as named when the notification was made; all three null on an older row) and `review.nudge`, read at the time of the call and only on `stalled`: `available` when a nudge can go now, `told_today` when the approver already heard today and one would be a 409 until `review.nudgeAvailableAt` (the start of the approver's next day, null otherwise), null once that request is over, and it is null for every other kind; `path` is the in-app address it opens, with the place inside it as a fragment: `/t/#c-` for a comment or a mention in one (and for changes requested, the comment that carries them), `/t/#descricao` for a mention in the description, `/t/#revisao` for the other review events, the bare `/t/` for an assignment, an agent's task or a due reminder, and `/p/#c-` for a comment on a project; `task`, `project`, `excerpt` and `dueAt` are what they were when the notification was made.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "parameters": [ { "name": "unread", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } }, { "name": "kind", "in": "query", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "name": "archived", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } }, { "name": "unreadFirst", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "format": "boolean", "default": false, "type": "string" } ] } }, { "name": "ids", "in": "query", "required": false, "schema": { "maxLength": 8200, "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "minimum": 1, "maximum": 200, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 1, "maximum": 200, "multipleOf": 1, "type": "number" } ] } }, { "name": "offset", "in": "query", "required": false, "schema": { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "anyOf": [ { "format": "numeric", "default": 0, "type": "string" }, { "minimum": 0, "maximum": 9007199254740991, "multipleOf": 1, "type": "number" } ] } } ], "operationId": "getV1Notifications", "security": [ { "bearerToken": [] } ] } } ] } ``` # Count my unread notifications (/docs/projects/api/notifications/getV1NotificationsCounts) `{ unread }`: what the header bell shows. Unread means not read and not archived. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/notifications/counts", "operation": { "tags": [ "Notifications" ], "summary": "Count my unread notifications", "description": "`{ unread }`: what the header bell shows. Unread means not read and not archived.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1NotificationsCounts", "security": [ { "bearerToken": [] } ] } } ] } ``` # Mark notifications read (/docs/projects/api/notifications/postV1NotificationsRead) `{ ids }` marks those, `{ all: true }` marks every unread one, and `{ all: true, kinds }` every unread one of those kinds (what "Mark all read" sends on a list filtered by kind; `kinds` is ignored with `ids`). Idempotent: a notification already read keeps when it was first read, and an id that is not the caller's is ignored. Answers `{ updated, unread }`, the count after the write, and tells the caller's other tabs over the WebSocket. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/notifications/read", "operation": { "tags": [ "Notifications" ], "summary": "Mark notifications read", "description": "`{ ids }` marks those, `{ all: true }` marks every unread one, and `{ all: true, kinds }` every unread one of those kinds (what \"Mark all read\" sends on a list filtered by kind; `kinds` is ignored with `ids`). Idempotent: a notification already read keeps when it was first read, and an id that is not the caller's is ignored. Answers `{ updated, unread }`, the count after the write, and tells the caller's other tabs over the WebSocket. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "all": { "type": "boolean" }, "kinds": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "mention", "assignment", "agent_created", "comment", "reminder", "review" ] } } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "all": { "type": "boolean" }, "kinds": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "mention", "assignment", "agent_created", "comment", "reminder", "review" ] } } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } }, "all": { "type": "boolean" }, "kinds": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "mention", "assignment", "agent_created", "comment", "reminder", "review" ] } } } } } } }, "operationId": "postV1NotificationsRead", "security": [ { "bearerToken": [] } ] } } ] } ``` # Archive notifications (/docs/projects/api/notifications/postV1NotificationsArchive) Takes them out of the list (`archived=true` still lists them), marking them read on the way. Idempotent. Answers `{ updated, unread }`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "POST", "path": "/v1/notifications/archive", "operation": { "tags": [ "Notifications" ], "summary": "Archive notifications", "description": "Takes them out of the list (`archived=true` still lists them), marking them read on the way. Idempotent. Answers `{ updated, unread }`. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "required": [ "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "pattern": "^[0-9]{1,40}$", "type": "string" } } } } } } }, "operationId": "postV1NotificationsArchive", "security": [ { "bearerToken": [] } ] } } ] } ``` # Read my notification preferences (/docs/projects/api/notifications/getV1MeNotification-preferences) `{ channels: { : { web, push } } }`: per event, whether it reaches the web notifications and Web Push. Without changes a person has every event on the web and none by push; push reaches only the browsers the person turned it on in, and only on a server with Web Push configured (`GET /me/push`). ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/me/notification-preferences", "operation": { "tags": [ "Notifications" ], "summary": "Read my notification preferences", "description": "`{ channels: { : { web, push } } }`: per event, whether it reaches the web notifications and Web Push. Without changes a person has every event on the web and none by push; push reaches only the browsers the person turned it on in, and only on a server with Web Push configured (`GET /me/push`).", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1MeNotification-preferences", "security": [ { "bearerToken": [] } ] } } ] } ``` # Change my notification preferences (/docs/projects/api/notifications/patchV1MeNotification-preferences) Partial: an event or a channel left out keeps its value. Answers the preferences, like the GET. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "PATCH", "path": "/v1/me/notification-preferences", "operation": { "tags": [ "Notifications" ], "summary": "Change my notification preferences", "description": "Partial: an event or a channel left out keeps its value. Answers the preferences, like the GET. Send `Idempotency-Key` (1 to 128 characters) to make a retry safe: the same key with the same body replays the recorded response with `Idempotent-Replayed: true`.", "responses": { "400": { "description": "Bad request: the body could not be parsed as JSON. Answered before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "409": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "content": { "application/json": { "schema": { "description": "Conflict: a duplicate, or the resource is in the wrong state.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Unprocessable: syntactically valid but semantically rejected.", "content": { "application/json": { "schema": { "description": "Unprocessable: syntactically valid but semantically rejected.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "properties": { "channels": { "additionalProperties": false, "type": "object", "properties": { "mention": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "assignment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "agent_created": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "comment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "reminder": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "review": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } } } } } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "type": "object", "properties": { "channels": { "additionalProperties": false, "type": "object", "properties": { "mention": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "assignment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "agent_created": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "comment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "reminder": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "review": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } } } } } } }, "multipart/form-data": { "schema": { "additionalProperties": false, "type": "object", "properties": { "channels": { "additionalProperties": false, "type": "object", "properties": { "mention": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "assignment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "agent_created": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "comment": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "reminder": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } }, "review": { "additionalProperties": false, "type": "object", "properties": { "web": { "type": "boolean" }, "push": { "type": "boolean" } } } } } } } } } }, "operationId": "patchV1MeNotification-preferences", "security": [ { "bearerToken": [] } ] } } ] } ``` # The organization's plan, its limits and what is in use (/docs/projects/api/plans/getV1OrganizationPlan) `enabled: false` (and nothing else) on an instance with no plans (`PLANS_ENABLED` off). Otherwise the plan (`free` or `pro`), where it comes from (`none` for the Free, `community` for the Pro of the community), the seats (`allowed`, `occupied`: owners, admins and members who are active people; `reserved`: open invites for a role that takes a seat) and the storage of the organization's attachments in bytes (`allowedBytes` null is no ceiling), plus the limits each plan gives. `communityGrant` is the Pro of the community when an owner turned it on: the grantor (the owner it depends on), `state` (`live`, `stale` while the hub does not answer and the last answer stands, up to `staleUntil`, or `ended` with `endedReason` `not_eligible`, `hub_unreachable`, `not_owner` or `moved`, when the grantor used their benefit in another organization), the last answer (`checkedAt`, `status`, `periodEnd`, `hold`) and until when it stands without asking again (`trustedUntil`). Read only: a seat is taken when a person is added, and a full organization answers that write with 409 `seat_limit`. ```json { "servers": [ { "url": "{base}/api", "variables": { "base": { "default": "http://localhost:3000", "description": "Your instance" } } } ], "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "projects_auth_token", "description": "Session JWT set by the sign-in routes (HttpOnly cookie). This release reads it from `projects_auth_token` and writes the same token under the new name too (`__Host-projects_session` in production, `projects_session` elsewhere), which the next release switches to (fazer-ai/projects#721). `bun setup` renames both per project." }, "bearerToken": { "type": "http", "scheme": "bearer", "description": "An agent's API key (`fzp_...`), minted by the agent's owner in the web app (POST /api/v1/agents/:id/api-keys). A Bearer header takes precedence over the cookie. Failures answer 401 with `WWW-Authenticate: Bearer realm=\"projects\"`." } }, "operations": [ { "method": "GET", "path": "/v1/organization/plan", "operation": { "tags": [ "Plans" ], "summary": "The organization's plan, its limits and what is in use", "description": "`enabled: false` (and nothing else) on an instance with no plans (`PLANS_ENABLED` off). Otherwise the plan (`free` or `pro`), where it comes from (`none` for the Free, `community` for the Pro of the community), the seats (`allowed`, `occupied`: owners, admins and members who are active people; `reserved`: open invites for a role that takes a seat) and the storage of the organization's attachments in bytes (`allowedBytes` null is no ceiling), plus the limits each plan gives. `communityGrant` is the Pro of the community when an owner turned it on: the grantor (the owner it depends on), `state` (`live`, `stale` while the hub does not answer and the last answer stands, up to `staleUntil`, or `ended` with `endedReason` `not_eligible`, `hub_unreachable`, `not_owner` or `moved`, when the grantor used their benefit in another organization), the last answer (`checkedAt`, `status`, `periodEnd`, `hold`) and until when it stands without asking again (`trustedUntil`). Read only: a seat is taken when a person is added, and a full organization answers that write with 409 `seat_limit`.", "responses": { "401": { "description": "Unauthorized: missing or invalid credentials.", "content": { "application/json": { "schema": { "description": "Unauthorized: missing or invalid credentials.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "content": { "application/json": { "schema": { "description": "Forbidden: authenticated but not allowed, or the action is disabled.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } }, "429": { "description": "Too many requests: a budget is exhausted. Every /api path is under RATE_LIMIT_PER_MIN per client IP, or USER_RATE_LIMIT_PER_MIN per person for a verified session, or API_KEY_RATE_LIMIT_PER_MIN per key for a valid API key; the credential endpoint (POST /auth/google) carries a second, tighter STRICT_RATE_LIMIT_PER_MIN budget per IP on top of it. Answered by the rate limiter before the route runs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Service unavailable: a dependency is down, retry.", "content": { "application/json": { "schema": { "description": "Service unavailable: a dependency is down, retry.", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "operationId": "getV1OrganizationPlan", "security": [ { "bearerToken": [] } ] } } ] } ```