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.
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
.spkexported by Lens Studio, signed with the same production key as earlier releases.
Create a Lens Submission key
- Open API Keys and switch to the organization that owns the Lens.
- Create a key with the Lens Submission purpose.
- Name it after the pipeline that uses it and pick an expiry. Keys can last from 1 hour to 365 days, or never expire.
- 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.
| 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:
{
"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
- Compute the base64 SHA-256 checksum of the
.spkand readmanifest.jsonfrom inside it (the SPK is a zip archive). - Call
POST /lenses/publishwith the checksum and manifest. SavelensId,releaseId,uploads.spk.url,uploads.spk.headers, andsubmitUrlfrom the response. PUTthe SPK file touploads.spk.urlwith every header fromuploads.spk.headers. Don't send the API key to the upload URL.- Call
POST <submitUrl>with the target channel.submitUrlis a path; send it tohttps://api.specs.com. Whilestatusisvalidating, waitretryAfterSeconds(5 if absent) and call it again. Stop onsubmitted, 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.