REST API

REST endpoints under /api/skills/ on app.skills.new. These are what sx install, sx update, and CI agents call to resolve and download assets.

The REST API at https://app.skills.new/api/skills/ is the asset-distribution surface. It is what the sx CLI uses to resolve which assets a caller should receive, download their bundles, and report usage. CI agents and review bots use it the same way sx does, just authenticated as a bot instead of a user.

For management actions (creating bots, editing assets, browsing the audit log, etc.) use the GraphQL API instead.

Conventions

  • Base URL: https://app.skills.new

  • Auth: every endpoint requires a credential — see Authentication. Bot API keys are passed with Authorization: Bearer <token>.

  • Org scoping: the credential identifies one organization. There is no orgSlug parameter in the URL.

  • Status codes: 2xx for success, 400 for invalid input, 401 if the credential is missing or invalid, 404 if the asset/version doesn't exist, 405 for the wrong HTTP method.

  • Caching: the lock file uses ETag / If-None-Match; immutable asset bundles set Cache-Control: public, max-age=31536000, immutable. Send the If-None-Match header on your repeat lock-file requests to get a 304 Not Modified.

Endpoint map

Method
Path
Purpose

GET

/api/skills/sx.lock

Resolve the full set of assets for the caller.

GET

/api/skills/sx.profiles

List the org's skill profiles and the caller's active one.

POST

/api/skills/sx.profiles/active

Set the caller's active skill profile.

GET

/api/skills/assets/{name}/list.txt

List published versions of an asset.

GET

/api/skills/assets/{name}/{version}/metadata.toml

Get the metadata for a specific version.

GET

/api/skills/assets/{name}/{version}/{filename}

Download the asset bundle (a .zip).

POST

/api/skills/assets

Upload a new asset version.

POST

/api/skills/usage

Report asset-usage events (JSONL).

POST

/api/skills/ai-query/stream

Stream an AI query against an integration.

The sections below cover each endpoint.


Lock file

Returns a TOML lock file enumerating every asset the caller should have installed, together with the version pinned for them and a download URL for each. This is the single source of truth for what should be on disk after sx install.

The lock content is scoped to the caller automatically:

  • User credential → assets installed to the user, the user's teams, the user's repositories, and the org-wide installs.

  • Bot credential → assets installed to the bot, the bot's teams, and the org-wide installs.

Headers

  • If-None-Match: "<etag>" — recommended. Returns 304 Not Modified if the lock hasn't changed.

  • x-session-id: <opaque> — optional. Tagged onto the audit log entry so you can correlate a sequence of calls.

  • user-agent: <client> — recorded for usage statistics.

Example

Returns 200 OK with Content-Type: application/toml (the lock file) or 304 Not Modified. The ETag response header changes whenever the resolved asset set changes for that caller.

Every successful call is recorded in the audit log as a LOCK_FILE_ACCESSED event with the user agent, client IP, and (for bots) the bot slug and key prefix.


Skill profiles

Skill profiles are named subsets of the available asset set — a user (or bot) picks an active profile and the lock file resolves against that profile.

List profiles

Set active profile

Pass {"slug": null} to clear the active profile. Returns the activated profile, or null if cleared.


Asset bundles

List versions

Returns plain text — one published version number per line, newest last. Use it to find the latest version available for an asset before fetching metadata or the bundle.

Get version metadata

Returns the TOML metadata for the version: name, description, asset type, dependencies, etc. Bundles are immutable per version, so the response is heavily cached (Cache-Control: public, max-age=31536000, immutable).

Download a bundle

Returns the zip file. The {filename} segment is for HTTP semantics (so browsers and tools pick a sensible filename); the server resolves the bundle from {asset_name} and {asset_version} alone. Convention is {name}-{version}.zip.

Each successful download:

  1. Queues an install-tracking event (powers the Adoption dashboard).

  2. Writes a DOWNLOADED event to the audit log with the caller, the user agent, and (for bots) the key prefix.

Upload a new version

Upload a packaged .zip to create a new version of an asset (or the first version of a new asset).

Form fields:

Field
Required
Description

file

yes

The .zip bundle. Must contain a metadata.toml with name and version.

name

no

Asset slug. Falls back to metadata.toml or the filename.

version

no

Version string. Used for validation against metadata.toml.

type

no

Asset type — skill (default), agent, rule, command, hook, mcp_server, plugin.

installations

no

JSON array of {entity_type, entity_id} objects describing where to install (org, team, repository, user, bot).

owned_by

no

Legacy fallback if installations isn't given — organization, user, or repository.

repository_owner / repository_name

conditional

Required if owned_by="repository".

Returns 201 Created with:


Usage reporting

Reports asset-usage events. The body is JSONL — one JSON object per line — with each line describing a single invocation:

Returns 204 No Content once events are queued (processing is async). An empty body is also a valid 204. Invalid JSONL returns 400.

Events feed the Govern / Usage dashboards.


AI query stream

Streams the result of a natural-language query against an integration provider (used by the sx AI-query subcommands).

Request:

  • provider is one of the configured integration providers — GITHUB, CIRCLECI, LINEAR, etc.

  • context.repo_url is required. branch and commit_sha may be empty strings.

Returns Content-Type: text/event-stream. Each event is a serialized tool call, intermediate result, or — as the final frame — {"type": "done", "result": {...}}. Errors arrive as {"type": "error", "error": "..."}.


A complete sx-style flow

The typical machine flow when an agent comes online (and roughly what sx install does):

In practice, prefer running sx itself with a bot's API key — it implements the caching, retry, and on-disk layout correctly.

Last updated

Was this helpful?