Primeiros passos

URL base

Todas as requisições da API vão para:

https://agent-studio.seeyu.ai

Início rápido

https://agent-studio.seeyu.ai/workspace/{workspaceId}/w/{workflowId}

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {}}'

const response = await fetch(
  `https://agent-studio.seeyu.ai/api/v2/workflows/${workflowId}/execute`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.STUDIO_API_KEY!,
    },
    body: JSON.stringify({ input: {} }),
  }
)

const data = await response.json()
console.log(data.data.output)

import requests
import os

response = requests.post(
    f"https://agent-studio.seeyu.ai/api/v2/workflows/{workflow_id}/execute",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["STUDIO_API_KEY"],
    },
    json={"input": {}},
)

data = response.json()
print(data["data"]["output"])

Execução síncrona vs. assíncrona

Por padrão, as execuções de workflow são síncronas — a API bloqueia até o workflow terminar e devolve o resultado direto.

Para workflows longos, use a execução assíncrona passando async: true:

curl -X POST https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"input": {}, "async": true}'

Quem chama com chave de API pode enviar X-Run-Id: my-run-123 para escolher o ID da execução. IDs de execução não podem ser reutilizados; um ID duplicado retorna 409.

Isso retorna imediatamente com um runId e uma statusUrl:

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "statusUrl": "https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
  }
}

Consulte o endpoint de status da execução até o status ser terminal:

curl "https://agent-studio.seeyu.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true" \
  -H "X-API-Key: YOUR_API_KEY"

Formato das respostas

As respostas de sucesso da v2 envolvem o recurso de execução em data:

{
  "data": {
    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
    "workflowId": "{workflowId}",
    "status": "completed",
    "output": { "result": "Hello, world!" },
    "error": null,
    "durationMs": 842
  }
}

Tratamento de erros

A API usa os códigos de status HTTP padrão. Os erros da v2 incluem um código estável e uma mensagem legível por humanos:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workflow not found"
  }
}

Campos não reconhecidos são rejeitados

Todo endpoint da v2 valida a requisição contra o schema publicado — parâmetros de path, query string e body — e responde 400 para qualquer campo que ele não declare. Um parâmetro escrito errado é um erro, não uma operação silenciosa: ?limt=20 falha em vez de devolver uma lista sem limite sem avisar.

Isso vale também para os endpoints que não declaram nenhum parâmetro de query. Não acrescente tags de rastreamento, cache busters ou outros parâmetros extras a uma URL da v2; envie apenas o que o endpoint documenta.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request",
    "details": [
      { "code": "unrecognized_keys", "keys": ["limt"], "path": [], "message": "Unrecognized key: \"limt\"" }
    ]
  }
}

Limites de requisições

Os limites de requisições dependem do seu plano de assinatura e valem separadamente para execuções síncronas e assíncronas.

Como ler sua cota

Toda resposta traz o estado do bucket em que a requisição foi contabilizada. Leia esses headers em vez de fixar um limite no código — o teto muda junto com o seu plano, e X-RateLimit-Limit é o valor autoritativo para a sua chave naquele momento.

Como os buckets são separados

A v2 mede por operação e por sujeito. Uma chave que esgota o orçamento em POST /api/v2/workflows/{id}/execute continua conseguindo ler logs. Cada requisição é verificada contra todos os sujeitos a que a chave se resolve — a própria chave de API, mais o usuário dono no caso de uma chave pessoal ou o workspace no caso de uma chave de workspace — e o bucket mais restritivo decide.

A v1 é mais grosseira: um único bucket compartilhado por usuário em todos os endpoints v1.

Quando você é limitado

Uma requisição barrada retorna 429 com o código de erro RATE_LIMITED:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": { "retryAfter": "2026-09-08T17:45:00.000Z" }
  }
}

O Retry-After dá a espera em segundos inteiros e details.retryAfter traz o mesmo instante como timestamp. Espere até lá em vez de tentar de novo na hora — uma retentativa antes do reset é contabilizada no bucket e empurra o reset para mais longe.

Restrições por plano

No plano gratuito, executar um workflow de forma programática — API pública, chave de API ou servidor MCP — retorna 402 com USAGE_LIMIT_EXCEEDED e a mensagem Programmatic workflow execution requires a paid plan. Upgrade to Pro or higher to use the API. As leituras não são afetadas.

Paginação

Os endpoints de listagem (workflows, logs, logs de auditoria) usam paginação por cursor:

# First page
curl "https://agent-studio.seeyu.ai/api/v2/logs?workspaceId=WORKSPACE_ID&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

# Next page — use the nextCursor from the previous response
curl "https://agent-studio.seeyu.ai/api/v2/logs?workspaceId=WORKSPACE_ID&limit=20&cursor=abc123" \
  -H "X-API-Key: YOUR_API_KEY"

A resposta inclui o campo nextCursor. Quando nextCursor está ausente ou é null, você chegou à última página.