Publicação via API

Publique seu workflow como um endpoint REST que qualquer aplicação pode chamar diretamente. Compatível com modos de execução síncrono, streaming e assíncrono.

Publicando um workflow

Abra o workflow e clique em Deploy. A aba General abre primeiro e mostra o estado atual do deployment:

A aba General contém:

• Live Workflow — um minimapa somente leitura do snapshot do workflow que está publicado no momento
• Versions — uma tabela de todos os deployments que você publicou, com número da versão, quem publicou e quando
• Deploy / Update / Undeploy — botões de ação no canto inferior direito

Clique em Deploy para publicar o workflow pela primeira vez, ou em Update para enviar um novo snapshot depois de fazer alterações. O ponto verde ao lado de uma versão indica que ela é a versão ao vivo no momento.

Depois de publicado, o workflow fica disponível em:

POST https://app.zoen.space/api/workflows/{workflow-id}/execute

Acompanhando as mudanças

Quando você modifica o canvas do workflow depois de publicar, um badge Update deployment aparece na parte inferior da tela como lembrete de que a versão ao vivo está desatualizada:

Você pode clicar no botão Update diretamente na barra de ferramentas do canvas — não precisa abrir o modal Deploy toda vez.

Controle de versão

Cada vez que você publica ou atualiza, uma nova versão é registrada na tabela Versions. Você pode gerenciar versões anteriores pelo menu de contexto (⋮) ao lado de qualquer linha:

Promote to live é útil para rollback — se um deployment novo tiver um problema, promova a versão anterior para restaurar o último estado bom conhecido na hora.

Gerenciando deployments pela API

Tudo acima também pode ser feito de forma programática. A API v1 expõe endpoints de deploy, undeploy e rollback — úteis para pipelines de CI/CD que publicam um workflow depois que os testes passam, ou para reverter à última versão boa conhecida a partir de um script de incidente. Os três exigem uma API key com permissão de admin no workspace do workflow.

# Deploy the current draft as a new version (body is optional)
curl -X POST https://app.zoen.space/api/v1/workflows/{workflow-id}/deploy \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOEN_API_KEY" \
  -d '{ "name": "Release 4", "description": "Fixes the agent prompt" }'

# Undeploy — take the workflow offline
curl -X DELETE https://app.zoen.space/api/v1/workflows/{workflow-id}/deploy \
  -H "x-api-key: $ZOEN_API_KEY"

# Roll back to the previous version (or pass { "version": N } for a specific one)
curl -X POST https://app.zoen.space/api/v1/workflows/{workflow-id}/rollback \
  -H "x-api-key: $ZOEN_API_KEY"

O rollback reativa uma versão de deployment existente — a mesma operação que Promote to live — e deixa o rascunho do canvas intacto. Veja a referência da API para detalhes completos de request e response: Deploy Workflow, Undeploy Workflow e Rollback Workflow.

Fazendo chamadas à API

Mude para a aba API no modal Deploy para ver código pronto para usar nos três modos de execução:

O seletor de linguagem no topo permite alternar entre cURL, Python, JavaScript e TypeScript. Cada modo — síncrono, streaming e async — tem o próprio bloco de código que você pode copiar diretamente. O código já vem preenchido com o ID do workflow e uma versão mascarada da sua API key.

Na parte inferior da aba, dois botões dão acesso rápido a configurações importantes:

• Edit API Info — defina uma descrição e escolha entre autenticação por API key ou acesso público
• Generate API Key — crie uma nova API key com escopo no seu workspace

Autenticação

Por padrão, endpoints de API exigem uma API key passada no header x-api-key. Gere chaves em Settings → Zoen Keys ou pelo botão Generate API Key na aba API.

curl -X POST https://app.zoen.space/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOEN_API_KEY" \
  -d '{ "input": "Hello" }'

API Info e acesso público

Clique em Edit API Info para adicionar uma descrição e alterar o modo de acesso:

O campo Description documenta o que a API do workflow faz. Isso é útil para equipes, ou ao expor o workflow a ferramentas e serviços que exibem metadados da API.

Modos de execução

Síncrono

O modo padrão. Envie uma request e aguarde a response completa:

curl -X POST https://app.zoen.space/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOEN_API_KEY" \
  -d '{ "input": "Summarize this article" }'

import requests, os

response = requests.post(
    "https://app.zoen.space/api/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["ZOEN_API_KEY"]
    },
    json={"input": "Summarize this article"}
)
print(response.json())

const response = await fetch('https://app.zoen.space/api/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ZOEN_API_KEY!
  },
  body: JSON.stringify({ input: 'Summarize this article' })
});
console.log(await response.json());

Streaming

Transmita a response token a token conforme ela é gerada. Adicione "stream": true ao body da request e especifique quais campos de saída do bloco transmitir usando selectedOutputs.

Use o dropdown Select outputs na aba API para escolher quais campos transmitir:

O dropdown agrupa as saídas disponíveis por bloco. A escolha mais comum é content de um bloco Agent, que transmite o texto gerado. Você pode selecionar campos de vários blocos ao mesmo tempo.

Os valores de selectedOutputs no body da request seguem o formato blockName.field (por exemplo, agent_1.content).

curl -X POST https://app.zoen.space/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOEN_API_KEY" \
  -d '{
    "input": "Write a long essay",
    "stream": true,
    "selectedOutputs": ["agent_1.content"]
  }'

import requests, os

response = requests.post(
    "https://app.zoen.space/api/workflows/{workflow-id}/execute",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["ZOEN_API_KEY"]
    },
    json={
        "input": "Write a long essay",
        "stream": True,
        "selectedOutputs": ["agent_1.content"]
    },
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

const response = await fetch('https://app.zoen.space/api/workflows/{workflow-id}/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ZOEN_API_KEY!
  },
  body: JSON.stringify({
    input: 'Write a long essay',
    stream: true,
    selectedOutputs: ['agent_1.content']
  })
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Saídas grandes demais

As responses de execução de workflow são limitadas pelos limites de request e response da plataforma. Quando uma saída interna, campo de log, campo em streaming ou payload de status async contém um valor grande demais para embutir, o Zoen pode substituir esse valor aninhado por uma referência versionada:

{
  "__simLargeValueRef": true,
  "version": 1,
  "id": "lv_abc123DEF456",
  "kind": "array",
  "size": 12582912,
  "key": "execution/workspace-id/workflow-id/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74/large-value-lv_abc123DEF456.json",
  "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
  "preview": { "length": 25000 }
}

O campo version faz parte do contrato externo da API. Trate a referência como um placeholder opaco para um valor que não pôde ser embutido com segurança na response. id, key e executionId não são URLs de fetch; key aponta para armazenamento no servidor com escopo de execução. Use selectedOutputs para solicitar um campo aninhado menor, reduza os dados passados entre blocos, ou retorne os dados de um bloco Response quando o workflow for dono intencional do body HTTP da response. Saídas de arquivo são metadata-first; peça .base64 só quando precisar do conteúdo do arquivo inline. Blocos JavaScript Function podem ler explicitamente arquivos grandes, value refs e arrays respaldados por manifesto com os helpers sim.files e sim.values, dentro de limites de memória.

Assíncrono

Para workflows de longa duração, o modo async retorna um job ID imediatamente para que você não precise manter a conexão aberta. Adicione o header X-Execution-Mode: async à request. A API retorna HTTP 202 com um job ID e uma URL de status. Faça poll na URL de status até o job concluir.

curl -X POST https://app.zoen.space/api/workflows/{workflow-id}/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: $ZOEN_API_KEY" \
  -H "X-Execution-Mode: async" \
  -d '{ "input": "Process this large dataset" }'

{
  "success": true,
  "async": true,
  "jobId": "run_abc123",
  "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
  "message": "Workflow execution queued",
  "statusUrl": "https://app.zoen.space/api/jobs/run_abc123"
}

curl https://app.zoen.space/api/jobs/{jobId} \
  -H "x-api-key: $ZOEN_API_KEY"

{
  "success": true,
  "taskId": "run_abc123",
  "status": "processing",
  "metadata": {
    "createdAt": "2025-09-10T12:00:00.000Z",
    "startedAt": "2025-09-10T12:00:01.000Z"
  },
  "estimatedDuration": 300000
}

{
  "success": true,
  "taskId": "run_abc123",
  "status": "completed",
  "metadata": {
    "createdAt": "2025-09-10T12:00:00.000Z",
    "startedAt": "2025-09-10T12:00:01.000Z",
    "completedAt": "2025-09-10T12:00:05.000Z",
    "duration": 4000
  },
  "output": { "result": "..." }
}

Valores de status do job

Faça poll no statusUrl da response inicial até o status ser completed ou failed.

Limites de tempo de execução

Se um job ultrapassar o limite de tempo, ele é marcado automaticamente como failed.

Retenção de jobs

Resultados de jobs concluídos e com falha são retidos por 24 horas. Depois disso, o endpoint de status retorna 404. Recupere e armazene os resultados do seu lado se precisar deles por mais tempo.

Limites de capacidade

Se a fila de execução estiver cheia, a API retorna 503:

{
  "error": "Service temporarily at capacity",
  "retryAfterSeconds": 10
}

Gerenciamento de API keys

Gere e gerencie API keys em Settings → Zoen Keys:

• Create novas chaves para aplicações ou ambientes diferentes
• Revoke chaves que não forem mais necessárias
• As chaves têm escopo no seu workspace

Rate limits

As chamadas à API estão sujeitas a rate limits conforme o seu plano. Os detalhes do rate limit são retornados nos headers da response (X-RateLimit-*) e no body da response. Use o modo async para cargas de alto volume ou de longa duração.

Para informações detalhadas de rate limit e a API de logs/webhooks, veja External API.