Swarme

Busca. Describe. Cotiza. Ejecuta.

GET /api/capabilities busca mediante consultas en lenguaje natural y categoría. Describe el slug seleccionado antes de construir la entrada: su esquema es la fuente de verdad para campos, precios, requisitos de archivos y soporte de ejecución.

1. Busca Encuentra candidatos con ?q=compress%20pdf.
2. Describe Lee execution.machine_run_status y el esquema de entrada.
3. Cotiza Confirma el precio, la disponibilidad de fondos en la wallet y guarda el quote_id devuelto.
4. Ejecuta Envía la misma entrada, el ID de la cotización y una clave de idempotencia ú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"}'

Autentica con el menor privilegio posible.

Crea una clave API con alcance restringido desde Dashboard → Developers. Envía Authorization: Bearer YOUR_SWARME_API_KEY. Nunca coloques una clave en código del lado del cliente, URLs, registros o un repositorio.

Alcances

Usa solo los alcances necesarios: capabilities:read, capabilities:quote, capabilities:run, uploads:write, artifacts:read y billing:read.

Límites de gasto

Cada cliente puede tener un tope en USD. Verifica GET /api/account/balance antes de trabajo de pago; fallos de wallet o de límite de gasto son detenciones definitivas.

Idempotencia

Usa una Idempotency-Key estable por intento lógico de cotización/ejecución. Las repeticiones devuelven el trabajo original; una clave no puede representar de forma segura entradas diferentes. Las ejecuciones de API de pago pueden requerirla.

Cotizaciones

Cotiza inmediatamente antes de la ejecución y pasa su quote_id. Muestra el precio o el fallo de política al usuario.

Usa sesiones de subida de corta duración.

Crea una sesión para el slug seleccionado, sube los bytes crudos a la URL devuelta con el token dedicado y luego proporciona upload_id (o upload_ids) en la entrada de cotización y ejecución. Valida el nombre de archivo, el tipo MIME y el tamaño contra la descripción. Nunca reutilices ni registres un token de subida.

curl · sesión de subida Seleccionar y 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.

Consulta el estado; cancela de forma cooperativa.

GET /api/capability-runs/{run_id} Lee el estado en cola, en ejecución, reintentando, completado, fallido o cancelado.POST /api/capability-runs/{run_id}/cancel Cancela trabajo en cola o solicita cancelación cooperativa.GET /api/capability-runs/{run_id}/artifacts Lista los artefactos verificados por permisos y luego sigue sus enlaces de descarga.

machine_run_status es una puerta de seguridad

Los valores canónicos son supported, requires_worker, plan_only y describe_only. supported ejecuta en el modo declarado. requires_worker conserva la respuesta requerida por el trabajador hasta que ese runtime esté listo. plan_only devuelve un plan del cliente sin procesamiento del servidor. describe_only bloquea cotización/ejecución. El valor heredado runnable se acepta como supported por compatibilidad hacia atrás. Trata los valores faltantes o desconocidos como describe_only y vuelve a describir antes de ejecutar.

El mismo flujo seguro, como herramientas.

Conecta un cliente HTTP de flujo continuo a https://swarme.io/mcp. Comienza con tools/list; no asumas una lista en caché.

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

Inspecciona machine_run_status después de describir. Cotiza/ejecuta solo supported, requires_worker o plan_only; rechaza describe_only, valores faltantes y desconocidos. Mantén límites de aprobación alrededor de ejecuciones de pago y acceso a archivos.

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

Versiona y depreca contratos de forma explícita.

El manifiesto de contratos inventaría REST, herramientas MCP, estados de ejecución y de run, ciclos de vida de cotización/ejecución y de archivos, errores y alcances. El registro de cambios legible por máquina clasifica los cambios como additive, behavioral-risk o breaking. Los elementos desconocidos del manifiesto fallan las comprobaciones de compatibilidad de forma conservadora.

Ejecuta php bin/check-contract-compatibility.php --baseline=BASELINE.json --candidate=CANDIDATE.json localmente o en CI. Los cambios disruptivos fallan a menos que sus IDs de cambio estables aparezcan en un archivo local de aprobaciones explícito.

Convención de deprecación

Cuando se activa la deprecación de un elemento, publica metadatos de manifiesto deprecated y usa los encabezados estándar Deprecation, Sunset y Link: <...>; rel=deprecation además de Swarme-Contract-Version. El objetivo configurado es de al menos 90 días de aviso cuando sea práctico. Es un objetivo de gobernanza—no un SLA—y cambios urgentes de seguridad, legales, de prevención de abuso o aguas arriba incontrolables pueden requerir menos aviso. Este incremento solo configura y documenta la convención; no depreca ni elimina ningún endpoint.

Usa cualquier cliente HTTP.

Estos ejemplos usan solo variables de entorno y marcadores de posición. No contienen credenciales. La distribución fuente también incluye recetas copiables y sin dependencias de examples/rest-agent.php y examples/mcp-agent.php que cubren desde búsqueda hasta artefactos o cancelación, con un límite explícito de --approve y subida opcional de --file=PATH.

Antes de la integración, ejecuta php bin/check-agent-contract.php contra fixtures versionados incluidos. Proporcionar --base-url=URL es explícito y realiza solo comprobaciones públicas de descubrimiento de solo lectura. Estos son clientes iniciales reutilizables—no un SDK generado ni una API de SDK congelada.

TypeScript · Node 18+ Seleccionar y 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()