Publish from CI or an AI agent

Submit a signed Lens from a script, a CI pipeline, or an AI agent with a Lens Submission API key. No browser login is needed at runtime.

View as Markdown

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 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 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:

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

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

RequestPurpose
GET /categoriesList category IDs. Needed for a Lens's first release.
GET /lenses/availability?pkgId=Check whether a package ID is free.
GET /lensesList the organization's Lenses.
POST /lenses/publishStart 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:

{
  "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"}:

targetChannelPortal channelResult
productionPublicEnters review; publishes after approval. Default.
betaBetaReleases to the Lens's beta testers after review.
internalOrganization onlyReleases to your organization.

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

Errors

CodeFix
PKG_ID_MISMATCHThe SPK's package ID doesn't match the Lens.
PKG_ID_UNAVAILABLEAnother organization owns this package ID.
CATEGORY_REQUIREDPass categoryId for the Lens's first release.
ORG_AMBIGUOUSYour sign-in can reach several organizations. The response lists them; choose one and retry, or use an organization's API key.
TARGET_CHANNEL_CONFLICTThe 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:

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:

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) and an API key in its environment, not in the prompt. A reliable instruction is:

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.