# Publish from CI or an AI agent

> Source: https://developers.specs.com/docs/publishing/publish-from-ci

Submit a signed Lens from a script, a CI pipeline, or an AI agent with a [Lens Submission API key](#create-a-lens-submission-key). No browser login is needed at runtime.

## What you need

- An existing Lens with a complete store listing. The first release of a brand-new Lens needs its listing created [in the portal](https://developers.specs.com/docs/publishing/store-listing) first.
- A signed `.spk` exported by Lens Studio, signed with the same production key as earlier releases.

## Create a Lens Submission key

1. Open [API Keys](https://developers.specs.com/api-keys) and switch to the organization that owns the Lens.
2. Create a key with the **Lens Submission** purpose.
3. Name it after the pipeline that uses it and pick an expiry. Keys can last from 1 hour to 365 days, or never expire.
4. Copy the key when it is shown — it is shown only once — and store it in your CI secret store as `SPECS_API_KEY`.

Keys look like `sk_specs_v1_appd_...`. A key can only have permissions that its creator already has; creating one normally requires an organization Admin.

> **Note:** Never commit, print, or log the key, and don't pass it as a command-line argument. Give each pipeline or agent its own key so you can revoke it independently.

## API

Base URL:

```text
https://api.specs.com/v1/submission
```

Send `Authorization: Bearer <api-key>` with every request to this base URL.

| Request                           | Purpose                                                               |
| --------------------------------- | --------------------------------------------------------------------- |
| `GET /categories`                 | List category IDs. Needed for a Lens's first release.                 |
| `GET /lenses/availability?pkgId=` | Check whether a package ID is free.                                   |
| `GET /lenses`                     | List the organization's Lenses.                                       |
| `POST /lenses/publish`            | Start a release. Returns an upload URL, its headers, and `submitUrl`. |
| `PUT <upload URL>`                | Upload the SPK. Send every returned header and **no** API key.        |
| `POST <submitUrl>`                | Submit to a channel. Repeat while `status` is `validating`.           |

`POST /lenses/publish` takes:

```json
{
  "spkChecksum": "<base64 SHA-256 of the .spk>",
  "manifestJson": "<contents of manifest.json from the .spk>",
  "categoryId": "<optional>"
}
```

The upload URL expires after one hour.

`POST <submitUrl>` takes `{"targetChannel": "production" | "beta" | "internal"}`:

| `targetChannel` | Portal channel    | Result                                            |
| --------------- | ----------------- | ------------------------------------------------- |
| `production`    | Public            | Enters review; publishes after approval. Default. |
| `beta`          | Beta              | Releases to the Lens's beta testers after review. |
| `internal`      | Organization only | Releases to your organization.                    |

A `submitted` status means the platform accepted the submission. For Public, review still follows.

### Errors

| Code                      | Fix                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `PKG_ID_MISMATCH`         | The SPK's package ID doesn't match the Lens.                                                                                   |
| `PKG_ID_UNAVAILABLE`      | Another organization owns this package ID.                                                                                     |
| `CATEGORY_REQUIRED`       | Pass `categoryId` for the Lens's first release.                                                                                |
| `ORG_AMBIGUOUS`           | Your sign-in can reach several organizations. The response lists them; choose one and retry, or use an organization's API key. |
| `TARGET_CHANNEL_CONFLICT` | The release is already in review for another channel. Withdraw it or submit to that channel.                                   |

## Submission flow

1. Compute the base64 SHA-256 checksum of the `.spk` and read `manifest.json` from inside it (the SPK is a zip archive).
2. Call `POST /lenses/publish` with the checksum and manifest. Save `lensId`, `releaseId`, `uploads.spk.url`, `uploads.spk.headers`, and `submitUrl` from the response.
3. `PUT` the SPK file to `uploads.spk.url` with every header from `uploads.spk.headers`. Don't send the API key to the upload URL.
4. Call `POST <submitUrl>` with the target channel. `submitUrl` is a path; send it to `https://api.specs.com`. While `status` is `validating`, wait `retryAfterSeconds` (5 if absent) and call it again. Stop on `submitted`, and treat any other status as a failure.

Find a category ID once and store it as non-secret configuration:

```bash
curl --fail-with-body --silent --show-error \
  "https://api.specs.com/v1/submission/categories" \
  --header @<(printf 'Authorization: Bearer %s\n' "$SPECS_API_KEY") \
  | jq '.categories[] | {id, displayName}'
```

## Export from Lens Studio in CI

Lens Studio packages and signs the SPK. With the Lens Studio CLI, an export looks like:

```bash
LensStudio export-lens \
  -s project.esproj \
  -o build/lens \
  --pack SPK \
  --sign-key "$LENS_SIGNING_KEY_PATH"
```

Flags can vary by Lens Studio version. Close the project in the Lens Studio app first; an open project can block a headless export.

## Using an AI agent

Give the agent this page's Markdown ([publish-from-ci.md](https://developers.specs.com/docs/publishing/publish-from-ci.md)) and an API key in its environment, not in the prompt. A reliable instruction is:

```text
Publish build/lens/app.spk to the internal channel using the SPECS submission API
described in the linked doc. Read SPECS_API_KEY from the environment and never print it.
Stop and report if the submit status is anything other than validating or submitted.
```
