A API da zerosoft.
REST e JSON.
Link, CRM, Cal, Track, Docs, Chat, Agents e a maioria dos outros apps têm API REST com respostas JSON e chaves pessoais.
Base URL
https://zerosoft.ai/api/v1Autenticação
Cada requisição precisa de uma API key, enviada como Bearer token. Para sessões de navegador, o fluxo OAuth do Google cria o cookie de sessão.
Authorization: Bearer zs_live_9f3k...Crie as chaves em Dashboard → Settings → API keys. A chave é exibida uma única vez: copie e guarde como uma senha. Cada chave permite 100 requisições por minuto.
Cada chave tem escopos, escolhidos ao criá-la. Os de escrita incluem leitura. Chaves criadas antes dos escopos têm todos. Uma requisição sem o escopo necessário recebe 403 insufficient_scope.
| Escopo | Descrição |
|---|---|
crm:read | Ler contatos, empresas, negócios, atividades, tarefas, pipelines, produtos, cotações, tags, templates, sequências e formulários. |
crm:write | Criar, editar e excluir registros do CRM, inscrever em sequências e aplicar tags (inclui crm:read). |
links:read | Listar links e ler suas estatísticas. |
links:write | Criar, editar e excluir links curtos (inclui links:read). |
cal:read | Listar tipos de evento e reservas. |
cal:write | Criar e cancelar reservas (inclui cal:read). |
agents:run | Enviar mensagens para os seus agentes de IA. |
robots:run | Listar e executar robôs, e ler suas execuções e lotes. |
chat:read | Listar as conversas do Chat e ler as mensagens. |
chat:write | Responder, atribuir, resolver e reabrir conversas do Chat (inclui chat:read). |
groups:read | Ler chats, mensagens e tickets de WhatsApp no Lines. |
groups:write | Enviar mensagens de WhatsApp e criar tickets no Lines. |
voice:read | Ler ditados, reuniões e transcrições do Voice. |
voice:write | Ditar e enviar áudio de reuniões para o Voice. |
track:read | Ler issues e pedidos de clientes do Track. |
track:write | Criar issues do Track a partir de pedidos de clientes (e-mail, formulários, Flow). |
docs:read | Ler páginas, bancos, linhas e comentários do Docs, e buscar. |
docs:write | Criar e editar páginas, linhas e comentários do Docs (inclui docs:read). |
talk:read | Ler canais e mensagens do Talk dos quais você é membro. |
talk:write | Publicar mensagens e criar canais no Talk. |
boards:read | Ler quadros, o resumo e buscar dentro. |
boards:write | Criar quadros, adicionar post-its e formas, renomear, mover e mandar para a lixeira. |
design:read | Ler designs do Design e suas páginas. |
shop:read | Ler produtos e pedidos do Shop. |
shop:write | Criar produtos do Shop. |
hiring:read | Ler as vagas do Hiring e os candidatos que quem criou a chave vê. |
sign:read | Ler os envelopes do Sign que a pessoa dona da key vê (sem arquivos). |
analytics:read | Ler projetos, eventos e pessoas do Pulse e rodar consultas. |
analytics:write | Mudar projetos, insights, painéis, coortes e flags do Pulse. |
bi:read | Ler perguntas, painéis e coleções do Analytics e rodar consultas. |
bi:write | Criar e mudar perguntas, painéis, coleções e assinaturas do Analytics. |
social:read | Ler publicações do Social das contas que você vê. |
social:write | Criar rascunhos e publicações agendadas no Social (com aprovação se você precisar). |
people:read | Ler o diretório do People: só campos públicos do perfil, nunca salário nem dados pessoais. |
books:read | Ler faturas do Books (com o papel no Books de quem criou a key). |
books:write | Criar faturas em rascunho no Books. |
forms:read | Ler os formulários do Forms e suas respostas, só os que o dono da key pode ver. |
send:read | Ler os documentos que a pessoa vê, com seus links e visitas. |
calls:read | Ler as chamadas que a pessoa vê, com transcrições e análise. |
calls:write | Criar e editar chamadas, comentários e clipes, e mandar o notetaker para uma reunião. |
notes:read | Ler as notas que quem criou a chave pode ver, e suas tarefas. |
notes:write | Criar e editar as notas de quem criou a chave. |
Uma chave age como a pessoa que a criou: se o seu workspace limita os membros aos próprios registros do CRM (ou aos da equipe), a API devolve só esses registros.
Login com Google
/api/auth/signin/googleRedirecione o usuário para iniciar o fluxo OAuth do Google. Após o sucesso ele retorna ao app com o cookie de sessão.
curl -X GET "https://zerosoft.ai/api/auth/signin/google" \
-H "Authorization: Bearer zs_live_9f3k..."Links
Criar, listar, atualizar e medir links curtos.
Criar um link
/api/v1/linksCria um link curto com as mesmas opções do app: UTM, expiração, limite de cliques, senha, prévia social, segmentação e um externalId. slug é opcional: se omitido, geramos um.
Escopo links:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | URL de destino. |
domain | string | Não | Hostname de um dos seus domínios próprios verificados. Se omitido, vale o domínio padrão. |
slug | string | Não | Slug curto personalizado. |
title | string | Não | Título legível. |
tags | string[] | Não | Array de strings de tags. |
utmSource | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmMedium | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmCampaign | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmTerm | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmContent | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
redirectType | integer | Não | 302 (padrão) ou 301. |
expiresAt | string | Não | Data ISO 8601. Depois dela, o link redireciona para expiredUrl ou mostra a página de expirado. |
maxClicks | integer | Não | Cliques permitidos antes de o link parar de redirecionar. |
password | string | Não | O visitante precisa digitá-la antes do redirect. Fica salva com hash e nunca é devolvida; a resposta só diz has_password. |
ogTitle | string | Não | Título, descrição e imagem (URL http(s)) da prévia em redes sociais e apps de chat. |
ogDescription | string | Não | Título, descrição e imagem (URL http(s)) da prévia em redes sociais e apps de chat. |
ogImage | string | Não | Título, descrição e imagem (URL http(s)) da prévia em redes sociais e apps de chat. |
targeting | object | Não | Regras por país e dispositivo, destinos A/B com pesos e deep links de iOS/Android. null remove. |
externalId | string | Não | Seu próprio id para o link, único por workspace (letras, números e . _ : @ -). Depois leia ou edite o link com /api/v1/links/ext_{externalId}. |
forwardParams | boolean | Não | Passa os query params do link curto para o destino (padrão true). Em conflito vale o do link curto; qr nunca é passado. |
doIndex | boolean | Não | Permite que os buscadores indexem o link curto (padrão false). Sem isso o redirecionamento leva X-Robots-Tag: noindex. |
expiredUrl | string | Não | Para onde o link redireciona quando expira ou atinge max_clicks. null remove e vale o padrão do domínio ou a página do zerosoft. |
curl -X POST "https://zerosoft.ai/api/v1/links" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"url": "https://zerosoft.ai/blog/open-source-launch",
"slug": "manifesto",
"title": "The manifesto",
"tags": [
"launch",
"blog"
],
"utmSource": "newsletter",
"utmMedium": "email",
"expiresAt": "2026-12-31T23:59:00Z",
"externalId": "cms-post-4812"
}'Requisição
{
"url": "https://zerosoft.ai/blog/open-source-launch",
"slug": "manifesto",
"title": "The manifesto",
"tags": [
"launch",
"blog"
],
"utmSource": "newsletter",
"utmMedium": "email",
"expiresAt": "2026-12-31T23:59:00Z",
"externalId": "cms-post-4812"
}Resposta · 201
{
"id": "lnk_9f3ka2",
"slug": "manifesto",
"domain": null,
"short_url": "https://zs.ai/manifesto",
"url": "https://zerosoft.ai/blog/open-source-launch?utm_source=newsletter&utm_medium=email",
"title": "The manifesto",
"tags": [
"launch",
"blog"
],
"archived": false,
"redirect_type": 302,
"expires_at": "2026-12-31T23:59:00.000Z",
"max_clicks": null,
"has_password": false,
"utm": {
"source": "newsletter",
"medium": "email",
"campaign": null,
"term": null,
"content": null
},
"og": {
"title": null,
"description": null,
"image": null
},
"clicks": 0,
"qr_scans": 0,
"targeting": null,
"forward_params": true,
"do_index": false,
"expired_url": null,
"created_by": "usr_4kq1",
"external_id": "cms-post-4812",
"folder_id": null,
"created_at": "2026-07-14T18:22:41Z",
"updated_at": "2026-07-14T18:22:41Z"
}Listar links
/api/v1/linksSeus links, do mais novo ao mais antigo. Paginação com page e pageSize (máx 50).
Escopo links:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
creator | string | Não | Só os links criados por este id de usuário. |
q | string | Não | Texto a buscar no slug, na URL de destino e no título. |
tag | string | Não | Só os links com esta tag. |
folder | string | Não | Id da pasta, ou none para links sem pasta. |
archived | boolean | Não | true traz só os arquivados, false só os ativos. Sem o parâmetro vêm ambos. |
sort | string | Não | created (padrão, do mais novo ao mais antigo) ou clicks (do mais clicado ao menos). |
curl -X GET "https://zerosoft.ai/api/v1/links" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"links": [
{
"id": "lnk_9f3ka2",
"slug": "manifesto",
"short_url": "https://zs.ai/manifesto",
"url": "https://zerosoft.ai/blog/open-source-launch",
"title": "The manifesto",
"tags": [
"launch",
"blog"
],
"clicks": 4812,
"archived": false,
"external_id": "cms-post-4812",
"created_by": "usr_4kq1",
"created_at": "2026-07-14T18:22:41Z"
}
],
"total": 48
}Excluir um link
/api/v1/links/{id}Exclua um link por id, junto com o histórico de cliques. Quem criou a chave de API precisa ser admin do workspace.
Escopo links:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do link, ou ext_ seguido do externalId definido ao criá-lo. |
curl -X DELETE "https://zerosoft.ai/api/v1/links/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Atualizar um link
/api/v1/links/{id}Atualize qualquer campo editável de um link.
Escopo links:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do link, ou ext_ seguido do externalId definido ao criá-lo. |
url | string | Não | URL de destino. |
slug | string | Não | Slug curto personalizado. |
title | string | Não | Título legível. |
tags | string[] | Não | Array de strings de tags. |
archived | boolean | Não | Flag de arquivo. |
targeting | object | Não | Regras por país e dispositivo, destinos A/B com pesos e deep links de iOS/Android. null remove. |
utmSource | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmMedium | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmCampaign | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmTerm | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
utmContent | string | Não | Define esse parâmetro utm_* na URL de destino. String vazia ou null remove. O objeto utm do link sempre reflete a URL final. |
externalId | string | Não | Seu próprio id para o link, único por workspace (letras, números e . _ : @ -). Depois leia ou edite o link com /api/v1/links/ext_{externalId}. |
forwardParams | boolean | Não | Passa os query params do link curto para o destino (padrão true). Em conflito vale o do link curto; qr nunca é passado. |
doIndex | boolean | Não | Permite que os buscadores indexem o link curto (padrão false). Sem isso o redirecionamento leva X-Robots-Tag: noindex. |
expiredUrl | string | Não | Para onde o link redireciona quando expira ou atinge max_clicks. null remove e vale o padrão do domínio ou a página do zerosoft. |
curl -X PATCH "https://zerosoft.ai/api/v1/links/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "The manifesto — updated"
}'Requisição
{
"title": "The manifesto — updated"
}Estatísticas de um link
/api/v1/links/{id}/statsTotais de cliques e detalhe por dia de um link.
Escopo links:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do link, ou ext_ seguido do externalId definido ao criá-lo. |
curl -X GET "https://zerosoft.ai/api/v1/links/{id}/stats" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"slug": "manifesto",
"total": 4812,
"byDay": [
{
"date": "2026-07-15",
"count": 412
},
{
"date": "2026-07-16",
"count": 388
},
{
"date": "2026-07-17",
"count": 441
}
]
}Analytics do workspace
/api/v1/links/analyticsCliques e leituras de QR de todos os seus links em um período: por dia, top links, referrers, países, dispositivos e navegadores. Até 366 dias.
Escopo links:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
from | string | Não | Data inicial (YYYY-MM-DD). Padrão: 29 dias atrás. |
to | string | Não | Data final (YYYY-MM-DD). Padrão: hoje. |
curl -X GET "https://zerosoft.ai/api/v1/links/analytics" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"range": {
"from": "2026-07-01",
"to": "2026-07-30"
},
"timezone": "UTC",
"filters": {},
"clicks": 1840,
"scans": 212,
"previous": {
"clicks": 1502,
"scans": 160
},
"byDay": [
{
"date": "2026-07-01",
"clicks": 61,
"scans": 7
}
],
"topLinks": [
{
"id": "lnk_9f3ka2",
"slug": "manifesto",
"short_url": "https://zs.ai/manifesto",
"clicks": 912,
"scans": 88
}
],
"referrers": [
{
"name": "direct",
"count": 640
}
],
"countries": [
{
"name": "AR",
"count": 803
}
],
"devices": [
{
"name": "mobile",
"count": 1210
}
],
"browsers": [
{
"name": "Chrome",
"count": 990
}
]
}Registrar um lead
/api/v1/links/track/leadAtribui um cadastro ao clique que trouxe a pessoa. O link precisa ter a medição de conversões ativada: as visitas chegam ao seu site com ?zs_id=<clickId> (o script /link-tracking.js guarda isso em um cookie zs_id do seu domínio). O mesmo cliente com o mesmo evento conta uma vez só.
Escopo links:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
clickId | string | Sim | Click id que chegou ao seu site como ?zs_id= (20 letras e números). |
customerExternalId | string | Sim | O seu próprio id do cliente. As vendas registradas depois com esse id vão para o mesmo link. |
eventName | string | Não | Nome do evento, como Sign up ou Purchase. |
customerName | string | Não | Nome do cliente (opcional, só o seu workspace vê). |
customerEmail | string | Não | Email do cliente (opcional, só o seu workspace vê). |
curl -X POST "https://zerosoft.ai/api/v1/links/track/lead" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"clickId": "Xk3mPq8ZrT2vLw9nB4cD",
"eventName": "Sign up",
"customerExternalId": "user_123"
}'Requisição
{
"clickId": "Xk3mPq8ZrT2vLw9nB4cD",
"eventName": "Sign up",
"customerExternalId": "user_123"
}Resposta · 201
{
"lead": {
"id": 41,
"type": "lead",
"eventName": "Sign up",
"linkId": "lnk_9f3ka2",
"clickId": "Xk3mPq8ZrT2vLw9nB4cD",
"customerExternalId": "user_123",
"amount": 0,
"currency": null,
"source": "api"
},
"duplicate": false
}Registrar uma venda
/api/v1/links/track/saleSoma receita ao link que trouxe o cliente: por customerExternalId (um lead registrado antes) ou por clickId em uma venda direta. Os valores vão em unidades menores. Um invoiceId repetido devolve duplicate: true e não conta duas vezes.
Escopo links:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customerExternalId | string | Não | O seu próprio id do cliente. As vendas registradas depois com esse id vão para o mesmo link. |
clickId | string | Não | Click id que chegou ao seu site como ?zs_id= (20 letras e números). |
amount | integer | Sim | Valor em unidades menores (4900 = 49,00). |
currency | string | Não | Código ISO 4217. Por padrão USD. |
invoiceId | string | Não | Id do pagamento ou da fatura, para a mesma venda nunca contar duas vezes. |
eventName | string | Não | Nome do evento, como Sign up ou Purchase. |
curl -X POST "https://zerosoft.ai/api/v1/links/track/sale" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"customerExternalId": "user_123",
"amount": 4900,
"currency": "USD",
"invoiceId": "inv_1"
}'Requisição
{
"customerExternalId": "user_123",
"amount": 4900,
"currency": "USD",
"invoiceId": "inv_1"
}Resposta · 201
{
"sale": {
"id": 42,
"type": "sale",
"eventName": "Purchase",
"linkId": "lnk_9f3ka2",
"customerExternalId": "user_123",
"amount": 4900,
"currency": "USD",
"invoiceId": "inv_1",
"source": "api"
},
"duplicate": false
}Deep link diferido (abertura do app)
/api/v1/links/track/openO seu app chama ao abrir pela primeira vez com a publishable key do workspace (Authorization: Bearer zs_pk_…, em Configurações do Link › Conversões), nunca com uma API key. Devolve o link deste workspace tocado na última hora a partir da mesma rede e plataforma (correspondência por um hash com sal, de uso único), ou resolve deepLink se o app abriu com um dos seus links curtos. Links com senha voltam sem destino; arquivados, expirados, bloqueados ou sem cliques dão 404.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
platform | string | Sim | ios ou android. |
domain | string | Não | Hostname do seu domínio próprio, para buscar só links desse domínio. |
deepLink | string | Não | Link curto com que o app foi aberto (universal link ou app link), se houver. |
curl -X POST "https://zerosoft.ai/api/v1/links/track/open" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"platform": "ios",
"domain": "go.acme.com"
}'Requisição
{
"platform": "ios",
"domain": "go.acme.com"
}Resposta · 200
{
"matched": "deferred",
"clickId": null,
"link": {
"id": "lnk_9f3ka2",
"shortLink": "https://go.acme.com/app",
"url": "https://acme.com/app",
"deepLink": "acme://promo/42"
}
}Servidor MCP
/api/v1/links/mcpServidor Model Context Protocol (streamable HTTP, respostas JSON) para agentes de IA. Ferramentas: list_links, get_link, create_link, update_link, delete_link, get_link_analytics, get_analytics, list_conversions e list_activity. links:read lê, links:write cria e edita. A key age como a pessoa que a criou, com as permissões de pastas dela.
Escopo links:read
curl -X POST "https://zerosoft.ai/api/v1/links/mcp" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_link",
"arguments": {
"url": "https://acme.com/launch"
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_link",
"arguments": {
"url": "https://acme.com/launch"
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"id\":\"lnk_…\",\"short_url\":\"https://zs.ai/x7k2p9q\"}"
}
],
"isError": false
}
}CRM · Contatos
Pessoas e leads.
Listar contatos
/api/v1/crm/contactsLista contatos. Filtros: q, page, pageSize (máx 100).
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
lifecycle | string | Não | Etapa do ciclo de vida (lead, sql, opportunity, customer). |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/contacts" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"contacts": [
{
"id": "b1f47ac2-…",
"first_name": "Ana",
"last_name": "Garcia",
"email": "ana@kallpa.co",
"lifecycle_stage": "sql",
"company_id": null,
"created_at": "2026-07-18 10:04:11"
}
],
"total": 142,
"page": 1,
"pageSize": 25
}Criar um contato
/api/v1/crm/contactsCria um contato novo.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
firstName | string | Não | Nome. |
lastName | string | Não | Sobrenome. |
email | string | Não | Endereço de email. |
lifecycleStage | string | Não | Etapa do ciclo de vida (lead, sql, opportunity, customer). |
companyId | string | Não | Id da empresa vinculada. |
curl -X POST "https://zerosoft.ai/api/v1/crm/contacts" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"firstName": "Ana",
"lastName": "Garcia",
"email": "ana@kallpa.co",
"lifecycleStage": "sql"
}'Requisição
{
"firstName": "Ana",
"lastName": "Garcia",
"email": "ana@kallpa.co",
"lifecycleStage": "sql"
}Resposta · 201
{
"id": "b1f47ac2-…",
"first_name": "Ana",
"last_name": "Garcia",
"email": "ana@kallpa.co",
"lifecycle_stage": "sql",
"created_at": "2026-07-18 10:04:11"
}Ler um contato
/api/v1/crm/contacts/{id}Lê um contato por id.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Atualizar um contato
/api/v1/crm/contacts/{id}Atualize qualquer propriedade de um contato.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
firstName | string | Não | Nome. |
lifecycleStage | string | Não | Etapa do ciclo de vida (lead, sql, opportunity, customer). |
companyId | string | null | Não | Id da empresa principal. É associada se necessário; a principal anterior continua associada. null remove a principal. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"lifecycleStage": "opportunity"
}'Requisição
{
"lifecycleStage": "opportunity"
}Excluir um contato
/api/v1/crm/contacts/{id}Exclui o contato definitivamente. As atividades ficam, sem vínculo.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/contacts/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Empresas
Organizações e contas.
Listar empresas
/api/v1/crm/companiesLista empresas. Filtros: q, page, pageSize.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/companies" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"companies": [
{
"id": "c7a1…",
"name": "Norte Labs",
"domain": "nortelabs.co",
"industry": "Software"
}
],
"total": 40,
"page": 1,
"pageSize": 25
}Criar uma empresa
/api/v1/crm/companiesCria uma empresa nova.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome da empresa. |
domain | string | Não | Nome de domínio. |
industry | string | Não | Indústria. |
parentCompanyId | string | null | Não | Id da empresa matriz (hierarquia). null a deixa no nível superior. Uma empresa não pode ser ancestral de si mesma. |
curl -X POST "https://zerosoft.ai/api/v1/crm/companies" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Norte Labs",
"domain": "nortelabs.co",
"industry": "Software"
}'Requisição
{
"name": "Norte Labs",
"domain": "nortelabs.co",
"industry": "Software"
}Ler uma empresa
/api/v1/crm/companies/{id}Lê uma empresa por id.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/companies/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Atualizar uma empresa
/api/v1/crm/companies/{id}Atualize qualquer propriedade de uma empresa.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
name | string | Não | Nome da empresa. |
domain | string | Não | Nome de domínio. |
industry | string | Não | Indústria. |
parentCompanyId | string | null | Não | Id da empresa matriz (hierarquia). null a deixa no nível superior. Uma empresa não pode ser ancestral de si mesma. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/companies/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"industry": "Cloud infrastructure",
"parentCompanyId": "{company_id}"
}'Requisição
{
"industry": "Cloud infrastructure",
"parentCompanyId": "{company_id}"
}Excluir uma empresa
/api/v1/crm/companies/{id}Exclui a empresa definitivamente. Os contatos continuam existindo sem empresa.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/companies/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Deals
Oportunidades e pipelines.
Listar deals
/api/v1/crm/dealsLista deals. Filtro: pipelineId.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pipelineId | string | Não | Id do pipeline. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/deals" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"deals": [
{
"id": "d9e2…",
"name": "Norte Labs — New business",
"amount": 24000,
"currency": "USD",
"stage_id": "{stage_id}"
}
],
"total": 36,
"page": 1,
"pageSize": 25
}Criar um deal
/api/v1/crm/dealsCria um deal em uma etapa do pipeline.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
pipelineId | string | Sim | Id do pipeline. |
stageId | string | Sim | Id da etapa. |
name | string | Não | Nome do deal. |
amount | number | Não | Valor do deal. |
currency | string | Não | Código da moeda. |
contactIds | string[] | Não | IDs dos contatos a inscrever (1–500). |
companyId | string | Não | Empresa principal do deal. |
companyIds | string[] | Não | Outras empresas para associar ao deal. |
curl -X POST "https://zerosoft.ai/api/v1/crm/deals" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"pipelineId": "{pipeline_id}",
"stageId": "{stage_id}",
"name": "Norte Labs — New business",
"amount": 24000,
"currency": "USD",
"contactIds": [
"{contact_id}"
],
"companyId": "{company_id}"
}'Requisição
{
"pipelineId": "{pipeline_id}",
"stageId": "{stage_id}",
"name": "Norte Labs — New business",
"amount": 24000,
"currency": "USD",
"contactIds": [
"{contact_id}"
],
"companyId": "{company_id}"
}Ler um deal
/api/v1/crm/deals/{id}Lê um deal por id.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/deals/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Atualizar um deal
/api/v1/crm/deals/{id}Atualize valor, etapa ou datas.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
name | string | Não | Nome do deal. |
amount | number | Não | Valor do deal. |
addContactIds | string[] | Não | IDs dos contatos a inscrever (1–500). |
companyId | string | Não | Empresa principal do deal. |
amountOverride | boolean | Não | true mantém um valor manual mesmo com line items; false o recalcula a partir dos line items. Editar o valor de um deal com line items o ativa. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/deals/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"amount": 28000,
"closeDate": "2026-11-30",
"amountOverride": true
}'Requisição
{
"amount": 28000,
"closeDate": "2026-11-30",
"amountOverride": true
}Mover um negócio de etapa
/api/v1/crm/deals/{id}/moveMove o negócio para outra etapa do pipeline. Etapas de ganho/perda o fecham; perda exige lostReason. Se a etapa pede propriedades que o negócio não tem, responde 422 missing_required com a lista; envie-as em fields para preencher e mover numa chamada só. Dispara deal.stage_changed (e deal.won / deal.lost).
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
stageId | string | Sim | Id da etapa. |
lostReason | string | Não | Por que foi perdido (obrigatório em etapas de perda). |
fields | object | Não | Propriedades que a etapa pede, salvas antes de mover: amount, closeDate, ownerId, priority, source, description e custom (valores de custom fields por nome). |
curl -X POST "https://zerosoft.ai/api/v1/crm/deals/{id}/move" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"stageId": "{stage_id}"
}'Requisição
{
"stageId": "{stage_id}"
}Excluir um negócio
/api/v1/crm/deals/{id}Exclui o negócio definitivamente.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/deals/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Atividades
A timeline de um contato, empresa ou negócio: notas, ligações, reuniões, emails e tarefas. Reuniões agendadas no Cal aparecem aqui automaticamente.
Listar a timeline de um registro
/api/v1/crm/activitiesMais recentes primeiro. Passe só um entre contactId, companyId ou dealId.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contactId | companyId | dealId | string | Sim | O registro cuja timeline você quer. |
type | note | task | call | meeting | email | Não | Tipo de atividade. |
limit | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/activities" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"activities": [
{
"id": "a12…",
"type": "meeting",
"subject": "Intro call",
"due_at": "2026-11-03 13:00:00",
"duration_min": 30,
"contact_id": "{contact_id}"
}
]
}Registrar uma atividade
/api/v1/crm/activitiesRegistre uma nota, ligação, reunião ou email em um registro. Tarefas têm endpoint próprio.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | note | call | meeting | email | Sim | Tipo de atividade. |
subject | string | Não | Assunto da tarefa. |
body | string | Não | Texto livre: notas, resumo da ligação, corpo do email. |
contactId | string | Não | Id do contato vinculado. |
dealId | string | Não | Id do deal vinculado. |
curl -X POST "https://zerosoft.ai/api/v1/crm/activities" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"type": "call",
"subject": "Discovery call",
"body": "Budget approved for Q1.",
"durationMin": 25,
"contactId": "{contact_id}"
}'Requisição
{
"type": "call",
"subject": "Discovery call",
"body": "Budget approved for Q1.",
"durationMin": 25,
"contactId": "{contact_id}"
}CRM · Tarefas
Atividades e acompanhamentos.
Listar tarefas
/api/v1/crm/tasksLista tarefas. bucket: overdue, today, upcoming, done.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
bucket | overdue | today | upcoming | done | Não | Bucket de filtro: overdue, today, upcoming, done. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/tasks" \
-H "Authorization: Bearer zs_live_9f3k..."Criar uma tarefa
/api/v1/crm/tasksCria uma tarefa, opcionalmente ligada a um registro.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
subject | string | Sim | Assunto da tarefa. |
dueAt | string (ISO 8601) | Não | Data de vencimento em formato ISO. |
contactId | string | Não | Id do contato vinculado. |
companyId | string | Não | Id da empresa vinculada. |
dealId | string | Não | Id do deal vinculado. |
curl -X POST "https://zerosoft.ai/api/v1/crm/tasks" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"subject": "Follow-up call",
"dueAt": "2026-07-25T15:00:00Z",
"dealId": "{deal_id}"
}'Requisição
{
"subject": "Follow-up call",
"dueAt": "2026-07-25T15:00:00Z",
"dealId": "{deal_id}"
}Atualizar uma tarefa
/api/v1/crm/tasks/{id}Edite ou conclua uma tarefa.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
subject | string | Não | Assunto da tarefa. |
done | boolean | Não | Marcar como concluída. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/tasks/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"done": true
}'Requisição
{
"done": true
}CRM · Pipelines e etapas
Pipelines de vendas e suas etapas.
Listar pipelines
/api/v1/crm/pipelinesLista pipelines com suas etapas.
Escopo crm:read
curl -X GET "https://zerosoft.ai/api/v1/crm/pipelines" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"pipelines": [
{
"id": "{pipeline_id}",
"name": "Sales",
"position": 0,
"stages": [
{
"id": "{stage_id}",
"name": "Qualified",
"position": 0,
"probability": 20,
"isWon": false,
"isLost": false
},
{
"id": "{stage_id}",
"name": "Won",
"position": 5,
"probability": 100,
"isWon": true,
"isLost": false
}
]
}
]
}CRM · Produtos e line items
Catálogo de produtos e os line items de cada deal. Enquanto um deal tiver line items, o valor dele é a soma dos líquidos (depois do desconto, antes dos impostos), a menos que amountOverride esteja ativo.
Listar produtos
/api/v1/crm/productsProdutos do catálogo, ativos primeiro, ordenados por nome.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Buscar por nome ou SKU. |
active | boolean | Não | true = só ativos, false = só arquivados. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/products" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"products": [
{
"id": "{product_id}",
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"price": 1200,
"currency": "USD",
"recurring": "yearly",
"tax_pct": 21,
"active": 1,
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}
],
"total": 12,
"page": 1,
"pageSize": 25
}Criar um produto
/api/v1/crm/productsAdiciona um produto ao catálogo. Sem moeda, usa a moeda base do workspace.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome do produto. |
sku | string | Não | SKU ou código interno. |
description | string | Não | Descrição exibida em line items e orçamentos. |
price | number | Não | Preço unitário. |
currency | string | Não | Código de moeda ISO (por padrão, a moeda base do workspace). |
recurring | none | monthly | yearly | Não | Cobrança: none, monthly ou yearly. |
taxPct | number | Não | Percentual de imposto (0-100). |
active | boolean | Não | false arquiva o produto (some dos seletores). |
curl -X POST "https://zerosoft.ai/api/v1/crm/products" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Pro plan",
"sku": "PRO-Y",
"price": 1200,
"currency": "USD",
"recurring": "yearly",
"taxPct": 21
}'Requisição
{
"name": "Pro plan",
"sku": "PRO-Y",
"price": 1200,
"currency": "USD",
"recurring": "yearly",
"taxPct": 21
}Resposta · 201
{
"id": "{product_id}",
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"price": 1200,
"currency": "USD",
"recurring": "yearly",
"tax_pct": 21,
"active": 1,
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}Obter um produto
/api/v1/crm/products/{id}Retorna um produto.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/products/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{product_id}",
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"price": 1200,
"currency": "USD",
"recurring": "yearly",
"tax_pct": 21,
"active": 1,
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}Atualizar um produto
/api/v1/crm/products/{id}Atualiza os campos enviados. Line items que já estão em deals não mudam.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
price | number | Não | Preço unitário. |
active | boolean | Não | false arquiva o produto (some dos seletores). |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/products/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"price": 1320,
"active": true
}'Requisição
{
"price": 1320,
"active": true
}Excluir um produto
/api/v1/crm/products/{id}Exclui o produto. Os line items que o usavam ficam nos deals como itens personalizados.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/products/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Listar os line items de um deal
/api/v1/crm/deals/{id}/line-itemsLine items com subtotal, desconto, líquido, imposto e total calculados, mais os totais do deal. Os valores são arredondados por linha na moeda do deal.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do deal. |
curl -X GET "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"currency": "USD",
"items": [
{
"id": "{line_item_id}",
"deal_id": "{deal_id}",
"product_id": "{product_id}",
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"quantity": 2,
"unit_price": 1200,
"discount_pct": 10,
"tax_pct": 21,
"recurring": "yearly",
"position": 0,
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6,
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}
],
"totals": {
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6
},
"amountOverride": false
}Adicionar um line item
/api/v1/crm/deals/{id}/line-itemsA partir de um produto (copia nome, preço, imposto e recorrência; o preço é convertido para a moeda do deal se houver taxa de câmbio) ou personalizado (nome e unitPrice). Recalcula o valor do deal.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do deal. |
productId | string | Não | Id do produto do catálogo. Omita para um line item personalizado. |
name | string | Não | Nome do line item (obrigatório em itens personalizados). |
quantity | number | Não | Quantidade (pode ter decimais). |
unitPrice | number | Não | Preço unitário na moeda do deal. |
discountPct | number | Não | Percentual de desconto (0-100). |
taxPct | number | Não | Percentual de imposto (0-100). |
curl -X POST "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"productId": "{product_id}",
"quantity": 2,
"discountPct": 10
}'Requisição
{
"productId": "{product_id}",
"quantity": 2,
"discountPct": 10
}Resposta · 201
{
"id": "{line_item_id}",
"deal_id": "{deal_id}",
"product_id": "{product_id}",
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"quantity": 2,
"unit_price": 1200,
"discount_pct": 10,
"tax_pct": 21,
"recurring": "yearly",
"position": 0,
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6,
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}Atualizar um line item
/api/v1/crm/deals/{id}/line-items/{itemId}Atualiza quantidade, preço, desconto, imposto ou texto e recalcula o valor do deal.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do deal. |
itemId | string | Sim | Id do line item. |
quantity | number | Não | Quantidade (pode ter decimais). |
discountPct | number | Não | Percentual de desconto (0-100). |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items/{itemId}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"quantity": 3,
"discountPct": 15
}'Requisição
{
"quantity": 3,
"discountPct": 15
}Excluir um line item
/api/v1/crm/deals/{id}/line-items/{itemId}Remove o line item e recalcula o valor do deal.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do deal. |
itemId | string | Sim | Id do line item. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/deals/{id}/line-items/{itemId}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Orçamentos
Orçamentos criados a partir dos line items de um deal. Cada um guarda uma cópia dos itens e tem uma página pública (public_url) onde o cliente aceita ou recusa. Ao aceitar, dispara o evento do Flow quote.accepted e o gatilho de workflow quote_accepted.
Listar orçamentos
/api/v1/crm/quotesOrçamentos do workspace, do mais novo ao mais antigo. Os enviados que passaram do vencimento voltam como expired.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
dealId | string | Não | Só os orçamentos deste deal. |
status | draft | sent | accepted | declined | expired | Não | Filtrar por status. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/quotes" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"quotes": [
{
"id": "{quote_id}",
"deal_id": "{deal_id}",
"deal_name": "Norte Labs — New business",
"number": "Q-2026-0003",
"title": "Norte Labs — Pro plan",
"status": "draft",
"currency": "USD",
"items": [
{
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"quantity": 2,
"unit_price": 1200,
"discount_pct": 10,
"tax_pct": 21,
"recurring": "yearly",
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6
}
],
"subtotal": 2400,
"discount_total": 240,
"tax_total": 453.6,
"total": 2613.6,
"expires_at": "2026-11-30",
"terms": "Payment within 30 days of acceptance.",
"notes": "",
"sender_name": "Lucía Pérez",
"sender_email": "lucia@zerosoft.ai",
"sender_company": "Zerosoft",
"recipient_name": "Ana Garcia",
"recipient_email": "ana@nortelabs.co",
"recipient_company": "Norte Labs",
"sent_at": null,
"accepted_at": null,
"declined_at": null,
"signer_name": "",
"public_url": "https://zerosoft.ai/q/7Jx2kQ…",
"created_at": "2026-10-13 12:00:00"
}
],
"total": 3,
"page": 1,
"pageSize": 25
}Criar um orçamento
/api/v1/crm/quotesCria um orçamento em rascunho com os line items atuais do deal (precisa de pelo menos um). Por padrão vence em 30 dias e o destinatário é o primeiro contato e a empresa principal do deal.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
dealId | string | Sim | Deal cujos line items formam o orçamento. |
title | string | Não | Título do orçamento (por padrão, o nome do deal). |
expiresAt | string | Não | Data de vencimento, YYYY-MM-DD. |
terms | string | Não | Termos e condições. |
notes | string | Não | Observações para o cliente. |
senderName | string | Não | Dados do remetente exibidos no orçamento. |
senderEmail | string | Não | Dados do remetente exibidos no orçamento. |
senderCompany | string | Não | Dados do remetente exibidos no orçamento. |
recipientName | string | Não | Dados do destinatário (padrão: primeiro contato e empresa principal do deal). |
recipientEmail | string | Não | Dados do destinatário (padrão: primeiro contato e empresa principal do deal). |
recipientCompany | string | Não | Dados do destinatário (padrão: primeiro contato e empresa principal do deal). |
curl -X POST "https://zerosoft.ai/api/v1/crm/quotes" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"dealId": "{deal_id}",
"title": "Norte Labs — Pro plan",
"expiresAt": "2026-11-30",
"terms": "Payment within 30 days of acceptance.",
"senderName": "Lucía Pérez",
"senderEmail": "lucia@zerosoft.ai",
"senderCompany": "Zerosoft"
}'Requisição
{
"dealId": "{deal_id}",
"title": "Norte Labs — Pro plan",
"expiresAt": "2026-11-30",
"terms": "Payment within 30 days of acceptance.",
"senderName": "Lucía Pérez",
"senderEmail": "lucia@zerosoft.ai",
"senderCompany": "Zerosoft"
}Resposta · 201
{
"id": "{quote_id}",
"deal_id": "{deal_id}",
"deal_name": "Norte Labs — New business",
"number": "Q-2026-0003",
"title": "Norte Labs — Pro plan",
"status": "draft",
"currency": "USD",
"items": [
{
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"quantity": 2,
"unit_price": 1200,
"discount_pct": 10,
"tax_pct": 21,
"recurring": "yearly",
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6
}
],
"subtotal": 2400,
"discount_total": 240,
"tax_total": 453.6,
"total": 2613.6,
"expires_at": "2026-11-30",
"terms": "Payment within 30 days of acceptance.",
"notes": "",
"sender_name": "Lucía Pérez",
"sender_email": "lucia@zerosoft.ai",
"sender_company": "Zerosoft",
"recipient_name": "Ana Garcia",
"recipient_email": "ana@nortelabs.co",
"recipient_company": "Norte Labs",
"sent_at": null,
"accepted_at": null,
"declined_at": null,
"signer_name": "",
"public_url": "https://zerosoft.ai/q/7Jx2kQ…",
"created_at": "2026-10-13 12:00:00"
}Obter um orçamento
/api/v1/crm/quotes/{id}Retorna o orçamento com os itens e o public_url.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/quotes/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{quote_id}",
"deal_id": "{deal_id}",
"deal_name": "Norte Labs — New business",
"number": "Q-2026-0003",
"title": "Norte Labs — Pro plan",
"status": "draft",
"currency": "USD",
"items": [
{
"name": "Pro plan",
"sku": "PRO-Y",
"description": "",
"quantity": 2,
"unit_price": 1200,
"discount_pct": 10,
"tax_pct": 21,
"recurring": "yearly",
"subtotal": 2400,
"discount": 240,
"net": 2160,
"tax": 453.6,
"total": 2613.6
}
],
"subtotal": 2400,
"discount_total": 240,
"tax_total": 453.6,
"total": 2613.6,
"expires_at": "2026-11-30",
"terms": "Payment within 30 days of acceptance.",
"notes": "",
"sender_name": "Lucía Pérez",
"sender_email": "lucia@zerosoft.ai",
"sender_company": "Zerosoft",
"recipient_name": "Ana Garcia",
"recipient_email": "ana@nortelabs.co",
"recipient_company": "Norte Labs",
"sent_at": null,
"accepted_at": null,
"declined_at": null,
"signer_name": "",
"public_url": "https://zerosoft.ai/q/7Jx2kQ…",
"created_at": "2026-10-13 12:00:00"
}Editar ou enviar um orçamento
/api/v1/crm/quotes/{id}Edita um rascunho. status: "sent" publica o link público (draft → sent). Aceitar e recusar acontece na página pública. Se não for rascunho, responde 409 not_draft.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
status | string | Não | "sent" publica o orçamento. |
refreshItems | boolean | Não | Copia de novo os line items atuais do deal (só rascunhos). |
expiresAt | string | Não | Data de vencimento, YYYY-MM-DD. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/quotes/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"refreshItems": true,
"status": "sent"
}'Requisição
{
"refreshItems": true,
"status": "sent"
}CRM · Leads
Leads são prospects antes de virarem negócio: responsável, etapa do pipeline de leads, contato e empresa. Converter um lead cria um negócio pelo app. Campos personalizados de leads vão em custom; os que a key não pode editar retornam 403 field_readonly e os ocultos ficam fora das respostas.
Listar leads
/api/v1/crm/leadsOs leads que a key vê, mais novos primeiro.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
status | open | qualified | disqualified | Não | Só leads em etapas deste tipo. |
stageId | string | Não | Etapa do pipeline de leads. |
contactId | string | Não | Contato associado. |
companyId | string | Não | Empresa associada. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/leads" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"leads": [
{
"id": "f1c2…",
"owner_id": "usr_…",
"name": "Ana Gómez",
"stage_id": "stg_…",
"stage_name": "Connected",
"stage_kind": "open",
"contact_id": "c7a1…",
"company_id": "co_…",
"source": "form",
"disqualify_reason": "",
"deal_id": null,
"converted_at": null,
"custom": "{}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}
],
"total": 1,
"page": 1,
"pageSize": 25
}Criar um lead
/api/v1/crm/leadsPrecisa de nome, contato ou empresa. Sem nome, usa o do contato (ou o da empresa). Sem stageId, começa na primeira etapa aberta.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Não | Nome do lead. |
contactId | string | Não | Contato associado. |
companyId | string | Não | Empresa associada. |
stageId | string | Não | Etapa do pipeline de leads. |
ownerId | string | Não | Pessoa do workspace responsável. Por padrão, quem criou a key. |
source | string | Não | Origem (organic, referral, ads, social, email, event, form, other). |
custom | object | Não | Campos personalizados de leads. |
curl -X POST "https://zerosoft.ai/api/v1/crm/leads" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"contactId": "{contact_id}",
"source": "form"
}'Requisição
{
"contactId": "{contact_id}",
"source": "form"
}Resposta · 201
{
"id": "f1c2…",
"owner_id": "usr_…",
"name": "Ana Gómez",
"stage_id": "stg_…",
"stage_name": "Connected",
"stage_kind": "open",
"contact_id": "c7a1…",
"company_id": "co_…",
"source": "form",
"disqualify_reason": "",
"deal_id": null,
"converted_at": null,
"custom": "{}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}Ver um lead
/api/v1/crm/leads/{id}Um lead com etapa, contato, empresa e negócio.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/leads/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "f1c2…",
"owner_id": "usr_…",
"name": "Ana Gómez",
"stage_id": "stg_…",
"stage_name": "Connected",
"stage_kind": "open",
"contact_id": "c7a1…",
"company_id": "co_…",
"source": "form",
"disqualify_reason": "",
"deal_id": null,
"converted_at": null,
"custom": "{}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}Editar um lead
/api/v1/crm/leads/{id}Muda etapa, responsável, contato, empresa, origem, motivo da desqualificação ou campos personalizados.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
stageId | string | Não | Etapa do pipeline de leads. |
disqualifyReason | string | Não | Por que o lead foi desqualificado. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/leads/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"stageId": "{stage_id}"
}'Requisição
{
"stageId": "{stage_id}"
}Resposta · 200
{
"id": "f1c2…",
"owner_id": "usr_…",
"name": "Ana Gómez",
"stage_id": "stg_…",
"stage_name": "Connected",
"stage_kind": "open",
"contact_id": "c7a1…",
"company_id": "co_…",
"source": "form",
"disqualify_reason": "",
"deal_id": null,
"converted_at": null,
"custom": "{}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}Excluir um lead
/api/v1/crm/leads/{id}Exclui o lead com suas notas e tarefas. O contato, a empresa e o negócio continuam.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/leads/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Objetos personalizados
Registros dos objetos personalizados que um admin definiu (por exemplo veículos ou imóveis). Cada registro tem nome (a propriedade principal), responsável e suas propriedades em custom. As permissões por campo valem como em contatos.
Listar objetos personalizados
/api/v1/crm/objectsOs objetos do workspace com as propriedades que a key vê.
Escopo crm:read
curl -X GET "https://zerosoft.ai/api/v1/crm/objects" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"objects": [
{
"id": "obj_…",
"slug": "vehicles",
"singular": "Vehicle",
"plural": "Vehicles",
"primary_label": "Plate",
"properties": [
{
"name": "model",
"label": "Model",
"type": "text",
"options": [],
"readOnly": false
}
]
}
]
}Listar registros
/api/v1/crm/objects/{slug}/recordsOs registros de um objeto, mais novos primeiro.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | Sim | Slug do objeto (de Listar objetos personalizados). |
q | string | Não | Query de busca. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/objects/{slug}/records" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"records": [
{
"id": "rec_…",
"object_id": "obj_…",
"owner_id": "usr_…",
"name": "AB 123 CD",
"custom": "{\"model\":\"Hilux\",\"year\":2023}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}
],
"total": 1,
"page": 1,
"pageSize": 25
}Criar um registro
/api/v1/crm/objects/{slug}/recordsOs valores de custom são validados com o tipo de cada propriedade; propriedades que não existem são ignoradas.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | Sim | Slug do objeto (de Listar objetos personalizados). |
name | string | Sim | Valor da propriedade principal. |
ownerId | string | Não | Pessoa do workspace responsável. Por padrão, quem criou a key. |
custom | object | Não | Valores das propriedades por nome. |
curl -X POST "https://zerosoft.ai/api/v1/crm/objects/{slug}/records" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "AB 123 CD",
"custom": {
"model": "Hilux",
"year": 2023
}
}'Requisição
{
"name": "AB 123 CD",
"custom": {
"model": "Hilux",
"year": 2023
}
}Resposta · 201
{
"id": "rec_…",
"object_id": "obj_…",
"owner_id": "usr_…",
"name": "AB 123 CD",
"custom": "{\"model\":\"Hilux\",\"year\":2023}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}Ver um registro
/api/v1/crm/objects/{slug}/records/{id}O registro com os ids dos contatos, empresas e negócios associados.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | Sim | Slug do objeto (de Listar objetos personalizados). |
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "rec_…",
"object_id": "obj_…",
"owner_id": "usr_…",
"name": "AB 123 CD",
"custom": "{\"model\":\"Hilux\",\"year\":2023}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00",
"associations": {
"contacts": [
"c7a1…"
],
"companies": [],
"deals": []
}
}Editar um registro
/api/v1/crm/objects/{slug}/records/{id}Muda nome, responsável ou propriedades.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | Sim | Slug do objeto (de Listar objetos personalizados). |
id | string | Sim | Id do registro. |
custom | object | Não | Valores das propriedades por nome. |
curl -X PATCH "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"custom": {
"model": "Hilux",
"year": 2024
}
}'Requisição
{
"custom": {
"model": "Hilux",
"year": 2024
}
}Resposta · 200
{
"id": "rec_…",
"object_id": "obj_…",
"owner_id": "usr_…",
"name": "AB 123 CD",
"custom": "{\"model\":\"Hilux\",\"year\":2023}",
"created_at": "2026-10-24 12:00:00",
"updated_at": "2026-10-24 12:00:00"
}Excluir um registro
/api/v1/crm/objects/{slug}/records/{id}Exclui o registro com suas notas e tarefas.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
slug | string | Sim | Slug do objeto (de Listar objetos personalizados). |
id | string | Sim | Id do registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/objects/{slug}/records/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Associações
Vínculos muitos-para-muitos entre contatos, empresas e deals. Um contato ou deal pode ter várias empresas; uma delas é a principal. contact.company_id sempre reflete a empresa principal.
Listar associações
/api/v1/crm/associationsTodos os registros vinculados a um contato, empresa ou deal. Empresas também retornam a empresa matriz e as filiais.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | contact | company | deal | Sim | Tipo de registro: contact, company ou deal. |
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/associations" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"companies": [
{
"id": "{company_id}",
"name": "Norte Labs",
"domain": "nortelabs.co",
"is_primary": true,
"label": "decision_maker"
},
{
"id": "{company_id}",
"name": "Norte Holding",
"domain": "norte.com",
"is_primary": false,
"label": "billing"
}
],
"deals": [
{
"id": "{deal_id}",
"name": "Norte Labs — New business",
"amount": 24000,
"currency": "USD"
}
]
}Associar dois registros
/api/v1/crm/associationsVincula contato ↔ empresa, deal ↔ empresa ou deal ↔ contato (em qualquer ordem). primary torna a empresa a principal; label só vale para contato ↔ empresa. Se a associação já existir, atualiza principal e label.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
fromType | contact | company | deal | Sim | Tipo do primeiro registro. |
fromId | string | Sim | Id do primeiro registro. |
toType | contact | company | deal | Sim | Tipo do segundo registro. |
toId | string | Sim | Id do segundo registro. |
primary | boolean | Não | Torna esta a empresa principal do contato ou deal. |
label | string | Não | Label de contato ↔ empresa: employee, decision_maker, billing, champion, influencer, former_employee (ou vazio). |
curl -X POST "https://zerosoft.ai/api/v1/crm/associations" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"fromType": "contact",
"fromId": "{contact_id}",
"toType": "company",
"toId": "{company_id}",
"primary": true,
"label": "decision_maker"
}'Requisição
{
"fromType": "contact",
"fromId": "{contact_id}",
"toType": "company",
"toId": "{company_id}",
"primary": true,
"label": "decision_maker"
}Resposta · 201
{
"ok": true
}Remover uma associação
/api/v1/crm/associationsDesvincula dois registros (parâmetros na query). Se você remover a empresa principal, a mais antiga que sobrar vira principal.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
fromType | contact | company | deal | Sim | Tipo do primeiro registro. |
fromId | string | Sim | Id do primeiro registro. |
toType | contact | company | deal | Sim | Tipo do segundo registro. |
toId | string | Sim | Id do segundo registro. |
curl -X DELETE "https://zerosoft.ai/api/v1/crm/associations" \
-H "Authorization: Bearer zs_live_9f3k..."CRM · Formulários
Formulários de captura de leads e seus envios. Cada envio também cria ou atualiza um contato e registra uma atividade "Form submitted".
Listar formulários
/api/v1/crm/formsFormulários do mais novo ao mais antigo, com status, quantidade de respostas e parciais, última resposta e quem pode abri-los.
Escopo crm:read
curl -X GET "https://zerosoft.ai/api/v1/crm/forms" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"forms": [
{
"id": "{form_id}",
"name": "Contact us",
"key": "contact-us",
"slug": "contact-us",
"token": "a1b2c3d4e5f6a7b8c9d0",
"status": "active",
"fields": [
{
"id": "email",
"type": "email",
"label": "Email",
"property": "email",
"required": true
}
],
"submission_count": 42
}
]
}Listar envios de um formulário
/api/v1/crm/forms/{id}/submissionsEnvios de um formulário, os mais recentes primeiro, com os valores, os parâmetros UTM e o contato vinculado.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/crm/forms/{id}/submissions" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"submissions": [
{
"id": "{submission_id}",
"formId": "{form_id}",
"contactId": "{contact_id}",
"contactCreated": true,
"values": {
"email": "ana@kallpa.co",
"first_name": "Ana"
},
"utm": {
"utm_source": "google",
"utm_campaign": "spring"
},
"pageUrl": "https://kallpa.co/pricing?utm_source=google",
"referrer": "",
"createdAt": "2026-10-13 14:02:11"
}
],
"total": 1,
"page": 1,
"pageSize": 25
}CRM · Templates de email e sequências
Templates e snippets de email compartilhados, e sequências de vendas com várias etapas. Os emails das sequências saem do Gmail conectado de quem envia; as etapas rodam no agendador de hora em hora.
Listar templates de email
/api/v1/crm/email-templatesTemplates e snippets compartilhados no workspace. As variáveis ficam entre chaves duplas (contact.first_name, contact.company, deal.name, owner.first_name, contact.custom.x), com um valor padrão opcional depois de uma barra vertical.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
kind | template | snippet | Não | Filtrar por tipo: template ou snippet. |
curl -X GET "https://zerosoft.ai/api/v1/crm/email-templates" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"templates": [
{
"id": "{template_id}",
"kind": "template",
"name": "Intro",
"subject": "Quick question, {{contact.first_name}}",
"body": "Hi {{contact.first_name | there}}, I saw {{contact.company}} is hiring…",
"created_by": "u_123",
"created_at": "2026-10-13 12:00:00",
"updated_at": "2026-10-13 12:00:00"
}
]
}Obter um template de email
/api/v1/crm/email-templates/{id}Retorna um template ou snippet.
Escopo crm:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/crm/email-templates/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Listar sequências
/api/v1/crm/sequencesSequências com o número de etapas e inscrições.
Escopo crm:read
curl -X GET "https://zerosoft.ai/api/v1/crm/sequences" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"sequences": [
{
"id": "{sequence_id}",
"name": "Outbound — 3 touches",
"timezone": "America/Argentina/Buenos_Aires",
"window_start": "09:00",
"window_end": "17:00",
"business_days": 1,
"step_count": 4,
"active_count": 12,
"total_count": 40
}
]
}Inscrever contatos em uma sequência
/api/v1/crm/sequences/{id}/enrollInscreve até 500 contatos. Os que já estão inscritos, cancelaram a inscrição ou não têm email voltam em skipped. Quem envia precisa do Gmail conectado com permissão de envio.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
contactIds | string[] | Sim | IDs dos contatos a inscrever (1–500). |
senderId | string | Não | Membro do workspace cujo Gmail envia os emails. Por padrão, o owner do contato e depois quem criou a sequência. |
curl -X POST "https://zerosoft.ai/api/v1/crm/sequences/{id}/enroll" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"contactIds": [
"{contact_id}"
]
}'Requisição
{
"contactIds": [
"{contact_id}"
]
}Resposta · 201
{
"enrolled": [
"{contact_id}"
],
"skipped": []
}Remover um contato de uma sequência
/api/v1/crm/sequences/{id}/unenrollRemove o contato da sequência (status exited, motivo manual).
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
contactId | string | Sim | Id do contato vinculado. |
curl -X POST "https://zerosoft.ai/api/v1/crm/sequences/{id}/unenroll" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"contactId": "{contact_id}"
}'Requisição
{
"contactId": "{contact_id}"
}Resposta · 200
{
"exited": 1
}Registrar um email do Gmail
/api/v1/crm/extension/log-emailSalva um email na linha do tempo dos contatos que participam. Enviar o mesmo messageId de novo não duplica (200 com duplicate: true). 404 no_contact se nenhum participante for contato.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
messageId | string | Sim | Id da mensagem no Gmail (data-legacy-message-id) |
from | string | Sim | Remetente, como "Ana <ana@acme.com>" |
to | string | Não | Destinatários, separados por vírgulas |
subject | string | Não | Assunto do email |
body | string | Não | Corpo em texto simples |
curl -X POST "https://zerosoft.ai/api/v1/crm/extension/log-email" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"messageId": "18c2f0a1b2c3d4e5",
"from": "Ana <ana@acme.com>",
"to": "you@yourco.com",
"subject": "Pricing",
"body": "Hi…"
}'Requisição
{
"messageId": "18c2f0a1b2c3d4e5",
"from": "Ana <ana@acme.com>",
"to": "you@yourco.com",
"subject": "Pricing",
"body": "Hi…"
}Resposta · 201
{
"ok": true,
"emailId": "{email_id}",
"contactIds": [
"{contact_id}"
],
"duplicate": false
}Registrar e rastrear um email antes de enviar
/api/v1/crm/extension/trackSalva o email de saída e devolve o pixel de aberturas para adicionar ao corpo. Se nenhum destinatário for contato, o primeiro é criado como contato.
Escopo crm:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
to | string | Sim | Destinatários, separados por vírgulas |
subject | string | Não | Assunto do email |
body | string | Não | Corpo em texto simples |
curl -X POST "https://zerosoft.ai/api/v1/crm/extension/track" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"to": "ana@acme.com",
"subject": "Proposal",
"body": "Hi Ana…"
}'Requisição
{
"to": "ana@acme.com",
"subject": "Proposal",
"body": "Hi Ana…"
}Resposta · 201
{
"ok": true,
"emailId": "{email_id}",
"pixelUrl": "https://zerosoft.ai/api/crm/t/o/{token}.gif",
"contactIds": [
"{contact_id}"
],
"createdContact": false
}Cal
Tipos de evento e reservas. Reservas criadas pela API seguem as mesmas regras da página pública (disponibilidade, intervalos, ocupado no Google Calendar) e enviam os mesmos emails.
Listar tipos de evento
/api/v1/calendar/event-typesSeus tipos de evento com a URL pública de agendamento.
Escopo cal:read
curl -X GET "https://zerosoft.ai/api/v1/calendar/event-types" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"eventTypes": [
{
"id": "et_42",
"slug": "intro",
"title": "Intro call",
"durationMin": 30,
"active": true,
"url": "https://zerosoft.ai/en/book/ana/intro"
}
]
}Listar reservas
/api/v1/calendar/bookingsReservas dos seus tipos de evento, mais novas primeiro. Filtre por status e período.
Escopo cal:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | confirmed | cancelled | no_show | pending | Não | Só reservas com este status. |
q | string | Não | Busca no nome ou no email do convidado. |
from | ISO 8601 | Não | Início a partir de (inclusive). |
to | ISO 8601 | Não | Início até (inclusive). |
curl -X GET "https://zerosoft.ai/api/v1/calendar/bookings" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"bookings": [
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}
]
}Criar uma reserva
/api/v1/calendar/bookingsReserva um horário para um convidado. Retorna 409 slot_unavailable se o horário não for mais oferecido.
Escopo cal:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
eventTypeId | string | Sim | Id do tipo de evento (de Listar tipos de evento). |
start | ISO 8601 | Sim | Início do horário; precisa coincidir com um oferecido. |
name | string | Sim | Nome do convidado. |
email | string | Sim | Email do convidado: recebe a confirmação e o convite de calendário. |
timezone | IANA | Não | Fuso do convidado para os emails. Padrão UTC. |
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"eventTypeId": "et_42",
"start": "2026-11-03T13:00:00.000Z",
"name": "Ana",
"email": "ana@example.com",
"timezone": "America/Argentina/Buenos_Aires"
}'Requisição
{
"eventTypeId": "et_42",
"start": "2026-11-03T13:00:00.000Z",
"name": "Ana",
"email": "ana@example.com",
"timezone": "America/Argentina/Buenos_Aires"
}Resposta · 201
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}Obter uma reserva
/api/v1/calendar/bookings/:idUma reserva por id (dono do tipo de evento ou host atribuído).
Escopo cal:read
curl -X GET "https://zerosoft.ai/api/v1/calendar/bookings/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}Cancelar uma reserva
/api/v1/calendar/bookings/:id/cancelCancela uma reserva confirmada, envia ao convidado o cancelamento com .ics, remove o evento do Google Calendar e emite booking.cancelled.
Escopo cal:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
reason | string | Não | Mostrado ao convidado no email de cancelamento. |
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/cancel" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"reason": "Customer asked to move it to next month"
}'Requisição
{
"reason": "Customer asked to move it to next month"
}Resposta · 200
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "cancelled",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": "Customer asked to move it to next month",
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}Reagendar uma reserva
/api/v1/calendar/bookings/:id/rescheduleMove uma reserva confirmada para outro horário oferecido, envia ao convidado o .ics atualizado e emite booking.rescheduled. Retorna 409 slot_unavailable se o horário não é oferecido.
Escopo cal:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
start | ISO 8601 | Sim | Início do horário; precisa coincidir com um oferecido. |
timezone | IANA | Não | Fuso do convidado para os emails. Padrão UTC. |
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/reschedule" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"start": "2026-11-04T14:00:00.000Z"
}'Requisição
{
"start": "2026-11-04T14:00:00.000Z"
}Resposta · 200
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-04T14:00:00.000Z",
"endsAt": "2026-11-04T14:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}Marcar ausência
/api/v1/calendar/bookings/:id/no-showMarca que o convidado não apareceu. Só para reservas confirmadas.
Escopo cal:write
curl -X POST "https://zerosoft.ai/api/v1/calendar/bookings/:id/no-show" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "no_show",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}Agents
Converse com seus agentes de AI a partir do seu próprio app. O agente usa as mesmas instruções, conhecimento e ferramentas do Chat e da página pública; cada resposta conta para a cota de AI do workspace.
Enviar uma mensagem a um agente
/api/v1/agents/:id/messagesRetorna a resposta do agente e as ferramentas que usou. Envie o conversationId retornado para continuar a mesma conversa. Erros: 404 not_found, 403 agent_disabled, 429 rate_limited, 503 ai_disabled.
Escopo agents:run
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
message | string | Sim | O que o usuário diz (até 4000 caracteres). |
conversationId | string | Não | Continua uma conversa de API existente. Omita para começar uma nova. |
curl -X POST "https://zerosoft.ai/api/v1/agents/:id/messages" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"message": "Do you ship to Brazil?"
}'Requisição
{
"message": "Do you ship to Brazil?"
}Resposta · 200
{
"conversationId": "6b0f8f7e-2a43-4d0c-9a51-3f3c1f1b8e21",
"message": {
"id": "b7e1…",
"role": "assistant",
"content": "Yes! We ship to Brazil in 5–7 business days.",
"createdAt": "2026-11-01T18:00:00.000Z"
},
"status": "replied",
"handoff": false,
"toolCalls": [
{
"tool": "search_knowledge",
"input": {
"query": "shipping Brazil"
},
"output": {
"results": []
},
"error": null
}
]
}Chat
Leia e responda as conversas do inbox do Chat a partir do seu app ou helpdesk. Precisa do scope chat:read para ler e chat:write para responder, atribuir e resolver. As respostas saem em nome de quem criou a key.
Listar conversas
/api/v1/chat/conversationsConversas dos widgets do workspace, as atualizadas mais recentemente primeiro.
Escopo chat:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | open | pending | snoozed | resolved | Não | Só conversas com este status. |
assignedTo | string | Não | Só conversas atribuídas a este id de usuário, ou unassigned. |
widgetId | string | Não | Só conversas deste widget. |
limit | integer | Não | Quantas devolver (de 1 a 200, 50 por padrão). |
offset | integer | Não | Quantas pular, para paginar. |
curl -X GET "https://zerosoft.ai/api/v1/chat/conversations" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"conversations": [
{
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
}
],
"total": 1,
"limit": 50,
"offset": 0
}Ver uma conversa
/api/v1/chat/conversations/{id}A conversa e todas as suas mensagens, da mais antiga para a mais nova. As notas internas vêm com isNote: true.
Escopo chat:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id do registro. |
curl -X GET "https://zerosoft.ai/api/v1/chat/conversations/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"conversation": {
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
},
"messages": [
{
"id": "{message_id}",
"conversationId": "{conversation_id}",
"senderType": "user",
"userId": "{user_id}",
"body": "Hi Ana, the order ships tomorrow.",
"isNote": false,
"attachments": [],
"createdAt": "2026-11-01T18:02:00.000Z"
}
]
}Responder
/api/v1/chat/conversations/{id}/messagesEnvia uma mensagem ao visitante (ou uma nota interna com note: true). Como uma resposta do inbox, conta como primeira resposta para o SLA e reabre a conversa se estava resolvida. Dispara chat.message.created.
Escopo chat:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
body | string | Sim | Texto da mensagem (até 5000 caracteres). |
note | boolean | Não | true para deixar uma nota interna que o visitante não vê. |
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/messages" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"body": "Hi Ana, the order ships tomorrow."
}'Requisição
{
"body": "Hi Ana, the order ships tomorrow."
}Resposta · 201
{
"id": "{message_id}",
"conversationId": "{conversation_id}",
"senderType": "user",
"userId": "{user_id}",
"body": "Hi Ana, the order ships tomorrow.",
"isNote": false,
"attachments": [],
"createdAt": "2026-11-01T18:02:00.000Z"
}Atribuir
/api/v1/chat/conversations/{id}/assignAtribui a conversa a um agente do widget, ou a deixa sem atribuição com null. Dispara chat.conversation.assigned. Erros: 400 invalid_assignee.
Escopo chat:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
assignedTo | string | Sim | Id de usuário do agente, ou null para tirar a atribuição. |
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/assign" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"assignedTo": "{user_id}"
}'Requisição
{
"assignedTo": "{user_id}"
}Resposta · 200
{
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
}Resolver
/api/v1/chat/conversations/{id}/resolveMarca a conversa como resolvida. Se o widget tem atributos obrigatórios vazios, responde 400 missing_attributes. Dispara chat.conversation.resolved.
Escopo chat:write
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/resolve" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "resolved",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": "2026-11-01T18:10:00.000Z",
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
}Reabrir
/api/v1/chat/conversations/{id}/reopenAbre de novo uma conversa resolvida ou adiada.
Escopo chat:write
curl -X POST "https://zerosoft.ai/api/v1/chat/conversations/{id}/reopen" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
}Robots
Execute seus robôs de navegador a partir do seu próprio app, um de cada vez ou sobre muitas entradas. As execuções passam pela mesma fila do app (uma por vez por workspace) e contam para os minutos mensais de robôs. Para executar é preciso uma key criada por um admin do workspace.
Listar robôs
/api/v1/robotsRetorna os robôs do workspace com suas entradas, para saber o que enviar ao executá-los.
Escopo robots:run
curl -X GET "https://zerosoft.ai/api/v1/robots" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"robots": [
{
"id": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
"name": "Price check",
"description": "",
"enabled": true,
"inputs": [
{
"name": "url",
"label": "Product URL",
"kind": "text",
"default": "",
"required": true
}
],
"updatedAt": "2026-11-01T18:00:00.000Z"
}
]
}Executar um robô
/api/v1/robots/:id/runsColoca uma execução na fila e responde 202 com a execução; consulte GET /api/v1/robots/runs/:id até que status seja success ou failed. Com "wait": true a resposta espera o resultado (200) se não houver outra execução na frente. O robô precisa ter as execuções automáticas ativadas. Erros: 404 not_found, 400 missing_input ou disabled, 409 busy, 429 rate_limited ou quota_exceeded, 503 runner_unavailable.
Escopo robots:run
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
inputs | object | Não | Entradas do robô por nome. Entradas do tipo lista recebem um array de textos. |
wait | boolean | Não | Esperar o resultado na mesma resposta (até o timeout do robô). Padrão false. |
curl -X POST "https://zerosoft.ai/api/v1/robots/:id/runs" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"inputs": {
"url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
}
}'Requisição
{
"inputs": {
"url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
}
}Resposta · 202
{
"run": {
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
"status": "queued",
"trigger": "api",
"input": {
"url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
},
"output": {},
"error": null,
"warnings": 0,
"changed": null,
"batchId": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"startedAt": null,
"finishedAt": null,
"durationMs": null
}
}Ver uma execução
/api/v1/robots/runs/:idStatus, entradas e dados extraídos de uma execução. changed diz se os dados diferem da execução bem-sucedida anterior com as mesmas entradas (null se não havia com o que comparar).
Escopo robots:run
curl -X GET "https://zerosoft.ai/api/v1/robots/runs/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"run": {
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
"status": "success",
"trigger": "api",
"input": {
"url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
},
"output": {
"title": "A Light in the Attic",
"price": "£51.77"
},
"error": null,
"warnings": 0,
"changed": false,
"batchId": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"startedAt": "2026-11-01T18:00:01.000Z",
"finishedAt": "2026-11-01T18:00:06.000Z",
"durationMs": 5000
}
}Executar um robô sobre muitas entradas
/api/v1/robots/:id/bulkColoca na fila uma execução por item de inputs (até 1.000 por pedido) sob um id de lote. Para chegar a 50.000, envie partes com o mesmo batchId, o offset da primeira linha de cada parte e total: nenhuma execução começa até todas as linhas chegarem, e reenviar uma parte não a duplica. As execuções seguem o ajuste de execuções simultâneas do workspace; cada entrada do pedido é validada antes de algo entrar na fila. Erros: 400 missing_input (com o índice do item), 409 busy, 429 rate_limited.
Escopo robots:run
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
inputs | object[] | Sim | Um objeto de entradas por execução, de 1 a 1.000 por pedido. |
curl -X POST "https://zerosoft.ai/api/v1/robots/:id/bulk" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"inputs": [
{
"url": "https://example.com/a"
},
{
"url": "https://example.com/b"
}
]
}'Requisição
{
"inputs": [
{
"url": "https://example.com/a"
},
{
"url": "https://example.com/b"
}
]
}Resposta · 202
{
"batchId": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"total": 2,
"runs": [
{
"id": "1f2e3d4c-…",
"status": "queued",
"input": {
"url": "https://example.com/a"
}
},
{
"id": "5b6a7c8d-…",
"status": "queued",
"input": {
"url": "https://example.com/b"
}
}
]
}Ver um lote
/api/v1/robots/batches/:idContagens por status, done quando todas terminaram e uma página de execuções na ordem em que você enviou: ?limit= (até 1.000, o padrão) e ?offset=. nextOffset é o offset da próxima página, ou null na última.
Escopo robots:run
curl -X GET "https://zerosoft.ai/api/v1/robots/batches/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"batchId": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"robotId": "c1f2a9d4-7b1e-4c2a-9f0e-1a2b3c4d5e6f",
"total": 2,
"counts": {
"queued": 0,
"running": 1,
"success": 1,
"failed": 0
},
"done": false,
"nextOffset": null,
"runs": [
{
"id": "1f2e3d4c-…",
"status": "success",
"input": {
"url": "https://example.com/a"
},
"output": {
"title": "A"
},
"error": null
},
{
"id": "5b6a7c8d-…",
"status": "running",
"input": {
"url": "https://example.com/b"
},
"output": {},
"error": null
}
]
}Lines (WhatsApp)
Leia chats e grupos de WhatsApp, envie mensagens e crie tickets a partir dos seus sistemas. As mensagens saem do número ao qual o chat pertence.
Listar chats e grupos
/api/v1/groups/chatsChats e grupos abertos, os mais recentes primeiro, com etiquetas, responsável e se esperam resposta.
Escopo groups:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
filter | string | Não | all, unread, unanswered, flagged, mine, unassigned ou closed |
q | string | Não | Query de busca. |
kind | string | Não | group ou dm |
curl -X GET "https://zerosoft.ai/api/v1/groups/chats" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "gc_1",
"kind": "group",
"name": "Acme · Support",
"memberCount": 12,
"assignedTo": null,
"labels": [
{
"id": "gl_1",
"name": "Enterprise",
"color": "blue"
}
],
"unread": 2,
"lastMessageAt": "2026-11-01T18:00:00.000Z",
"awaitingSince": "2026-11-01T18:00:00.000Z",
"flagged": false
}
],
"total": 1
}Listar mensagens
/api/v1/groups/chats/:id/messagesMensagens e notas internas de um chat, da mais antiga para a mais nova.
Escopo groups:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
after | string | Não | Só mensagens depois desta data ISO |
curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id/messages" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "gm_1",
"direction": "in",
"senderName": "Ana",
"senderPhone": "5491155550000",
"body": "The October invoice did not arrive",
"status": "received",
"createdAt": "2026-11-01T18:00:00.000Z"
}
]
}Enviar uma mensagem
/api/v1/groups/chats/:id/messagesEnvia um WhatsApp para o chat ou grupo, ou salva uma nota interna com note: true.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
body | string | Sim | Texto da mensagem (até 4096 caracteres) |
note | boolean | Não | Salvar como nota interna em vez de enviar |
poll | object | Não | Objeto com question, options (2 a 12) e multi, no lugar de body. Só WAHA e Evolution |
media | object | Não | Objeto com url (https pública), mimetype e filename |
curl -X POST "https://zerosoft.ai/api/v1/groups/chats/:id/messages" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"body": "Hi Ana, resending it now."
}'Requisição
{
"body": "Hi Ana, resending it now."
}Resposta · 201
{
"data": {
"id": "gm_2",
"direction": "out",
"body": "Hi Ana, resending it now.",
"status": "sent",
"createdAt": "2026-11-01T18:01:00.000Z"
}
}Listar tickets
/api/v1/groups/ticketsTickets criados a partir de mensagens de WhatsApp, com o status de SLA.
Escopo groups:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string | Não | active (padrão), all, open, in_progress, resolved ou closed |
curl -X GET "https://zerosoft.ai/api/v1/groups/tickets" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "gt_1",
"number": 12,
"title": "Invoice did not arrive",
"status": "open",
"priority": "high",
"source": "reaction",
"dueAt": "2026-11-02T18:00:00.000Z",
"breached": false
}
]
}Criar um ticket
/api/v1/groups/ticketsCria um ticket em um chat. Com messageId, uma mensagem tem no máximo um ticket: repetir devolve o existente.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chatId | string | Sim | Id do chat ou grupo |
title | string | Não | Título do ticket (padrão: a primeira linha da mensagem) |
priority | string | Não | low, medium, high ou urgent |
curl -X POST "https://zerosoft.ai/api/v1/groups/tickets" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"chatId": "gc_1",
"title": "Invoice did not arrive",
"priority": "high"
}'Requisição
{
"chatId": "gc_1",
"title": "Invoice did not arrive",
"priority": "high"
}Resposta · 201
{
"data": {
"id": "gt_1",
"number": 12,
"title": "Invoice did not arrive",
"status": "open",
"priority": "high",
"source": "api"
}
}Ver um chat
/api/v1/groups/chats/:idUm chat ou grupo com etiquetas, responsável e membros.
Escopo groups:read
curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "gc_1",
"kind": "group",
"name": "Acme · Support",
"memberCount": 12,
"status": "open",
"labels": [],
"members": [
{
"phone": "5491155550000",
"name": "Ana",
"role": "admin"
}
]
}
}Atualizar um chat
/api/v1/groups/chats/:idAtribuir, fechar ou reabrir, trocar etiquetas, renomear (também no WhatsApp se for grupo) ou definir propriedades. As mudanças ficam na auditoria.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
assignedTo | string | Não | Id de uma pessoa do workspace, ou null para tirar |
status | open | closed | Não | open ou closed |
labelIds | string[] | Não | Ids de etiquetas (substituem as atuais) |
name | string | Não | Nome |
curl -X PATCH "https://zerosoft.ai/api/v1/groups/chats/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"assignedTo": "u_1",
"labelIds": [
"gl_1"
]
}'Requisição
{
"assignedTo": "u_1",
"labelIds": [
"gl_1"
]
}Resposta · 200
{
"data": {
"id": "gc_1",
"assignedTo": "u_1",
"status": "open",
"labels": [
{
"id": "gl_1",
"name": "Enterprise",
"color": "blue"
}
]
}
}Listar membros de um grupo
/api/v1/groups/chats/:id/membersMembros de um grupo com o papel (member, admin ou superadmin).
Escopo groups:read
curl -X GET "https://zerosoft.ai/api/v1/groups/chats/:id/members" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"phone": "5491155550000",
"name": "Ana",
"role": "admin"
}
]
}Adicionar, remover ou promover membros
/api/v1/groups/chats/:id/membersMuda membros no WhatsApp (números WAHA ou Evolution). Com action invite devolve o link de convite; revoke: true gera um novo.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
action | add | remove | promote | demote | invite | Sim | O que fazer com os telefones |
phones | string[] | Não | Telefones em formato internacional |
curl -X POST "https://zerosoft.ai/api/v1/groups/chats/:id/members" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"action": "add",
"phones": [
"+5491155550001"
]
}'Requisição
{
"action": "add",
"phones": [
"+5491155550001"
]
}Resposta · 200
{
"data": {
"results": [
{
"phone": "5491155550001",
"ok": true
}
],
"members": []
}
}Criar grupos
/api/v1/groups/groupsCria um grupo de WhatsApp, ou até 50 com groups: [...]. Os telefones que o WhatsApp não deixou adicionar voltam em notAdded.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
numberId | string | Sim | Número que cria o grupo (WAHA ou Evolution) |
name | string | Sim | Nome |
phones | string[] | Não | Telefones em formato internacional |
curl -X POST "https://zerosoft.ai/api/v1/groups/groups" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"numberId": "gn_1",
"name": "Acme · Onboarding",
"phones": [
"+5491155550001"
]
}'Requisição
{
"numberId": "gn_1",
"name": "Acme · Onboarding",
"phones": [
"+5491155550001"
]
}Resposta · 201
{
"data": [
{
"name": "Acme · Onboarding",
"ok": true,
"chatId": "gc_2",
"notAdded": []
}
]
}Listar números
/api/v1/groups/numbersNúmeros de WhatsApp conectados com provedor, status e recursos. As credenciais nunca são devolvidas.
Escopo groups:read
curl -X GET "https://zerosoft.ai/api/v1/groups/numbers" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "gn_1",
"name": "Support line",
"provider": "waha",
"phone": "5491155550000",
"status": "connected"
}
]
}Listar etiquetas
/api/v1/groups/labelsEtiquetas do workspace com quantos chats tem cada uma.
Escopo groups:read
curl -X GET "https://zerosoft.ai/api/v1/groups/labels" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "gl_1",
"name": "Enterprise",
"color": "blue",
"count": 4
}
]
}Criar uma etiqueta
/api/v1/groups/labelsCores: gray, red, orange, yellow, green, teal, blue, purple ou pink.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome |
curl -X POST "https://zerosoft.ai/api/v1/groups/labels" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Enterprise",
"color": "blue"
}'Requisição
{
"name": "Enterprise",
"color": "blue"
}Resposta · 201
{
"data": {
"id": "gl_1",
"name": "Enterprise",
"color": "blue"
}
}Ver um ticket
/api/v1/groups/tickets/:idO ticket com os tickets vinculados no Freshdesk ou Zoho Desk, se houver.
Escopo groups:read
curl -X GET "https://zerosoft.ai/api/v1/groups/tickets/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "gt_1",
"number": 12,
"title": "Invoice did not arrive",
"status": "open",
"links": [
{
"kind": "freshdesk",
"remoteId": "1042",
"remoteUrl": "https://acme.freshdesk.com/a/tickets/1042"
}
]
}
}Atualizar um ticket
/api/v1/groups/tickets/:idStatus, prioridade, responsável ou título. O novo status vai para os tickets vinculados do Freshdesk ou Zoho Desk.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string | Não | active (padrão), all, open, in_progress, resolved ou closed |
priority | string | Não | low, medium, high ou urgent |
assigneeId | string | Não | Id de uma pessoa do workspace, ou null para tirar |
curl -X PATCH "https://zerosoft.ai/api/v1/groups/tickets/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"status": "resolved"
}'Requisição
{
"status": "resolved"
}Resposta · 200
{
"data": {
"id": "gt_1",
"number": 12,
"status": "resolved"
}
}Fazer um envio em massa
/api/v1/groups/broadcastsEnvia uma mensagem ou enquete para muitos chats e grupos de um número, no ritmo escolhido (perMinute). Com scheduledAt sai depois.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chatIds | string[] | Sim | Ids de chats e grupos |
body | string | Não | Texto da mensagem (até 4096 caracteres) |
poll | object | Não | Objeto com question, options (2 a 12) e multi, no lugar de body. Só WAHA e Evolution |
scheduledAt | string | Não | Data ISO para enviar depois |
curl -X POST "https://zerosoft.ai/api/v1/groups/broadcasts" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"chatIds": [
"gc_1",
"gc_2"
],
"body": "Hi {{first_name}}, the new release is live.",
"perMinute": 20
}'Requisição
{
"chatIds": [
"gc_1",
"gc_2"
],
"body": "Hi {{first_name}}, the new release is live.",
"perMinute": 20
}Resposta · 201
{
"data": {
"id": "gb_1",
"status": "scheduled",
"total": 2
}
}Criar uma mensagem recorrente
/api/v1/groups/recurringRepete uma mensagem ou enquete todo dia, toda semana, todo mês ou com uma expressão cron. GET na mesma rota lista com a próxima execução.
Escopo groups:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
chatIds | string[] | Sim | Ids de chats e grupos |
rule | object | Sim | Objeto com freq (daily, weekly, monthly ou cron), time (HH:MM), days (0 a 6), dayOfMonth ou cron |
timezone | string | Não | Fuso horário IANA (padrão UTC) |
endsAt | string | Não | Data ISO de fim, opcional |
curl -X POST "https://zerosoft.ai/api/v1/groups/recurring" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"chatIds": [
"gc_1"
],
"body": "Weekly check-in: anything blocking you?",
"rule": {
"freq": "weekly",
"days": [
1
],
"time": "09:00"
},
"timezone": "America/Argentina/Buenos_Aires"
}'Requisição
{
"chatIds": [
"gc_1"
],
"body": "Weekly check-in: anything blocking you?",
"rule": {
"freq": "weekly",
"days": [
1
],
"time": "09:00"
},
"timezone": "America/Argentina/Buenos_Aires"
}Resposta · 201
{
"data": {
"id": "gr_1",
"status": "active",
"nextRunAt": "2026-11-02T12:00:00.000Z"
}
}Servidor MCP
/api/v1/groups/mcpModel Context Protocol por streamable HTTP (JSON-RPC). Métodos: initialize, tools/list, tools/call. Ferramentas: list_chats, get_messages, send_message, send_poll, update_chat, list_labels, create_ticket, list_tickets, update_ticket. As que escrevem pedem groups:write.
Escopo groups:read
curl -X POST "https://zerosoft.ai/api/v1/groups/mcp" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_chats",
"arguments": {
"filter": "unanswered"
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_chats",
"arguments": {
"filter": "unanswered"
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"total\":1,\"chats\":[...]}"
}
],
"isError": false
}
}Voice
Ditado e transcrições de reuniões. O app desktop usa estes endpoints com uma chave com voice:read e voice:write. O áudio é transcrito e descartado.
Ditar
/api/v1/voice/dictateEnvia um áudio em multipart. Devolve a transcrição limpa com o dicionário e o estilo da pessoa e salva no histórico de ditados.
Escopo voice:write
curl -X POST "https://zerosoft.ai/api/v1/voice/dictate" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"audio": "(multipart file, webm/ogg/wav/m4a/mp3, up to 4 MB)",
"context": "email",
"sourceApp": "Mail",
"durationMs": 5200
}'Requisição
{
"audio": "(multipart file, webm/ogg/wav/m4a/mp3, up to 4 MB)",
"context": "email",
"sourceApp": "Mail",
"durationMs": 5200
}Resposta · 201
{
"data": {
"id": "vs_1",
"text": "The launch is on Tuesday.",
"raw": "um the launch is on monday, no, I mean tuesday",
"ai": true
}
}Listar sessões
/api/v1/voice/sessionsDitados e reuniões de quem criou a chave, da mais nova para a mais antiga.
Escopo voice:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
kind | string | Não | meeting ou dictation. |
q | string | Não | Query de busca. |
curl -X GET "https://zerosoft.ai/api/v1/voice/sessions" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "vs_2",
"kind": "meeting",
"title": "Acme pricing call",
"status": "done",
"durationMs": 1820000,
"startedAt": "2026-11-02T15:00:00.000Z"
}
]
}Criar uma reunião
/api/v1/voice/sessionsInicia uma reunião para enviar trechos de áudio.
Escopo voice:write
curl -X POST "https://zerosoft.ai/api/v1/voice/sessions" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Acme pricing call"
}'Requisição
{
"title": "Acme pricing call"
}Resposta · 201
{
"data": {
"id": "vs_2",
"title": "Acme pricing call",
"status": "recording",
"startedAt": "2026-11-02T15:00:00.000Z"
}
}Enviar um trecho de áudio
/api/v1/voice/sessions/:id/chunksTranscreve um trecho da reunião. source é me (microfone), them (áudio do sistema) ou mixed. Idempotente por source e seq.
Escopo voice:write
curl -X POST "https://zerosoft.ai/api/v1/voice/sessions/:id/chunks" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"audio": "(multipart file, up to 4 MB)",
"source": "them",
"seq": 200,
"offsetMs": 20000,
"durationMs": 20000
}'Requisição
{
"audio": "(multipart file, up to 4 MB)",
"source": "them",
"seq": 200,
"offsetMs": 20000,
"durationMs": 20000
}Resposta · 201
{
"data": {
"duplicate": false,
"segments": [
{
"id": "sg_1",
"source": "them",
"speaker": "0",
"startMs": 20400,
"endMs": 24100,
"text": "Twenty dollars works for us."
}
]
}
}Ver uma sessão
/api/v1/voice/sessions/:idA sessão com a transcrição, as notas e a nota com IA.
Escopo voice:read
curl -X GET "https://zerosoft.ai/api/v1/voice/sessions/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "vs_2",
"title": "Acme pricing call",
"segments": [],
"myNotes": "",
"enhanced": null
}
}Atualizar uma sessão
/api/v1/voice/sessions/:idMudar o título, ou definir status como done ao terminar a gravação.
Escopo voice:write
curl -X PATCH "https://zerosoft.ai/api/v1/voice/sessions/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"status": "done"
}'Requisição
{
"status": "done"
}Resposta · 200
{
"data": {
"id": "vs_2",
"title": "Acme pricing call",
"status": "done",
"durationMs": 1820000
}
}Dicionário e ajustes
/api/v1/voice/dictionaryPalavras, substituições, snippets e ajustes de ditado da pessoa, para sincronizar o app desktop.
Escopo voice:read
curl -X GET "https://zerosoft.ai/api/v1/voice/dictionary" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"entries": [
{
"id": "vd_1",
"kind": "replace",
"phrase": "zero soft",
"replacement": "zerosoft"
}
],
"settings": {
"language": "auto",
"shortcut": "Alt+Space"
}
}
}Track
Issues, comentários, equipes, cycles, status, labels e pessoas do Track. Use uma key com track:read ou track:write. Os issues criados pela API vão para triage se a equipe tiver ativo, e cada mudança deixa atividade, avisos, webhooks e uma entrada de audit como o app. As equipes antes se chamavam projetos: /api/v1/track/projects e projectId continuam funcionando.
Listar issues
/api/v1/track/issuesIssues que a key vê, os editados mais recentes primeiro, com filtros.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
teamId | string | Não | Id ou chave da equipe (WEB). projectId também funciona. |
statusCategory | backlog | todo | in_progress | done | cancelled | Não | Categoria do status. |
assigneeId | string | Não | Id da pessoa atribuída. |
priority | urgent | high | medium | low | Não | Prioridade. |
q | string | Não | Query de busca. |
updatedSince | string | Não | Só issues editados desde esta data ISO. |
page | integer | Não | Número da página. |
pageSize | integer | Não | Items por página (máx 100). |
curl -X GET "https://zerosoft.ai/api/v1/track/issues" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"url": "https://zerosoft.ai/app/track/issues/{issue_id}",
"projectId": "{team_id}",
"teamId": "{team_id}",
"planId": null,
"status": {
"id": "{status_id}",
"name": "In Progress",
"category": "in_progress",
"color": "#000000"
},
"priority": "high",
"assignee": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"creatorId": "{user_id}",
"cycle": {
"id": "{cycle_id}",
"name": "Cycle 4"
},
"milestoneId": null,
"parentId": null,
"estimate": 3,
"labels": [
{
"id": "{label_id}",
"name": "bug",
"color": "#d14343"
}
],
"startDate": null,
"dueDate": "2026-11-04",
"triage": false,
"source": "api",
"createdAt": "2026-10-25T14:02:11.000Z",
"updatedAt": "2026-10-25T15:10:00.000Z"
}
],
"page": 1,
"pageSize": 50,
"total": 1,
"hasMore": false
}Criar um issue
/api/v1/track/issuesteamId aceita o id ou a chave (WEB); projectId é o nome anterior. status aceita o nome do status ou uma categoria. Os links do Sentry, Zendesk, Intercom ou Figma ficam vinculados ao issue.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
teamId | string | Sim | Id ou chave da equipe (WEB). projectId também funciona. |
title | string | Sim | Título do issue. |
description | string | Não | Descrição em markdown. |
status | string | Não | Nome do status ("In Progress") ou categoria (in_progress). |
priority | urgent | high | medium | low | Não | Prioridade. |
assigneeEmail | string | Não | Email de um membro da equipe. |
labels | string[] | Não | Nomes de labels; os que não existem são criados. |
dueDate | string | Não | Prazo, YYYY-MM-DD. |
links | string[] | Não | URLs do Sentry, Zendesk, Intercom ou Figma para vincular. |
curl -X POST "https://zerosoft.ai/api/v1/track/issues" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"teamId": "WEB",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"priority": "high",
"labels": [
"bug"
],
"links": [
"https://acme.zendesk.com/agent/tickets/4812"
]
}'Requisição
{
"teamId": "WEB",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"priority": "high",
"labels": [
"bug"
],
"links": [
"https://acme.zendesk.com/agent/tickets/4812"
]
}Resposta · 201
{
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"url": "https://zerosoft.ai/app/track/issues/{issue_id}",
"projectId": "{team_id}",
"teamId": "{team_id}",
"planId": null,
"status": {
"id": "{status_id}",
"name": "In Progress",
"category": "in_progress",
"color": "#000000"
},
"priority": "high",
"assignee": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"creatorId": "{user_id}",
"cycle": {
"id": "{cycle_id}",
"name": "Cycle 4"
},
"milestoneId": null,
"parentId": null,
"estimate": 3,
"labels": [
{
"id": "{label_id}",
"name": "bug",
"color": "#d14343"
}
],
"startDate": null,
"dueDate": "2026-11-04",
"triage": false,
"source": "api",
"createdAt": "2026-10-25T14:02:11.000Z",
"updatedAt": "2026-10-25T15:10:00.000Z"
}Ver um issue
/api/v1/track/issues/{id}Por id ou identificador (WEB-12).
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou identificador do issue (WEB-12). |
curl -X GET "https://zerosoft.ai/api/v1/track/issues/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"url": "https://zerosoft.ai/app/track/issues/{issue_id}",
"projectId": "{team_id}",
"teamId": "{team_id}",
"planId": null,
"status": {
"id": "{status_id}",
"name": "In Progress",
"category": "in_progress",
"color": "#000000"
},
"priority": "high",
"assignee": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"creatorId": "{user_id}",
"cycle": {
"id": "{cycle_id}",
"name": "Cycle 4"
},
"milestoneId": null,
"parentId": null,
"estimate": 3,
"labels": [
{
"id": "{label_id}",
"name": "bug",
"color": "#d14343"
}
],
"startDate": null,
"dueDate": "2026-11-04",
"triage": false,
"source": "api",
"createdAt": "2026-10-25T14:02:11.000Z",
"updatedAt": "2026-10-25T15:10:00.000Z"
}Editar um issue
/api/v1/track/issues/{id}Envie só o que muda. Mudar status ou responsável aceita um issue que está em triage.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou identificador do issue (WEB-12). |
status | string | Não | Nome do status ("In Progress") ou categoria (in_progress). |
assigneeEmail | string | Não | Email de um membro da equipe. |
priority | urgent | high | medium | low | Não | Prioridade. |
curl -X PATCH "https://zerosoft.ai/api/v1/track/issues/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"status": "Done"
}'Requisição
{
"status": "Done"
}Resposta · 200
{
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"description": "Steps: open /pricing, press Buy.",
"url": "https://zerosoft.ai/app/track/issues/{issue_id}",
"projectId": "{team_id}",
"teamId": "{team_id}",
"planId": null,
"status": {
"id": "{status_id}",
"name": "Done",
"category": "done",
"color": "#000000"
},
"priority": "high",
"assignee": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"creatorId": "{user_id}",
"cycle": {
"id": "{cycle_id}",
"name": "Cycle 4"
},
"milestoneId": null,
"parentId": null,
"estimate": 3,
"labels": [
{
"id": "{label_id}",
"name": "bug",
"color": "#d14343"
}
],
"startDate": null,
"dueDate": "2026-11-04",
"triage": false,
"source": "api",
"createdAt": "2026-10-25T14:02:11.000Z",
"updatedAt": "2026-10-25T15:10:00.000Z"
}Excluir um issue
/api/v1/track/issues/{id}Exclui o issue e os sub-issues.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou identificador do issue (WEB-12). |
curl -X DELETE "https://zerosoft.ai/api/v1/track/issues/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{issue_id}",
"deleted": true
}Listar comentários
/api/v1/track/issues/{id}/commentsComentários de um issue, os mais antigos primeiro.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou identificador do issue (WEB-12). |
curl -X GET "https://zerosoft.ai/api/v1/track/issues/{id}/comments" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{comment_id}",
"issueId": "{issue_id}",
"body": "Reproduced on Safari 18.",
"author": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"createdAt": "2026-10-25T15:00:00.000Z",
"updatedAt": "2026-10-25T15:00:00.000Z"
}
]
}Comentar
/api/v1/track/issues/{id}/commentsComenta como o dono da key em markdown e avisa inscritos e menções.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou identificador do issue (WEB-12). |
body | string | Sim | Comentário em markdown. |
curl -X POST "https://zerosoft.ai/api/v1/track/issues/{id}/comments" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"body": "Deployed the fix to staging."
}'Requisição
{
"body": "Deployed the fix to staging."
}Resposta · 201
{
"id": "{comment_id}",
"issueId": "{issue_id}",
"body": "Deployed the fix to staging.",
"author": {
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com"
},
"createdAt": "2026-10-25T16:00:00.000Z",
"updatedAt": "2026-10-25T16:00:00.000Z"
}Listar equipes
/api/v1/track/teamsEquipes ativas que a key vê. includeArchived=true inclui as arquivadas.
Escopo track:read
curl -X GET "https://zerosoft.ai/api/v1/track/teams" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{team_id}",
"name": "Web",
"key": "WEB",
"description": "",
"icon": null,
"color": "#000000",
"status": "active",
"visibility": "workspace",
"triageEnabled": true,
"url": "https://zerosoft.ai/app/track/team/WEB",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-10-20T10:00:00.000Z"
}
]
}Criar uma equipe
/api/v1/track/teamsSó admins. Cria os status padrão. key é o prefixo dos identificadores.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome |
key | string | Não | Prefixo dos identificadores, letras e números (WEB). |
description | string | Não | Descrição |
curl -X POST "https://zerosoft.ai/api/v1/track/teams" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Web",
"key": "WEB"
}'Requisição
{
"name": "Web",
"key": "WEB"
}Resposta · 201
{
"id": "{team_id}",
"name": "Web",
"key": "WEB",
"description": "",
"icon": null,
"color": "#000000",
"status": "active",
"visibility": "workspace",
"triageEnabled": true,
"url": "https://zerosoft.ai/app/track/team/WEB",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-10-20T10:00:00.000Z"
}Ver uma equipe
/api/v1/track/teams/{id}Por id ou chave, com os status.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou chave da equipe (WEB). projectId também funciona. |
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"id": "{team_id}",
"name": "Web",
"key": "WEB",
"description": "",
"icon": null,
"color": "#000000",
"status": "active",
"visibility": "workspace",
"triageEnabled": true,
"url": "https://zerosoft.ai/app/track/team/WEB",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-10-20T10:00:00.000Z",
"statuses": [
{
"id": "{status_id}",
"projectId": "{project_id}",
"name": "Todo",
"category": "todo",
"color": "#000000",
"position": 1
}
]
}Editar uma equipe
/api/v1/track/teams/{id}Nome, descrição, cor e ícone. Arquivar e triage pedem uma key de admin.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou chave da equipe (WEB). projectId também funciona. |
status | active | archived | Não | active ou archived. |
curl -X PATCH "https://zerosoft.ai/api/v1/track/teams/{id}" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"description": "Marketing site and checkout"
}'Requisição
{
"description": "Marketing site and checkout"
}Resposta · 200
{
"id": "{team_id}",
"name": "Web",
"key": "WEB",
"description": "",
"icon": null,
"color": "#000000",
"status": "active",
"visibility": "workspace",
"triageEnabled": true,
"url": "https://zerosoft.ai/app/track/team/WEB",
"createdAt": "2026-09-01T10:00:00.000Z",
"updatedAt": "2026-10-20T10:00:00.000Z"
}Listar cycles
/api/v1/track/teams/{id}/cyclesCycles de uma equipe.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou chave da equipe (WEB). projectId também funciona. |
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}/cycles" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{cycle_id}",
"projectId": "{project_id}",
"name": "Cycle 4",
"startAt": "2026-10-20",
"endAt": "2026-11-02",
"completedAt": null
}
]
}Criar um cycle
/api/v1/track/teams/{id}/cyclesDatas em YYYY-MM-DD.
Escopo track:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome |
startAt | string | Sim | Data, YYYY-MM-DD. |
endAt | string | Sim | Data, YYYY-MM-DD. |
curl -X POST "https://zerosoft.ai/api/v1/track/teams/{id}/cycles" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Cycle 5",
"startAt": "2026-11-03",
"endAt": "2026-11-16"
}'Requisição
{
"name": "Cycle 5",
"startAt": "2026-11-03",
"endAt": "2026-11-16"
}Resposta · 201
{
"id": "{cycle_id}",
"projectId": "{project_id}",
"name": "Cycle 5",
"startAt": "2026-11-03",
"endAt": "2026-11-16",
"completedAt": null
}Listar status
/api/v1/track/teams/{id}/statusesStatus do workflow de uma equipe em ordem, com a categoria.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id | string | Sim | Id ou chave da equipe (WEB). projectId também funciona. |
curl -X GET "https://zerosoft.ai/api/v1/track/teams/{id}/statuses" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{status_id}",
"projectId": "{project_id}",
"name": "In Progress",
"category": "in_progress",
"color": "#000000",
"position": 2
}
]
}Listar labels
/api/v1/track/labelsLabels do workspace. POST com name e teamId cria um.
Escopo track:read
curl -X GET "https://zerosoft.ai/api/v1/track/labels" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{label_id}",
"name": "bug",
"color": "#d14343",
"workspaceId": "{workspace_id}"
}
]
}Listar pessoas
/api/v1/track/usersPessoas que podem ser atribuídas, de uma equipe ou de todas.
Escopo track:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
teamId | string | Não | Id ou chave da equipe (WEB). projectId também funciona. |
curl -X GET "https://zerosoft.ai/api/v1/track/users" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "{user_id}",
"name": "Ana",
"email": "ana@example.com",
"role": "member"
}
]
}Servidor MCP do Track
Model Context Protocol via Streamable HTTP em /api/mcp/track (só leitura em /api/mcp/track/readonly). Autenticação com uma API key como Bearer. Ferramentas: search_issues, get_issue, create_issue, update_issue, add_comment, list_teams, get_team, list_cycles, list_labels, list_users.
Chamar uma ferramenta
/api/mcp/trackJSON-RPC 2.0: initialize, tools/list e tools/call. As ferramentas que escrevem pedem track:write.
Escopo track:read
curl -X POST "https://zerosoft.ai/api/mcp/track" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_issues",
"arguments": {
"query": "checkout",
"statusCategory": "in_progress"
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_issues",
"arguments": {
"query": "checkout",
"statusCategory": "in_progress"
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{ \"total\": 1, \"issues\": [ … ] }"
}
],
"isError": false
}
}Docs
Leia e escreva páginas, blocos, bancos, linhas e comentários do Docs. O conteúdo entra e sai em Markdown (ou em blocos do Docs). Uma key age como a pessoa que a criou: só vê e edita as páginas que essa pessoa pode abrir. Bancos sincronizados são somente leitura.
Listar páginas
/api/v1/docs/pagesPáginas que a key pode ler, mais novas primeiro. Com q procura em títulos e conteúdo.
Escopo docs:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
parent | string | Não | Só páginas dentro deste id (root para as do topo). |
limit | number | Não | Quantos retornar (1 a 100, padrão 50). |
offset | number | Não | Quantos pular, para paginar. |
curl -X GET "https://zerosoft.ai/api/v1/docs/pages" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "pg_1",
"title": "Launch plan",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false
}
],
"hasMore": false
}Criar uma página
/api/v1/docs/pagesCria uma página a partir de Markdown ou blocos, dentro de outra (parentId) ou de um modelo (id de modelo do workspace ou builtin:<key>). As {{variáveis}} do modelo são preenchidas com vars.
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Não | Título da página. |
markdown | string | Não | Conteúdo em Markdown (títulos, listas, to-dos, citações, código, tabelas). |
parentId | string | Não | Criar como subpágina desta página. |
templateId | string | Não | Id de modelo do workspace ou builtin:<key>. |
curl -X POST "https://zerosoft.ai/api/v1/docs/pages" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Launch plan",
"parentId": "pg_root",
"markdown": "## Goals\n\n- [ ] Ship the beta"
}'Requisição
{
"title": "Launch plan",
"parentId": "pg_root",
"markdown": "## Goals\n\n- [ ] Ship the beta"
}Resposta · 201
{
"data": {
"id": "pg_1",
"title": "Launch plan",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false,
"access": "owner",
"markdown": "## Goals\n\n- [ ] Ship the beta",
"databases": []
}
}Ler uma página
/api/v1/docs/pages/:idA página com o conteúdo em Markdown e seus bancos. Com format=blocks traz também os blocos.
Escopo docs:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
format | string | Não | blocks para trazer também os blocos. |
curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "pg_1",
"title": "Launch plan",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false,
"access": "edit",
"markdown": "## Goals\n\n- [ ] Ship the beta",
"databases": [
{
"blockId": "b_1",
"title": "Tasks",
"rows": 12,
"synced": false
}
]
}
}Atualizar uma página
/api/v1/docs/pages/:idMuda o título ou o ícone, substitui o conteúdo (os bancos da página são mantidos) ou manda para a lixeira e tira de lá (archived).
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Não | Título da página. |
markdown | string | Não | Substitui todo o conteúdo (os bancos são mantidos). |
archived | boolean | Não | true manda para a lixeira, false restaura. |
curl -X PATCH "https://zerosoft.ai/api/v1/docs/pages/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Launch plan (Q4)"
}'Requisição
{
"title": "Launch plan (Q4)"
}Resposta · 200
{
"data": {
"id": "pg_1",
"title": "Launch plan (Q4)",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false,
"access": "owner",
"markdown": "",
"databases": []
}
}Mandar uma página para a lixeira
/api/v1/docs/pages/:idManda a página e suas subpáginas para a lixeira. Restaure com PATCH archived: false.
Escopo docs:write
curl -X DELETE "https://zerosoft.ai/api/v1/docs/pages/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Listar blocos
/api/v1/docs/pages/:id/blocksOs blocos de uma página no formato do Docs (tipo, conteúdo em HTML-lite, aninhamento com indent).
Escopo docs:read
curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id/blocks" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "b_1",
"type": "heading",
"level": 2,
"content": "Goals"
},
{
"id": "b_2",
"type": "todo",
"content": "Ship the beta",
"checked": false
}
]
}Adicionar blocos
/api/v1/docs/pages/:id/blocksAdiciona Markdown ou blocos no fim da página, ou abaixo do bloco em after. Quem está com a página aberta vê mesclado no editor.
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
markdown | string | Não | Conteúdo em Markdown (títulos, listas, to-dos, citações, código, tabelas). |
blocks | object[] | Não | Blocos no formato do Docs (em vez de Markdown). |
after | string | Não | Inserir abaixo deste id de bloco. |
curl -X POST "https://zerosoft.ai/api/v1/docs/pages/:id/blocks" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"markdown": "- [ ] Write the release notes"
}'Requisição
{
"markdown": "- [ ] Write the release notes"
}Resposta · 201
{
"data": {
"id": "pg_1",
"title": "Launch plan",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false,
"access": "owner",
"markdown": "- [ ] Write the release notes",
"databases": []
}
}Listar comentários
/api/v1/docs/pages/:id/commentsComentários e conversas de uma página.
Escopo docs:read
curl -X GET "https://zerosoft.ai/api/v1/docs/pages/:id/comments" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "cm_1",
"pageId": "pg_1",
"blockId": null,
"parentId": null,
"text": "Can we ship this in May?",
"resolved": false,
"author": {
"id": "u_1",
"name": "Ada",
"email": "ada@example.com"
},
"createdAt": "2026-11-02T10:00:00.000Z"
}
]
}Comentar
/api/v1/docs/pages/:id/commentsComenta a página ou um bloco, ou responde uma conversa, como a pessoa que criou a key.
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | string | Sim | Texto do comentário. |
blockId | string | Não | Comentar este bloco. |
parentId | string | Não | Responder na conversa deste comentário. |
curl -X POST "https://zerosoft.ai/api/v1/docs/pages/:id/comments" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"text": "Done, the beta is live."
}'Requisição
{
"text": "Done, the beta is live."
}Resposta · 201
{
"data": {
"id": "cm_2",
"pageId": "pg_1",
"blockId": null,
"parentId": null,
"text": "Done, the beta is live.",
"resolved": false,
"author": {
"id": "u_1",
"name": "Ada",
"email": "ada@example.com"
},
"createdAt": "2026-11-02T11:00:00.000Z"
}
}Listar bancos
/api/v1/docs/databasesBancos das páginas que a key pode ler, com propriedades e opções.
Escopo docs:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
curl -X GET "https://zerosoft.ai/api/v1/docs/databases" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"pageId": "pg_1",
"blockId": "b_1",
"title": "Tasks",
"page": {
"id": "pg_1",
"title": "Launch plan"
},
"synced": null,
"properties": [
{
"id": "title",
"name": "Name",
"type": "title"
},
{
"id": "status",
"name": "Status",
"type": "status",
"options": [
"Not started",
"In progress",
"Done"
]
}
],
"rowCount": 12
}
]
}Ler um banco
/api/v1/docs/databases/:pageId/:blockIdPropriedades de um banco e, se for sincronizado, de onde vem.
Escopo docs:read
curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"pageId": "pg_1",
"blockId": "b_1",
"title": "Issues",
"page": {
"id": "pg_1",
"title": "Engineering"
},
"synced": {
"provider": "github",
"label": "acme/web · Issues",
"syncedAt": "2026-11-02T10:15:00.000Z"
},
"properties": [
{
"id": "title",
"name": "Title",
"type": "title"
}
],
"rowCount": 40
}
}Consultar linhas
/api/v1/docs/databases/:pageId/:blockId/rowsLinhas de um banco com propriedades em texto (properties) e valores brutos (values). filter[Propriedade]=texto mantém as linhas cujo valor contém o texto.
Escopo docs:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
filter[Property] | string | Não | Mantém as linhas cuja Propriedade contém o texto. |
limit | number | Não | Quantos retornar (1 a 100, padrão 50). |
offset | number | Não | Quantos pular, para paginar. |
curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "r_1",
"title": "Website refresh",
"url": "/app/docs/pg_1?row=r_1",
"properties": {
"Status": "In progress",
"Owner": "Ada"
},
"values": {
"Status": "opt_2",
"Owner": [
"u_1"
]
},
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:00:00.000Z"
}
],
"total": 1,
"hasMore": false
}Adicionar uma linha
/api/v1/docs/databases/:pageId/:blockId/rowsAdiciona uma linha. properties vai do nome (ou id) da propriedade ao valor: opções de select são criadas se faltarem, pessoas por email e datas como AAAA-MM-DD. As automações do banco rodam como sempre.
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Não | Título da linha. |
properties | object | Não | Nome ou id da propriedade → valor. |
markdown | string | Não | Conteúdo da linha em Markdown. |
template | string | Não | Modelo de linha do banco (id ou nome). |
curl -X POST "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Website refresh",
"properties": {
"Status": "In progress",
"Owner": "ada@example.com",
"Tags": [
"web",
"q4"
]
}
}'Requisição
{
"title": "Website refresh",
"properties": {
"Status": "In progress",
"Owner": "ada@example.com",
"Tags": [
"web",
"q4"
]
}
}Resposta · 201
{
"data": {
"id": "r_2",
"title": "Website refresh",
"url": "/app/docs/pg_1?row=r_2",
"properties": {
"Status": "In progress",
"Owner": "Ada",
"Tags": "web, q4"
},
"values": {},
"createdAt": "2026-11-02T12:00:00.000Z",
"updatedAt": "2026-11-02T12:00:00.000Z"
}
}Ler uma linha
/api/v1/docs/databases/:pageId/:blockId/rows/:rowIdUma linha com propriedades e conteúdo em Markdown.
Escopo docs:read
curl -X GET "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "r_1",
"title": "Website refresh",
"url": "/app/docs/pg_1?row=r_1",
"properties": {
"Status": "In progress"
},
"values": {},
"markdown": "Brief and links.",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:00:00.000Z"
}
}Atualizar uma linha
/api/v1/docs/databases/:pageId/:blockId/rows/:rowIdMuda propriedades, o título ou o conteúdo de uma linha.
Escopo docs:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
properties | object | Não | Nome ou id da propriedade → valor. |
title | string | Não | Título da linha. |
appendMarkdown | string | Não | Markdown para adicionar no fim do conteúdo da linha. |
curl -X PATCH "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"properties": {
"Status": "Done"
}
}'Requisição
{
"properties": {
"Status": "Done"
}
}Resposta · 200
{
"data": {
"id": "r_1",
"title": "Website refresh",
"url": "/app/docs/pg_1?row=r_1",
"properties": {
"Status": "Done"
},
"values": {},
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T13:00:00.000Z"
}
}Apagar uma linha
/api/v1/docs/databases/:pageId/:blockId/rows/:rowIdApaga a linha. Ela fica no histórico da página.
Escopo docs:write
curl -X DELETE "https://zerosoft.ai/api/v1/docs/databases/:pageId/:blockId/rows/:rowId" \
-H "Authorization: Bearer zs_live_9f3k..."Buscar
/api/v1/docs/searchPáginas e linhas de bancos por título e conteúdo, com um trecho.
Escopo docs:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Sim | Query de busca. |
limit | number | Não | Quantos retornar (1 a 100, padrão 50). |
curl -X GET "https://zerosoft.ai/api/v1/docs/search" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"page": {
"id": "pg_1",
"title": "Launch plan",
"icon": null,
"parentId": null,
"url": "/app/docs/pg_1",
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"archived": false
},
"snippet": "…ship the beta on Friday…"
}
]
}Servidor MCP
/api/v1/docs/mcpModel Context Protocol sobre HTTP (JSON-RPC). Métodos: initialize, tools/list, tools/call. Ferramentas: search, fetch_page, create_page, update_page, list_databases, get_database, query_database, get_row, create_row, update_row, list_comments, add_comment. As que escrevem pedem docs:write.
Escopo docs:read
curl -X POST "https://zerosoft.ai/api/v1/docs/mcp" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "launch plan"
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "launch plan"
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"results\":[...]}"
}
],
"isError": false
}
}Notes
Leia e escreva suas notas. Uma chave age como a pessoa que a criou e só vê as notas dela. Notas bloqueadas não retornam conteúdo.
Listar notas
/api/v1/notesSuas notas, as mais recentes primeiro. q aceita os mesmos operadores do app (tag:, notebook:, intitle:, todo:).
Escopo notes:read
curl -X GET "https://zerosoft.ai/api/v1/notes" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "note_1",
"title": "Weekly review",
"snippet": "Send the report",
"notebookId": null,
"tags": [
"work"
],
"pinned": false,
"trashed": false,
"locked": false,
"sourceUrl": null,
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z"
}
],
"hasMore": false
}Criar uma nota
/api/v1/notesCria uma nota a partir de Markdown ou blocos.
Escopo notes:write
curl -X POST "https://zerosoft.ai/api/v1/notes" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Weekly review",
"markdown": "- [ ] Send the report",
"tags": [
"work"
]
}'Requisição
{
"title": "Weekly review",
"markdown": "- [ ] Send the report",
"tags": [
"work"
]
}Resposta · 201
{
"data": {
"id": "note_1",
"title": "Weekly review",
"snippet": "Send the report",
"notebookId": null,
"tags": [
"work"
],
"pinned": false,
"trashed": false,
"locked": false,
"sourceUrl": null,
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"markdown": "- [ ] Send the report"
}
}Ler uma nota
/api/v1/notes/:idUma nota com o conteúdo em Markdown e blocos.
Escopo notes:read
curl -X GET "https://zerosoft.ai/api/v1/notes/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "note_1",
"title": "Weekly review",
"snippet": "Send the report",
"notebookId": null,
"tags": [
"work"
],
"pinned": false,
"trashed": false,
"locked": false,
"sourceUrl": null,
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z",
"markdown": "- [ ] Send the report"
}
}Editar uma nota
/api/v1/notes/:idMuda título, etiquetas, caderno, fixação ou conteúdo.
Escopo notes:write
curl -X PATCH "https://zerosoft.ai/api/v1/notes/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"title": "Weekly review (done)",
"pinned": true
}'Requisição
{
"title": "Weekly review (done)",
"pinned": true
}Resposta · 200
{
"data": {
"id": "note_1",
"title": "Weekly review",
"snippet": "Send the report",
"notebookId": null,
"tags": [
"work"
],
"pinned": true,
"trashed": false,
"locked": false,
"sourceUrl": null,
"createdAt": "2026-11-01T12:00:00.000Z",
"updatedAt": "2026-11-02T09:30:00.000Z"
}
}Enviar para a lixeira
/api/v1/notes/:idMove a nota para a lixeira.
Escopo notes:write
curl -X DELETE "https://zerosoft.ai/api/v1/notes/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "note_1",
"trashed": true
}
}Listar cadernos
/api/v1/notes/notebooksSeus cadernos com a contagem de notas.
Escopo notes:read
curl -X GET "https://zerosoft.ai/api/v1/notes/notebooks" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "nb_1",
"name": "Work",
"count": 12,
"stack": null
}
]
}Servidor MCP
/api/v1/notes/mcpEndpoint do Model Context Protocol. Ferramentas: search_notes, read_note, list_notebooks, list_tasks, create_note e update_note.
Escopo notes:read
curl -X POST "https://zerosoft.ai/api/v1/notes/mcp" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_notes",
"arguments": {
"query": "tag:work"
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search_notes",
"arguments": {
"query": "tag:work"
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"notes\":[...]}"
}
],
"isError": false
}
}Talk
Mensagens de equipe. A key age como a pessoa que a criou: vê os canais que essa pessoa vê e publica onde ela é membro (em um canal público entra ao publicar). As mensagens diretas não estão na API. Escopos talk:read e talk:write.
Listar canais
/api/v1/talk/channelsOs canais em que a pessoa da key está, ou com scope=all os públicos e os privados em que ela está.
Escopo talk:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
scope | string | Não | member (padrão) ou all |
q | string | Não | Query de busca. |
curl -X GET "https://zerosoft.ai/api/v1/talk/channels" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "tc_1",
"name": "general",
"kind": "public",
"topic": "Company news",
"description": "",
"archived": false,
"member_count": 8,
"is_member": true,
"created_at": "2026-10-25T12:00:00.000Z"
}
]
}Criar um canal
/api/v1/talk/channelsCria um canal público ou privado. O nome é salvo como no Slack: em minúsculas e com hífens no lugar de espaços.
Escopo talk:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome do canal |
kind | string | Não | public (padrão) ou private |
topic | string | Não | Tema do canal |
curl -X POST "https://zerosoft.ai/api/v1/talk/channels" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "launch-q4",
"kind": "public",
"topic": "Q4 launch"
}'Requisição
{
"name": "launch-q4",
"kind": "public",
"topic": "Q4 launch"
}Resposta · 201
{
"data": {
"id": "tc_2",
"name": "launch-q4",
"kind": "public",
"topic": "Q4 launch",
"description": "",
"archived": false,
"member_count": 1,
"is_member": true,
"created_at": "2026-10-25T12:00:00.000Z"
}
}Listar mensagens
/api/v1/talk/messagesAs mensagens do canal, da mais antiga para a mais nova. As menções vêm como tokens com o id da pessoa, mais os de canal e aqui.
Escopo talk:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
channel | string | Sim | Id ou nome do canal (general ou #general) |
before | string | Não | Data ISO: as mensagens anteriores (para paginar) |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/talk/messages" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "tm_1",
"channel_id": "tc_1",
"thread_id": null,
"user_id": "u_1",
"bot_name": null,
"text": "Deploy done <@u_2>",
"files": [],
"reactions": [
{
"emoji": "🎉",
"count": 2,
"users": [
"u_2",
"u_3"
]
}
],
"reply_count": 1,
"edited_at": null,
"pinned": false,
"created_at": "2026-10-25T12:05:00.000Z"
}
],
"has_more": false
}Enviar uma mensagem
/api/v1/talk/messagesPublica em um canal ou responde em um fio. Menções, avisos, prévias de links, Flow e webhooks rodam como se fosse pelo app.
Escopo talk:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
channel | string | Sim | Id ou nome do canal (general ou #general) |
text | string | Sim | Texto da mensagem, com a mesma formatação do app (*negrito*, _itálico_, `código`, links, :emoji:) |
thread_id | string | Não | Id da mensagem raiz para responder no fio |
also_in_channel | boolean | Não | Com thread_id, mostrar a resposta também no canal |
curl -X POST "https://zerosoft.ai/api/v1/talk/messages" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"channel": "general",
"text": "Release *2.4* is live :tada:"
}'Requisição
{
"channel": "general",
"text": "Release *2.4* is live :tada:"
}Resposta · 201
{
"data": {
"id": "tm_2",
"channel_id": "tc_1",
"thread_id": null,
"user_id": "u_1",
"bot_name": null,
"text": "Release *2.4* is live :tada:",
"files": [],
"reactions": [],
"reply_count": 0,
"edited_at": null,
"pinned": false,
"created_at": "2026-10-25T12:06:00.000Z"
}
}Webhook de entrada
/api/talk/hooks/:tokenSem API key: crie a URL em um canal (Detalhes, Integrações) e envie um POST com um JSON com text. Publica como bot com o nome do webhook. 60 pedidos por minuto por webhook.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | string | Sim | Texto da mensagem, com a mesma formatação do app (*negrito*, _itálico_, `código`, links, :emoji:) |
username | string | Não | Nome do bot na mensagem (por padrão, o do webhook) |
thread_id | string | Não | Id da mensagem raiz para responder no fio |
curl -X POST "https://zerosoft.ai/api/talk/hooks/:token" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"text": "Build *green* on main",
"username": "CI"
}'Requisição
{
"text": "Build *green* on main",
"username": "CI"
}Resposta · 200
{
"ok": true,
"id": "tm_3"
}Board
Quadros: listar e buscar (também pelo texto de dentro), ler um resumo, criar a partir de um modelo, adicionar post-its, formas e setas, renomear, mover para uma pasta ou mandar para a lixeira. A key age como a pessoa que a criou: vê e edita os quadros que essa pessoa pode abrir. Quem está com o quadro aberto vê as mudanças ao vivo. Scopes boards:read e boards:write.
Listar quadros
/api/v1/boardsQuadros que a pessoa da key pode abrir, o editado mais recente primeiro. Com q busca também em post-its, rótulos e nomes de frames, e devolve a linha que coincidiu em match.
Escopo boards:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Busca no nome e no texto de dentro. |
folder | string | Não | Id da pasta. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/boards" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "b_1",
"name": "Q4 retro",
"folderId": null,
"access": "workspace",
"version": 12,
"updatedAt": "2026-10-28T12:00:00.000Z",
"createdAt": "2026-10-20T09:00:00.000Z",
"updatedBy": "Ana"
}
]
}Criar um quadro
/api/v1/boardsVazio ou a partir de um modelo: retro, brainstorm, userFlow, kanban, roadmap, swot, mindMap, priorityMatrix, journey ou leanCanvas.
Escopo boards:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Não | Nome do quadro. |
template | string | Não | Chave do modelo. |
folderId | string | Não | Id da pasta. |
curl -X POST "https://zerosoft.ai/api/v1/boards" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Q4 retro",
"template": "retro",
"locale": "en"
}'Requisição
{
"name": "Q4 retro",
"template": "retro",
"locale": "en"
}Resposta · 201
{
"data": {
"id": "b_1",
"name": "Q4 retro",
"folderId": null,
"access": "workspace",
"version": 12,
"updatedAt": "2026-10-28T12:00:00.000Z",
"createdAt": "2026-10-20T09:00:00.000Z",
"updatedBy": "Ana"
}
}Ler um quadro
/api/v1/boards/:idO quadro com um resumo: frames em ordem de leitura, post-its com texto e etiquetas, textos soltos. Com scene=1, também a cena do Excalidraw.
Escopo boards:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
scene | string | Não | 1 para incluir a cena do Excalidraw. |
curl -X GET "https://zerosoft.ai/api/v1/boards/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": {
"id": "b_1",
"name": "Q4 retro",
"folderId": null,
"access": "workspace",
"version": 12,
"updatedAt": "2026-10-28T12:00:00.000Z",
"createdAt": "2026-10-20T09:00:00.000Z",
"updatedBy": "Ana",
"myAccess": "edit",
"outline": {
"frames": [
{
"id": "f_1",
"name": "Agenda"
}
],
"stickies": [
{
"id": "s_1",
"text": "Ship the beta",
"tags": [
"launch"
],
"frameId": null
}
],
"texts": [],
"elementCount": 14
}
}
}Alterar um quadro
/api/v1/boards/:idRenomeia ou move para uma pasta (folderId null tira da pasta).
Escopo boards:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Não | Nome do quadro. |
folderId | string | Não | Id da pasta. |
curl -X PATCH "https://zerosoft.ai/api/v1/boards/:id" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"name": "Q4 retro (final)"
}'Requisição
{
"name": "Q4 retro (final)"
}Resposta · 200
{
"data": {
"id": "b_1",
"name": "Q4 retro (final)",
"folderId": null,
"access": "workspace",
"version": 12,
"updatedAt": "2026-10-28T12:00:00.000Z",
"createdAt": "2026-10-20T09:00:00.000Z",
"updatedBy": "Ana"
}
}Apagar um quadro
/api/v1/boards/:idManda para a lixeira. Pode ser restaurado pelo app por 30 dias.
Escopo boards:write
curl -X DELETE "https://zerosoft.ai/api/v1/boards/:id" \
-H "Authorization: Bearer zs_live_9f3k..."Adicionar post-its e formas
/api/v1/boards/:id/elementsAdiciona post-its, textos e formas, e setas entre eles por índice. Sem x e y ficam ao lado do conteúdo. Não muda nada do que já existe.
Escopo boards:write
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
stickies | array | Não | Post-its: { text, color?, tags? }. Cores: yellow, green, blue, pink, violet, orange. |
elements | array | Não | Formas e textos: { kind, text?, x?, y?, width?, height?, fill? } com kind sticky, text, rectangle, ellipse ou diamond. |
connect | array | Não | Setas entre elementos por índice: { from, to }. |
curl -X POST "https://zerosoft.ai/api/v1/boards/:id/elements" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"elements": [
{
"kind": "ellipse",
"text": "Start"
},
{
"kind": "rectangle",
"text": "Sign up"
}
],
"connect": [
{
"from": 0,
"to": 1
}
]
}'Requisição
{
"elements": [
{
"kind": "ellipse",
"text": "Start"
},
{
"kind": "rectangle",
"text": "Sign up"
}
],
"connect": [
{
"from": 0,
"to": 1
}
]
}Resposta · 201
{
"data": {
"version": 13,
"added": [
{
"id": "e_1",
"type": "ellipse"
},
{
"id": "e_2",
"type": "rectangle"
},
{
"id": "e_3",
"type": "arrow"
}
]
}
}Servidor MCP
/api/v1/boards/mcpModel Context Protocol (streamable HTTP, respostas JSON) para agentes de IA. Ferramentas: list_boards, get_board, create_board, add_stickies, add_diagram, update_board e trash_board.
Escopo boards:read
curl -X POST "https://zerosoft.ai/api/v1/boards/mcp" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "add_stickies",
"arguments": {
"board_id": "b_1",
"stickies": [
{
"text": "Ship the beta",
"color": "green"
}
]
}
}
}'Requisição
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "add_stickies",
"arguments": {
"board_id": "b_1",
"stickies": [
{
"text": "Ship the beta",
"color": "green"
}
]
}
}
}Resposta · 200
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"version\":13,\"added\":[...]}"
}
],
"isError": false
}
}Design
Leia os designs que a pessoa da chave vê: nomes, tamanhos, páginas e, com id, o JSON completo das páginas.
Listar ou ler designs
/api/v1/designSem id, os designs que a pessoa vê (os mais recentes primeiro). Com id, esse design com suas páginas em JSON.
Escopo design:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
view | string | Não | recent (padrão), mine, shared, starred ou templates |
id | string | Não | Id de um design: devolve esse design com suas páginas |
curl -X GET "https://zerosoft.ai/api/v1/design" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "d_1",
"name": "Summer sale",
"width": 1080,
"height": 1080,
"pages": 1,
"owner": "Ana",
"access": "owner",
"starred": false,
"template": false,
"updated_at": "2026-10-29T12:00:00.000Z",
"url": "https://zerosoft.ai/en/app/design/d_1"
}
]
}Shop
O catálogo e os pedidos da sua loja. Scopes shop:read e shop:write. Os dados de clientes só ficam disponíveis para keys de pessoas com o app Shop.
Listar produtos
/api/v1/shop/productsProdutos com status, faixa de preço, número de variantes e estoque. Um POST no mesmo path cria um produto com o mesmo corpo que o app usa.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/shop/products" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "prod_1",
"handle": "blue-mug",
"title": "Blue mug",
"status": "active",
"variants": 2,
"stock": 14,
"tracked": true,
"minPriceCents": 1900,
"maxPriceCents": 2100
}
],
"total": 1
}Listar pedidos
/api/v1/shop/ordersPedidos do mais novo ao mais antigo, com status (pending, paid, fulfilled, cancelled, refunded) e total em centavos.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/shop/orders" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "ord_1",
"number": 1001,
"status": "paid",
"email": "ana@example.com",
"name": "Ana Pérez",
"totalCents": 4100,
"currency": "USD",
"paymentMethod": "stripe",
"items": 2,
"createdAt": "2026-10-29 15:00:00"
}
],
"total": 1
}Pulse
Analytics de produto. Os endpoints de ingestão (/api/ingest/*) usam a key do projeto, não uma API key: a pública (zsp_…) no corpo vinda do navegador, ou a key secreta do projeto como Bearer zss_… vinda de um servidor. As consultas aceitam uma sessão iniciada ou uma API key com analytics:read.
Capturar eventos
/api/ingest/eUm evento ou um lote de até 200, 512 KB por pedido. Com a key secreta como Bearer não há checagem de origem. Eventos com uuid repetido são ignorados. Tem limite por projeto.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
api_key | string | Não | Key pública do projeto (zsp_…). Também aceita como token. |
batch | array | Sim | Eventos: event, distinct_id, properties, timestamp e um uuid opcional. Um evento só pode ir no primeiro nível. |
sent_at | string | Não | Quando o cliente enviou o lote; serve para corrigir o relógio dele. |
curl -X POST "https://zerosoft.ai/api/ingest/e" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"api_key": "zsp_…",
"batch": [
{
"event": "signed_up",
"distinct_id": "user_42",
"properties": {
"plan": "team"
},
"timestamp": "2026-10-29T12:00:00.000Z"
}
]
}'Requisição
{
"api_key": "zsp_…",
"batch": [
{
"event": "signed_up",
"distinct_id": "user_42",
"properties": {
"plan": "team"
},
"timestamp": "2026-10-29T12:00:00.000Z"
}
]
}Resposta · 200
{
"status": 1,
"stored": 1,
"dropped": 0
}Feature flags de uma pessoa
/api/ingest/decideValores das flags ativas para um distinct_id (true, false ou a chave da variante) e os ajustes do snippet. person_properties se soma ao que a pessoa já tem.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
api_key | string | Sim | Key pública do projeto (zsp_…). Também aceita como token. |
distinct_id | string | Sim | O id da pessoa no seu produto. |
person_properties | object | Não | Propriedades extras da pessoa para esta avaliação. |
curl -X POST "https://zerosoft.ai/api/ingest/decide" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"api_key": "zsp_…",
"distinct_id": "user_42"
}'Requisição
{
"api_key": "zsp_…",
"distinct_id": "user_42"
}Resposta · 200
{
"featureFlags": {
"new-checkout": true,
"pricing-test": "variant-b"
},
"config": {
"autocapture": true,
"respectDnt": true
}
}Apagar uma pessoa
/api/ingest/deleteApaga a pessoa de um distinct_id com todos os seus eventos e sessões. Pede a key secreta do projeto como Bearer zss_….
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
distinct_id | string | Sim | O id da pessoa no seu produto. |
curl -X POST "https://zerosoft.ai/api/ingest/delete" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"distinct_id": "user_42"
}'Requisição
{
"distinct_id": "user_42"
}Resposta · 200
{
"deleted": true,
"events": 128
}Rodar uma consulta
/api/analytics/querykind é trends, funnel, retention, paths, sql ou web. O SQL é somente leitura sobre as tabelas do projeto events, persons, person_distinct_ids e sessions, até 1.000 linhas.
Escopo analytics:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
projectId | string | Sim | Id do projeto (ap_…). |
query | object | Sim | A definição da consulta, a mesma que o app salva num insight. |
curl -X POST "https://zerosoft.ai/api/analytics/query" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"projectId": "ap_…",
"query": {
"kind": "trends",
"series": [
{
"event": "$pageview",
"math": "unique"
}
],
"interval": "day",
"dateRange": {
"from": "-7d"
}
}
}'Requisição
{
"projectId": "ap_…",
"query": {
"kind": "trends",
"series": [
{
"event": "$pageview",
"math": "unique"
}
],
"interval": "day",
"dateRange": {
"from": "-7d"
}
}
}Resposta · 200
{
"result": {
"kind": "trends",
"buckets": [
"2026-10-23",
"2026-10-24"
],
"series": [
{
"label": "$pageview (unique users)",
"breakdownValue": null,
"data": [
120,
134
],
"total": 231
}
],
"usedRollup": true
}
}Listar eventos
/api/analytics/eventsÚltimos eventos de um projeto, os mais novos primeiro. Passe after com o último id que você viu para trazer só os novos.
Escopo analytics:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
project | string | Sim | Id do projeto (ap_…). |
event | string | Não | Só este nome de evento. |
after | number | Não | Só eventos com id maior. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/analytics/events" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"events": [
{
"id": 981,
"event": "$pageview",
"distinctId": "user_42",
"ts": 1761739200000,
"url": "https://example.com/pricing",
"pathname": "/pricing",
"browser": "Chrome",
"os": "macOS",
"device": "desktop",
"country": "AR",
"properties": {}
}
]
}Listar pessoas
/api/analytics/personsPessoas de um projeto com suas propriedades e distinct ids, as vistas mais recentemente primeiro.
Escopo analytics:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
project | string | Sim | Id do projeto (ap_…). |
q | string | Não | Query de busca. |
cohort | string | Não | Só pessoas deste id de coorte. |
curl -X GET "https://zerosoft.ai/api/analytics/persons" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"persons": [
{
"id": "p_3f…",
"distinctIds": [
"user_42"
],
"properties": {
"email": "ana@example.com"
},
"isIdentified": true,
"createdAt": 1761000000000,
"lastSeen": 1761739200000
}
],
"hasMore": false
}Books
Faturas do Books. A key age como a pessoa que a criou, com o papel dela no Books. Valores são inteiros na unidade mínima da moeda (centavos). Scopes books:read e books:write.
Listar faturas
/api/v1/books/invoicesFaturas, das mais novas para as mais antigas, com status, número, cliente, total e saldo.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
status | string | Não | draft, sent, partial, paid, overdue, void ou open (tudo que tem saldo). |
q | string | Não | Query de busca. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/books/invoices" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "inv_1",
"docType": "invoice",
"status": "sent",
"numberLabel": "B 00001-00000012",
"reference": "PO 778",
"contactId": "con_1",
"contactName": "Acme SA",
"issueDate": "2026-11-01",
"dueDate": "2026-12-01",
"currency": "ARS",
"total": 12100000,
"amountDue": 12100000,
"sentAt": "2026-11-01 12:00:00",
"updatedAt": "2026-11-01 12:00:00"
}
],
"total": 1
}Criar uma fatura em rascunho
/api/v1/books/invoicesSalva um rascunho com o mesmo corpo que o app usa. Alguém aprova no app, que atribui o número e gera o lançamento.
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
contactId | string | Não | Id do contato do Books (o cliente). |
lines | object[] | Sim | Linhas: description, quantity, unitPrice (unidades mínimas inteiras, ou um texto decimal com ponto como separador decimal, por exemplo "1500.50", seja qual for a moeda), discountBps, taxRateId, itemId. |
currency | string | Não | Código de moeda ISO; a moeda base se omitido. |
fxRate | string | Não | Câmbio manual (moeda base por 1 unidade) quando a moeda não é a base. |
reference | string | Não | Sua referência (pedido de compra, projeto). |
curl -X POST "https://zerosoft.ai/api/v1/books/invoices" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"contactId": "con_1",
"reference": "PO 778",
"lines": [
{
"description": "Consulting",
"quantity": 10,
"unitPrice": "1000.00",
"taxRateId": "tax_iva21"
}
]
}'Requisição
{
"contactId": "con_1",
"reference": "PO 778",
"lines": [
{
"description": "Consulting",
"quantity": 10,
"unitPrice": "1000.00",
"taxRateId": "tax_iva21"
}
]
}Resposta · 201
{
"data": {
"id": "inv_2",
"docType": "invoice",
"status": "draft",
"numberLabel": "",
"total": 1210000,
"currency": "ARS",
"lines": [
{
"description": "Consulting",
"quantity": 10,
"unitPrice": 100000,
"taxBps": 2100,
"net": 1000000,
"tax": 210000,
"total": 1210000
}
]
}
}Forms
Formulários e suas respostas. A key age como a pessoa que a criou e só vê os formulários que ela pode abrir. Scope forms:read.
Listar formulários
/api/v1/forms/formsFormulários do mais novo ao mais antigo, com status, quantidade de respostas e parciais, última resposta e quem pode abri-los.
Escopo forms:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
q | string | Não | Query de busca. |
status | string | Não | Filtre os formulários por status, por exemplo published. |
curl -X GET "https://zerosoft.ai/api/v1/forms/forms" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "fm_1",
"name": "NPS survey",
"slug": "nps-survey-a1b2c3",
"status": "published",
"responseCount": 42,
"partialCount": 3,
"lastResponseAt": "2026-11-03T13:00:00.000Z",
"updatedAt": "2026-11-03T13:00:00.000Z",
"sharing": "workspace",
"open": true
}
]
}Listar respostas
/api/v1/forms/responsesRespostas de um formulário, da mais nova à mais antiga. As respostas são indexadas pelo id da pergunta. As de arquivo devolvem uma referência, não o arquivo.
Escopo forms:read
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
form | string | Sim | Id do formulário. |
status | string | Não | completed (padrão) ou partial. |
from | string | Não | Só respostas enviadas a partir desta data (YYYY-MM-DD). |
to | string | Não | Só respostas enviadas até esta data (YYYY-MM-DD). |
page | integer | Não | Número da página. |
limit | number | Não | Quantidade máxima de resultados. |
curl -X GET "https://zerosoft.ai/api/v1/forms/responses" \
-H "Authorization: Bearer zs_live_9f3k..."Resposta · 200
{
"data": [
{
"id": "rs_1",
"status": "completed",
"answers": {
"q_1": 9,
"q_2": "Fast and clear"
},
"hidden": {
"source": "newsletter"
},
"vars": {
"score": 0
},
"endingId": "end_1",
"lang": "en",
"contactId": "con_1",
"consent": true,
"createdAt": "2026-11-03T12:58:00.000Z",
"submittedAt": "2026-11-03T13:00:00.000Z"
}
],
"total": 42
}Webhooks
Adicione endpoints em Dashboard → Configurações → Webhooks. Eventos: booking.created, booking.rescheduled, booking.cancelled, booking.no_show, booking.requested, link.created, link.clicked, link.updated, link.deleted, contact.created, contact.updated, deal.created, deal.updated, deal.stage_changed, deal.won, deal.lost, robot.run.finished, robot.run.failed, robot.output.changed, chat.message.created, chat.conversation.created, chat.conversation.assigned, chat.conversation.tagged, chat.conversation.resolved, chat.csat.submitted. Os eventos de links podem ser limitados a alguns links, tags ou domínios. link.updated traz o link e a lista de campos alterados; link.deleted, o link como estava. Cada request traz Zerosoft-Signature: t=TIMESTAMP,v1=HEX, onde v1 = HMAC-SHA256(secret, "TIMESTAMP.BODY_CRU"). Rejeite timestamps antigos. Entregas com falha são reenviadas com backoff por ~15 horas.
Payload do evento
https://your-app.example/webhooks/zerosoftO que seu endpoint recebe. Responda 2xx em até 8 segundos.
curl -X POST "https://your-app.example/webhooks/zerosoft" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"id": "evt_1",
"type": "booking.created",
"createdAt": "2026-11-01T18:00:00.000Z",
"data": {
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}
}'Requisição
{
"id": "evt_1",
"type": "booking.created",
"createdAt": "2026-11-01T18:00:00.000Z",
"data": {
"id": "8f1c2a8e-5b1e-4a7e-9a0e-2f6a1d0c9b11",
"status": "confirmed",
"startsAt": "2026-11-03T13:00:00.000Z",
"endsAt": "2026-11-03T13:30:00.000Z",
"timezone": "America/Argentina/Buenos_Aires",
"invitee": {
"name": "Ana",
"email": "ana@example.com"
},
"answers": {},
"hostUserId": "u_123",
"meetingUrl": "https://meet.google.com/abc-defg-hij",
"rescheduledFrom": null,
"cancelReason": null,
"eventType": {
"id": "et_42",
"slug": "intro",
"title": "Intro call"
}
}
}Payload dos eventos do Chat
https://your-app.example/webhooks/zerosoftOs eventos do Chat trazem a conversa. chat.message.created soma a mensagem (do visitante, da equipe ou do bot; as notas internas não são enviadas) e chat.conversation.assigned soma previousAssignedTo.
curl -X POST "https://your-app.example/webhooks/zerosoft" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"id": "evt_2",
"type": "chat.message.created",
"createdAt": "2026-11-01T18:02:00.000Z",
"data": {
"conversation": {
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
},
"message": {
"id": "{message_id}",
"conversationId": "{conversation_id}",
"senderType": "user",
"userId": "{user_id}",
"body": "Hi Ana, the order ships tomorrow.",
"isNote": false,
"attachments": [],
"createdAt": "2026-11-01T18:02:00.000Z"
}
}
}'Requisição
{
"id": "evt_2",
"type": "chat.message.created",
"createdAt": "2026-11-01T18:02:00.000Z",
"data": {
"conversation": {
"id": "{conversation_id}",
"widgetId": "{widget_id}",
"status": "open",
"priority": "medium",
"subject": null,
"assignedTo": "{user_id}",
"visitor": {
"id": "{visitor_id}",
"name": "Ana",
"email": "ana@example.com"
},
"firstResponseAt": "2026-11-01T18:02:00.000Z",
"resolvedAt": null,
"createdAt": "2026-11-01T18:00:00.000Z",
"updatedAt": "2026-11-01T18:02:00.000Z"
},
"message": {
"id": "{message_id}",
"conversationId": "{conversation_id}",
"senderType": "user",
"userId": "{user_id}",
"body": "Hi Ana, the order ships tomorrow.",
"isNote": false,
"attachments": [],
"createdAt": "2026-11-01T18:02:00.000Z"
}
}
}Payload de eventos do Track
https://your-app.example/webhooks/zerosoftOs eventos issue.* trazem o issue e a equipe (project no payload); issue.status_changed inclui from e to, comment.created o comentário e project.* a equipe.
curl -X POST "https://your-app.example/webhooks/zerosoft" \
-H "Authorization: Bearer zs_live_9f3k..."
-H "Content-Type: application/json" \
-d '{
"id": "evt_3",
"type": "issue.status_changed",
"createdAt": "2026-10-25T15:10:00.000Z",
"data": {
"issue": {
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"priority": "high",
"status": "Done",
"assigneeId": "{user_id}"
},
"project": {
"id": "{project_id}",
"name": "Web"
},
"changes": [
"statusId"
],
"from": "In Progress",
"to": "Done"
}
}'Requisição
{
"id": "evt_3",
"type": "issue.status_changed",
"createdAt": "2026-10-25T15:10:00.000Z",
"data": {
"issue": {
"id": "{issue_id}",
"identifier": "WEB-12",
"title": "Checkout button does nothing on Safari",
"priority": "high",
"status": "Done",
"assigneeId": "{user_id}"
},
"project": {
"id": "{project_id}",
"name": "Web"
},
"changes": [
"statusId"
],
"from": "In Progress",
"to": "Done"
}
}
Listar publicações
/api/v1/social/postsAs publicações que a chave vê, da mais nova para a mais antiga, com o status de cada conta e o link para o que foi publicado.
statusfromtoResposta · 200