v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create an installation

Creates a new installation for an agent, connecting it to an external service or enablement channel via the specified kind. The installation begins in a pending state unless an integration is supplied at creation time, in which case it is activated immediately.

Supply shared_integration to bind an existing org- or app-level integration, or supply integration to create a new integration inline and activate the installation in a single request. Supplying both fields returns 422.

Use lookup_key to assign a stable identifier you can reference later in knowledge search source_refs. The key must be unique within the app, org, and sandbox combination. The caller must have app scope for the app that owns the agent.

post/api/v1/agents/{agent}/agent_installations

Path parameters

agentstring required

Agent ID (agt_...) that will own this installation.

Request body

configobject

Kind-specific configuration object. Shape varies by kind; omit if the kind requires no initial configuration.

kindstring required

Installation kind that determines the external service being connected. Examples: "enablement/github_app", "enablement/slack_bot", "integration/github", "integration/gmail", "web/site". Use the List Kinds endpoint to retrieve all supported values.

lookup_keystring

Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search source_refs. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing.

shared_integrationstring

ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with integration.

Example request

{
  "config": {},
  "integration": {
    "access_token": "string",
    "installation_id": "string",
    "metadata": {
      "key": "value"
    },
    "refresh_token": "string",
    "workspace_key": "example-slug"
  },
  "kind": "string",
  "lookup_key": "string",
  "shared_integration": "string"
}

Response

Successful response

agentstring

ID of the agent that owns this installation (agi_...). null if the installation has no agent owner.

configobject

Kind-specific configuration object for this installation. Shape depends on the kind value. null if the kind requires no configuration.

created_atstring date-time

When the installation was created (ISO 8601).

idstring required

Installation ID (cin_...).

kindstring

Slug identifying the type of external service this installation connects to, e.g. "enablement/github_app" or "integration/gmail". null if not set.

lookup_keystring

Caller-assigned stable identifier for this installation, used to reference it in knowledge search source_refs. null if no lookup key was provided at creation time.

shared_integrationstring

ID of the shared org- or app-level integration bound to this installation (int_...). null if no integration has been bound.

statestring

Current lifecycle state of the installation. One of "pending", "active", "paused", or "error". "error" indicates the installation was suspended due to a policy or compliance issue and requires attention.

status_payloadobject

Provider-supplied status detail for this installation, set during activation or event processing. null if no status has been reported.

updated_atstring date-time

When the installation record was last updated (ISO 8601).

Example response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "config": {},
  "created_at": "2024-01-01T00:00:00Z",
  "id": "cin_0aBcDeFgHiJkLmNoPqRsTu",
  "kind": "enablement/github_app",
  "lookup_key": "string",
  "shared_integration": "int_0aBcDeFgHiJkLmNoPqRsTu",
  "state": "active",
  "status_payload": {},
  "updated_at": "2024-01-01T00:00:00Z"
}