---
title: "Create an installation"
method: POST
path: "/api/v1/agents/{agent}/agent_installations"
---

# Create an installation

`POST /api/v1/agents/{agent}/agent_installations`

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.

## Path parameters

- `agent` string, required

## Request body

- object
  - `config` object — Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration.
  - `integration` object — Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`.
    - `access_token` string — OAuth access token or static API key used by `oauth` providers to authenticate requests on behalf of the user.
    - `installation_id` string — External installation identifier used by `app_installation` providers, e.g. a GitHub App installation ID or a Slack team ID.
    - `metadata` object — Arbitrary provider-specific metadata, e.g. `{"bot_user_id": "U012AB3CD"}` for Slack. Stored alongside the integration and made available to connector logic.
    - `refresh_token` string — OAuth refresh token used to obtain a new `access_token` when the current one expires. Omit for providers that do not issue refresh tokens.
    - `workspace_key` string — Provider-specific workspace or team identifier, e.g. a Slack workspace slug. Used to scope the integration to a particular workspace.
  - `kind` string, 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_key` string — 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_integration` string — ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`.

## Response `200`

Successful response

- Installation — An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration.
  - `agent` string — ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.
  - `config` object — Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.
  - `created_at` string, date-time — When the installation was created (ISO 8601).
  - `id` string, required — Installation ID (`cin_...`).
  - `kind` string — Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set.
  - `lookup_key` string — 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_integration` string — ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound.
  - `state` string — 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_payload` object — Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported.
  - `updated_at` string, date-time — When the installation record was last updated (ISO 8601).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `404` — Agent not found
- `422` — Validation failed

---

[API](https://skmtc.dev/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.dev/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)