# Upseam documentation

Upseam is Dependabot for APIs. It is a GitHub App that knows which API
versions, SDKs and AI models your repositories use. When a provider ships a
change that touches your code, Upseam finds the exact lines. Once you connect a
model, it asks your team in Slack or in a GitHub issue, then writes a fix with
that model and opens a pull request. You review it.

Upseam is in a free beta, installed by link.

## Install

:::tabs Install Upseam

::: tab GitHub App

Install the App, pick repositories, done. No YAML file and no secrets on the
default path. The steps and permissions are in
[Install the GitHub App](install.md).

::: tab GitHub Action

The Action runs the detector in your CI and keeps one issue, **Upseam watches
this repository**, up to date. It is published with the first release of
`upseam/action`.

```yaml title=".github/workflows/upseam.yml"
name: upseam
on:
  schedule:
    - cron: "17 6 * * 1"
  workflow_dispatch:
permissions:
  contents: read
  issues: write
concurrency: upseam
jobs:
  upseam:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          persist-credentials: false
      - uses: upseam/action@v0 # after the first release
```

::: tab CLI

The CLI runs the same detector locally, with no account and no server. It
needs Node.js 22 or later.

```sh title="Run once"
npx @upseam/cli inspect stripe .
```

```sh title="Install globally"
npm i -g @upseam/cli
upseam inspect stripe .
```

:::

## What Upseam watches

- **Shopify**: quarterly versions of the Admin GraphQL API.
- **Stripe**: REST API versions, from your pin or the SDK major version.
- **AI models**: OpenAI, Anthropic and Gemini models your code names, when
  the vendor retires them.

Repositories in TypeScript, JavaScript and Python are supported.

## What Upseam does

- **Install, pick repositories, done.** No YAML and no secrets on the default
  path.
- **Fix pull requests for mechanical changes.** Removed, renamed and retyped
  fields and methods get a pull request. Behavior changes are listed for you
  under "Needs you" instead of being guessed at.
- **Works with Dependabot.** When a Dependabot or Renovate pull request bumps a
  tracked SDK and the bump breaks your code, Upseam asks for approval and then
  opens a pull request with the bump and the code fix.
- **Retired AI models.** When a vendor retires a model your code names and
  names one successor, you can approve a pull request to it, with a note to
  review parameters and behavior.
- **Approve in Slack or the dashboard issue, or open pull requests
  automatically.** New repositories start in the `ask` mode. See
  [Delivery modes](delivery-modes.md).
- **Bring your own model.** Anthropic or OpenAI with your key, or any
  OpenAI-compatible endpoint with the stored-key method.
- **Upseam never stores your code.** See [Security model](security.md).

## What Upseam does not do

- It does not run your tests before the pull request. Your own CI runs on the
  pull request, and Upseam reports the result.
- It does not fix every breaking change. Only mechanical changes are patched;
  everything else is flagged with the file and line.
- It does not bump SDKs. That stays Dependabot's or Renovate's job; Upseam
  fixes the code a bump breaks.

:::cards Related resources

- [How it works](how-it-works.md)
  The path from a vendor change to a pull request and a Slack message.
- [Install the GitHub App](install.md)
  Pick repositories and finish the optional setup steps.
- [Connect a model](models.md)
  Fix pull requests are written by your model with your key.
- [CLI](cli.md)
  Inspect a repository locally or in your CI.

:::