Installing a team

How to find, install, run, and manage an Envelope team entirely via the API — no workspace required.

Authenticate every request with your API key:

Authorization: Bearer <your-api-key>

All endpoints are prefixed with /api. The base URL is your Envelope instance origin (e.g. https://openenvelope.org/api).

1. Find a team

List all published teams:

GET /templates

{
  "templates": [
    {
      "id": "{your-template-id}",
      "slug": "support-triage",
      "name": "Support Triage",
      "description": "Routes inbound tickets to the right queue.",
      "version": 3,
      "requiredSecrets": ["ZENDESK_API_KEY"],
      "requiredVariables": ["QUEUE_EMAIL"]
    }
  ]
}

Fetch a specific team by ID or slug:

GET /templates/:id

Check requiredSecrets and requiredVariables — you'll need to supply these at install time or immediately after.

2. Install the team

POST /installs

Envelope Managed

Envelope provisions and runs the agents. Secrets can be added immediately after install via PATCH /installs/:id/secrets.

{
  "templateId": "{your-template-id}",
  "platform": "envelope",
  "secrets": {
    "ZENDESK_API_KEY": "zdkey_..."
  },
  "variables": {
    "QUEUE_EMAIL": "[email protected]"
  }
}

Paperclip

Agents are provisioned on your Paperclip instance. Supply your Paperclip base URL, API key, and either an existing companyId or a companyName to create a new company.

{
  "templateId": "{your-template-id}",
  "platform": "paperclip",
  "credentials": {
    "paperclipBaseUrl": "https://paperclip.acme.com",
    "paperclipApiKey": "pk_..."
  },
  "companyId": "cmp_xyz",
  "secrets": {
    "ZENDESK_API_KEY": "zdkey_..."
  },
  "variables": {
    "QUEUE_EMAIL": "[email protected]"
  }
}

Supply companyName instead of companyId to have Envelope create the Paperclip company for you. The created company ID is returned in the response.

Response

{
  "installId": "{your-install-id}",
  "platform": "envelope",
  "status": "completed",
  "deployedAgents": [
    { "key": "coordinator", "externalId": "agent_...", "name": "Coordinator" }
  ]
}

Note the installId — every subsequent API call for this deployment uses it.

Optional install fields

3. Add or update secrets and variables

Supply secrets and variables at install time or add them afterward. Both endpoints accept flat key/value JSON.

Secrets (encrypted at rest, never returned by any API):

PATCH /installs/:installId/secrets

{
  "ZENDESK_API_KEY": "zdkey_new..."
}

Variables (non-sensitive config values):

PATCH /installs/:installId/variables

{
  "QUEUE_EMAIL": "[email protected]"
}

Both endpoints also accept a wrapped format: { "secrets": { ... } } or { "variables": { ... } }.

For Envelope Managed installs, adding the last required secret or variable triggers a run automatically (unless a schedule is configured).

4. Trigger a run

POST /installs/:installId/run

{
  "inputText": "Ticket #8821 — Customer reports login failure after MFA change."
}

Response — run completed:

{
  "runId": "{your-run-id}",
  "status": "completed",
  "response": "Ticket routed to Tier 2 queue. Escalation email sent.",
  "inputTokens": 412,
  "outputTokens": 98
}

Response — run paused at a human gate:

{
  "runId": "{your-run-id}",
  "status": "paused",
  "pausedAtGate": "manager-review"
}

The install must have status: "completed" before runs can be triggered. A 409 is returned if the install is still provisioning.

5. Receive run completions via webhook

If you passed a webhookUrl at install time, Envelope POSTs to that URL when each run finishes:

{
  "installId": "{your-install-id}",
  "runId": "{your-run-id}",
  "status": "completed",
  "response": "Ticket routed to Tier 2 queue.",
  "inputTokens": 412,
  "outputTokens": 98
}

When a run pauses at a gate, the payload has "status": "paused" and a "pausedAtGate" field identifying which gate triggered.

6. Fetch run history

Individual agent runs, newest first:

GET /installs/:installId/agent-runs?limit=50

{
  "runs": [
    {
      "id": "ar_...",
      "agentKey": "coordinator",
      "runId": "{your-run-id}",
      "status": "completed",
      "inputTokens": 412,
      "outputTokens": 98,
      "errorMessage": null,
      "createdAt": "2026-05-12T09:41:00.000Z"
    }
  ]
}

limit accepts 1–200. Defaults to 50.

Aggregated daily pass/fail counts:

GET /installs/:installId/run-log?days=7

{
  "days": [
    { "date": "2026-05-06", "ok": 14, "error": 1 },
    { "date": "2026-05-07", "ok": 18, "error": 0 }
  ]
}

days accepts 1–30. Defaults to 7.

7. List your installs

GET /installs

Returns all installs created with your API key, ordered newest first. Includes id, templateId, templateName, templateSlug, templateVersion, platform, status, and createdAt.

8. Override agent models

By default Envelope assigns a model to each agent automatically based on its role. You can inspect and override these per-agent without re-installing or touching the team definition.

List all agents with their current models:

GET /installs/:installId/agents

{
  "installId": "{your-install-id}",
  "agents": [
    {
      "agentKey": "triage",
      "name": "Triage Agent",
      "role": "classify incoming support tickets",
      "definitionModel": null,
      "overrideModel": null,
      "effectiveModel": "auto"
    },
    {
      "agentKey": "responder",
      "name": "Response Drafter",
      "role": "draft replies to customer messages",
      "definitionModel": "anthropic:claude-sonnet-4-5",
      "overrideModel": "openai:gpt-5-mini",
      "effectiveModel": "openai:gpt-5-mini"
    }
  ]
}

effectiveModel is what will actually run — it reflects the full resolution order: deployer override → definition model → auto-routing.

Pin a model to an agent:

PATCH /installs/:installId/agents/:agentKey/model

{ "model": "openai:gpt-5-mini" }

Pass "auto" as the model to reset back to automatic routing.

Valid models: openai:gpt-5.4, openai:gpt-5-mini, openai:gpt-5-nano, openai:o4-mini, openai:o3, anthropic:claude-opus-4-5, anthropic:claude-sonnet-4-5, anthropic:claude-haiku-4-5.

Reset an agent to automatic routing:

DELETE /installs/:installId/agents/:agentKey/model

{ "ok": true, "installId": "{your-install-id}", "agentKey": "triage", "routing": "auto" }

These same operations are available as MCP tools (get_agent_models, set_agent_model, reset_agent_model) if your workspace is connected to Claude.ai or ChatGPT via the MCP server.

9. Remove an install

DELETE /installs/:installId

Tears down provisioned agents on the platform, deletes all encrypted secrets, and marks the install as cancelled. Returns:

{
  "ok": true,
  "installId": "{your-install-id}",
  "platform": "envelope",
  "deletedAgents": 3
}

Error reference