Swarme

Pesquise. Descreva. Cite. Execute.

GET /api/capabilities pesquisa por consulta em linguagem natural e categoria. Descreva o slug selecionado antes de construir a entrada: seu esquema é a fonte da verdade para campos, preços, requisitos de arquivo e suporte à execução.

1. Pesquise Encontre candidatos com ?q=compress%20pdf.
2. Descreva Leia execution.machine_run_status e o esquema de entrada.
3. Cite Confirme o preço, a liberação da carteira e salve o quote_id retornado.
4. Execute Envie a mesma entrada, o ID da cotação e uma chave de idempotência única.

export SWARME_API_KEY="YOUR_SWARME_API_KEY"
export SWARME_BASE_URL="https://YOUR_SWARME_HOST"

curl "$SWARME_BASE_URL/api/capabilities?q=compress%20pdf&limit=10"
curl "$SWARME_BASE_URL/api/capabilities/compress-pdf"

curl -X POST "$SWARME_BASE_URL/api/capabilities/uuid-generator/quote" \
  -H "Authorization: Bearer $SWARME_API_KEY" -H "Content-Type: application/json" \
  -d '{"input":{},"client_type":"api"}'

curl -X POST "$SWARME_BASE_URL/api/capabilities/uuid-generator/run" \
  -H "Authorization: Bearer $SWARME_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" -H "Content-Type: application/json" \
  -d '{"input":{},"client_type":"api","quote_id":"YOUR_QUOTE_ID"}'

Autentique-se com privilégio mínimo.

Crie uma chave de API com escopo restrito em Dashboard → Developers. Envie Authorization: Bearer YOUR_SWARME_API_KEY. Nunca coloque uma chave em código no lado do cliente, URLs, logs ou repositório.

Escopos

Use apenas os escopos necessários: capabilities:read, capabilities:quote, capabilities:run, uploads:write, artifacts:read e billing:read.

Limites de gastos

Cada cliente pode ter um limite em USD. Verifique GET /api/account/balance antes de trabalho pago; falhas na carteira ou no limite de gastos são interrupções definitivas.

Idempotência

Use uma Idempotency-Key estável por tentativa lógica de cotação/execução. Reexecuções retornam o trabalho original; uma chave não pode representar com segurança entradas diferentes. Execuções de API pagas podem exigir isso.

Cotações

Cite imediatamente antes da execução e passe seu quote_id. Informe o preço ou a falha de política ao usuário.

Use sessões de upload de curta duração.

Crie uma sessão para o slug selecionado, envie os bytes brutos para a URL retornada com o token dedicado e, em seguida, forneça upload_id (ou upload_ids) na entrada de cotação e execução. Valide nome do arquivo, tipo MIME e tamanho conforme a descrição. Nunca reutilize ou registre um token de upload.

curl · sessão de upload Selecionar e copiar

# Create a session. Keep its upload_token private.
curl -X POST "$SWARME_BASE_URL/api/capabilities/compress-pdf/upload-session" \
  -H "Authorization: Bearer $SWARME_API_KEY" -H "Content-Type: application/json" \
  -d '{"input":{"filename":"document.pdf","content_type":"application/pdf","size_bytes":12345},"client_type":"api"}'

# Read upload_url and upload_token from the response, then:
curl -X PUT "YOUR_UPLOAD_URL" -H "Authorization: Bearer YOUR_UPLOAD_TOKEN" \
  -H "Content-Type: application/pdf" --data-binary @document.pdf

# Quote and run with upload_id; then poll /api/capability-runs/YOUR_RUN_ID.

Consulte o status; cancele de forma cooperativa.

GET /api/capability-runs/{run_id} Leia o estado enfileirado, em execução, em nova tentativa, concluído, falho ou cancelado.POST /api/capability-runs/{run_id}/cancel Cancele trabalho enfileirado ou solicite cancelamento cooperativo.GET /api/capability-runs/{run_id}/artifacts Liste artefatos verificados por permissão e siga seus links de download.

machine_run_status é uma barreira de segurança

Os valores canônicos são supported, requires_worker, plan_only e describe_only. supported executa no modo declarado. requires_worker preserva a resposta exigida pelo worker até que o runtime esteja pronto. plan_only retorna um plano do cliente sem processamento no servidor. describe_only bloqueia cotação/execução. O valor legado runnable é aceito como supported para compatibilidade retroativa. Trate valores ausentes ou desconhecidos como describe_only e re-descreva antes da execução.

O mesmo fluxo seguro, como ferramentas.

Conecte um cliente HTTP de streaming a https://swarme.io/mcp. Comece com tools/list; não presuma uma lista em cache.

swarme_capabilities_search swarme_capability_describe swarme_account_balance swarme_tool_quote swarme_tool_run swarme_tool_status swarme_tool_cancel swarme_tool_artifacts swarme_upload_session_create

Inspecione machine_run_status após descrever. Cite/execute apenas supported, requires_worker ou plan_only; recuse describe_only, valores ausentes e desconhecidos. Mantenha limites de aprovação em torno de execuções pagas e acesso a arquivos.

{
  "mcpServers": {
    "swarme": {
      "type": "streamable-http",
      "url": "https://YOUR_SWARME_HOST/mcp",
      "headers": { "Authorization": "Bearer ${SWARME_API_KEY}" }
    }
  }
}

Versione e deprecie contratos explicitamente.

O manifesto de contrato inventaria REST, ferramentas MCP, estados de execução e execução, ciclos de vida de cotação/execução e arquivos, erros e escopos. O changelog legível por máquina classifica alterações como additive, behavioral-risk ou breaking. Elementos desconhecidos do manifesto falham verificações de compatibilidade de forma conservadora.

Execute php bin/check-contract-compatibility.php --baseline=BASELINE.json --candidate=CANDIDATE.json localmente ou em CI. Alterações que quebram compatibilidade falham, a menos que seus IDs de alteração estáveis apareçam em um arquivo local explícito de aprovações.

Convenção de depreciação

Quando a depreciação é ativada para um elemento, publique metadados de manifesto deprecated e use cabeçalhos padrão Deprecation, Sunset e Link: <...>; rel=deprecation além de Swarme-Contract-Version. O alvo configurado é de pelo menos 90 dias de aviso quando prático. É uma meta de governança—não um SLA—e mudanças urgentes de segurança, legais, de prevenção de abuso ou upstream incontroláveis podem exigir menos aviso. Este incremento configura e documenta a convenção apenas; não deprecia nem remove nenhum endpoint.

Use qualquer cliente HTTP.

Estes exemplos usam apenas variáveis de ambiente e espaços reservados. Não contêm credenciais. A distribuição de origem também inclui receitas copiáveis e sem dependências de examples/rest-agent.php e examples/mcp-agent.php cobrindo pesquisa até artefatos ou cancelamento, com um limite explícito de --approve e upload opcional de --file=PATH.

Antes da integração, execute php bin/check-agent-contract.php contra fixtures versionados incluídos. Fornecer --base-url=URL é explícito e realiza apenas verificações públicas de descoberta somente leitura. Estes são clientes iniciais reutilizáveis—não um SDK gerado nem uma API de SDK congelada.

TypeScript · Node 18+ Selecionar e copiar

const baseUrl = process.env.SWARME_BASE_URL ?? "https://YOUR_SWARME_HOST";
const apiKey = process.env.SWARME_API_KEY;
if (!apiKey) throw new Error("Set SWARME_API_KEY");

const request = async (path: string, init: RequestInit = {}) => {
  const response = await fetch(\`${baseUrl}${path}\`, {
    ...init,
    headers: { Authorization: \`Bearer ${apiKey}\`, "Content-Type": "application/json", ...init.headers },
  });
  if (!response.ok) throw new Error(\`${response.status}: ${await response.text()}\`);
  return response.json();
};
const described = await request("/api/capabilities/uuid-generator");
const rawStatus = described.capability?.execution?.machine_run_status;
const machineStatus = rawStatus === "runnable" ? "supported" : rawStatus;
const allowedStatuses = new Set(["supported", "requires_worker", "plan_only"]);
if (!allowedStatuses.has(machineStatus)) throw new Error("Capability is describe-only; describe again before execution");
const quote = await request("/api/capabilities/uuid-generator/quote", {
  method: "POST", body: JSON.stringify({ input: {}, client_type: "api" }),
});
const run = await request("/api/capabilities/uuid-generator/run", {
  method: "POST", headers: { "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ input: {}, client_type: "api", quote_id: quote.quote.quote_id }),
});
const status = await request(\`/api/capability-runs/${run.run_id}\`);

import os, uuid, requests

base_url = os.getenv("SWARME_BASE_URL", "https://YOUR_SWARME_HOST")
api_key = os.environ["SWARME_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
described = requests.get(f"{base_url}/api/capabilities/uuid-generator", headers=headers, timeout=30).json()
raw_status = described.get("capability", {}).get("execution", {}).get("machine_run_status")
machine_status = "supported" if raw_status == "runnable" else raw_status
if machine_status not in {"supported", "requires_worker", "plan_only"}:
    raise RuntimeError("Capability is describe-only; describe again before execution")
quote = requests.post(
    f"{base_url}/api/capabilities/uuid-generator/quote",
    headers=headers, json={"input": {}, "client_type": "api"}, timeout=30,
).json()
run = requests.post(
    f"{base_url}/api/capabilities/uuid-generator/run",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={"input": {}, "client_type": "api", "quote_id": quote["quote"]["quote_id"]}, timeout=30,
).json()
status = requests.get(f"{base_url}/api/capability-runs/{run['run_id']}", headers=headers, timeout=30).json()