API reference

Field names below are taken directly from the backend’s own response models (api/schemas.py) — not reconstructed from the design doc — so they match what actually comes back on the wire. Example values (ids, digests, tenant ids) are from a real local run, not placeholders.

Endpoint index

Method	Path	Purpose
`GET`	`/api/v1/skills`	Search — anonymous-reachable; scoped to public entries for an unauthenticated caller
`GET`	`/api/v1/skills/{id}/versions/{version}`	Full manifest metadata + resolved dependencies; never the executable payload
`POST`	`/api/v1/skills/{id}/versions/{version}/artifact-token`	Validates authorization, issues a short-lived artifact access token
`GET`	`/api/v1/artifacts/{token}`	Redeems a token; reusable until expiry, not single-use
`GET / POST / DELETE`	`/api/v1/skills/{id}/shares[/{grantId}]`	List, create, or revoke a share grant
`POST`	`/api/v1/skills/{id}/versions/{version}/yank · /unyank`	Withdraw or restore a published version
`PUT`	`/api/v1/skills/{id}/governance`	Update ownership/governance metadata
`GET / PUT`	`/api/v1/tenants/{tenantId}/guardrail-policy`	Read or update which configurable guardrail checks a tenant has opted into
`GET / POST / PUT / DELETE`	`/api/v1/tenants/{tenantId}/repo-links[/{skillId}]`	Register, update, or remove a git-native release link
`GET / POST`	`/api/v1/tenants/{tenantId}/members`	List or invite tenant members
`GET`	`/api/v1/tenants/{tenantId}/audit-export`	Export the tenant’s audit log
`POST / GET / PUT / DELETE`	`/api/v1/drafts[/{draftId}]`	Create, read, edit, or discard a draft
`POST`	`/api/v1/drafts/{draftId}/validate`	Structural validation + guardrails scan, no publish
`POST`	`/api/v1/drafts/{draftId}/publish`	Re-validates, then publishes; a BLOCK finding halts before any write
`POST`	`/api/v1/auth/google · /login · /refresh`	Sign-in and session refresh

Search

GET /api/v1/skills Query params: query, runtime, versionConstraint, tags (csv), category, page, pageSize — all optional. No query returns everything the caller can see. Matches on indexed tokens (id segments, name words, tags, category, description words), not arbitrary substrings — see the ranking model below. Searching an id’s own hyphenated suffix (personal-notes) won’t match if that exact string isn’t itself a tag or name token; searching a real tag (notes) will.

curl "https://registry.example.com/api/v1/skills?query=notes" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "items": [
    {
      "id": "jaas.demo.personal-notes",
      "name": "Personal Notes",
      "version": "1.0.1",
      "category": "productivity",
      "tags": ["demo", "personal", "notes"],
      "runtime": ["prompt"],
      "digest": "sha256:51f5b3c8d0168f3ad5cdb1b7e687908bf520c4b472ed50d52028e2aea831a376",
      "score": 1.0,
      "visibility": "private",
      "ownerUser": "usr_7b8f18bf675f11395a442ba2",
      "ownerTenant": "tnt_personal_7b8f18bf675f11395a442ba2",
      "status": "active"
    }
  ],
  "page": { "total": 1, "nextPageToken": null }
}

Every field on items[] and page above is exhaustive — that’s the complete SearchResultItem / PageMeta shape, nothing trimmed.

Ranking model

Match	Weight
Exact id match	1.0
Name token match	0.6
Owner match	0.5
Tag match	0.4
Category match	0.3
Description match	0.2

Skill metadata

GET /api/v1/skills/{id}/versions/{version}

curl "https://registry.example.com/api/v1/skills/jaas.demo.personal-notes/versions/1.0.1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "jaas.demo.personal-notes",
  "name": "Personal Notes",
  "version": "1.0.1",
  "description": "Jots down a quick freeform note under a topic and lists what's already been noted...",
  "owner": { "team": "jaas-registry-examples" },
  "category": "productivity",
  "tags": ["demo", "personal", "notes"],
  "runtime": [{ "family": "prompt", "versionRange": ">=1.0.0,<2.0.0" }],
  "digest": "sha256:51f5b3c8d0168f3ad5cdb1b7e687908bf520c4b472ed50d52028e2aea831a376",
  "dependencies": [],
  "visibility": "private",
  "ownerUser": "usr_7b8f18bf675f11395a442ba2",
  "ownerTenant": "tnt_personal_7b8f18bf675f11395a442ba2",
  "sourceRepo": null,
  "sourceCommit": null,
  "status": "active",
  "guardrailCertifiedLevel": 2,
  "guardrailLevelStatuses": [[1, "certified"], [2, "certified"]],
  "guardrailWarningCheckIds": [],
  "businessPurpose": null,
  "systemsAccessed": [],
  "governanceReviewDate": null
}

{
  "error": "SKILL_NOT_FOUND",
  "message": "No skill jaas.demo.personal-notes at version 1.0.1"
}

The 404 is deliberately identical whether the id doesn’t exist at all, or exists but is private and the caller isn’t its owner or a share grantee — see Corner cases. guardrailCertifiedLevel/guardrailLevelStatuses are a point-in-time attestation computed once at publish — null/[] means “not available for this version” (published before certification existed, or the guardrails service was unreachable at publish time), never “failed,” and it is never recomputed later even if the tenant’s guardrail policy changes afterward.

Create, validate, and publish a draft

POST /api/v1/drafts → DraftResponse

{ "forkFrom": null, "git": null }

{
  "id": "draft_a1b2c3d4e5f64789",
  "ownerUser": "usr_7b8f18bf675f11395a442ba2",
  "ownerTenant": "tnt_personal_7b8f18bf675f11395a442ba2",
  "createdAt": "2026-09-08T06:12:03Z",
  "forkedFromId": null,
  "forkedFromVersion": null,
  "files": ["manifest.yaml"],
  "provider": null,
  "repoUrl": null,
  "gitSyncStatus": null
}

POST /api/v1/drafts/{draftId}/validate → ValidationResultResponse — no body required.

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "certification": {
    "highestCertifiedLevel": 2,
    "levelStatuses": [[1, "certified"], [2, "certified"]]
  }
}

{
  "valid": false,
  "errors": [
    { "code": "MISSING_REQUIRED_FIELD", "message": "manifest.yaml is missing required field 'owner'", "file": "manifest.yaml" }
  ],
  "warnings": [],
  "certification": null
}

certification is a projection — what this draft would be certified as if published right now. It’s null whenever nothing was actually scanned (invalid/blocked) or the guardrails service wasn’t reachable. POST /api/v1/drafts/{draftId}/publish → DraftPublishResponse

{ "visibility": "private" }

{
  "id": "jaas.demo.personal-notes",
  "version": "1.0.1",
  "digest": "sha256:51f5b3c8d0168f3ad5cdb1b7e687908bf520c4b472ed50d52028e2aea831a376",
  "prUrl": null,
  "releaseUrl": null,
  "guardrailCertifiedLevel": 2,
  "guardrailLevelStatuses": [[1, "certified"], [2, "certified"]],
  "guardrailWarningCheckIds": []
}

{
  "error": "DUPLICATE_PUBLISH",
  "message": "'tags/jaas.demo.personal-notes/1.0.0/manifest.json' has already been published"
}

The 409 example above is a real error message, not a paraphrase — captured live in the publishing walkthrough when re-publishing an id+version that already existed. visibility defaults to "private" when omitted — a caller has to opt in to "public" explicitly; nothing is ever published world-visible by accident. POST /api/v1/skills/{id}/shares → ShareGrantResponse. Requires the skills:share scope and being either the skill’s owner or an admin of its owning tenant.

{ "granteeType": "tenant", "granteeId": "tnt_acme_corp", "permission": "read" }

{
  "id": "share_9f8e7d6c5b4a",
  "skillId": "jaas.demo.personal-notes",
  "granteeType": "tenant",
  "granteeId": "tnt_acme_corp",
  "permission": "read",
  "grantedBy": "usr_7b8f18bf675f11395a442ba2",
  "grantedAt": "2026-09-08T06:20:11Z"
}

permission defaults to "read" when omitted. Revoking (DELETE /api/v1/skills/{id}/shares/{grantId}) takes effect on the very next request — grants are checked per-request, never cached.

Artifact download

POST /api/v1/skills/{id}/versions/{version}/artifact-token → ArtifactTokenResponse, then GET /api/v1/artifacts/{token} redeems it.

Response — artifact-token

{
  "token": "atk_3f9a2c8e1d7b4650",
  "expiresAt": "2026-09-08T06:35:00Z",
  "ttlSeconds": 300
}

The token is reusable until expiresAt, not single-use — the same posture as a presigned S3/OCI URL, which is exactly what this stands in for on the local filesystem backend (see Architecture).

Tenant guardrail policy

GET /api/v1/tenants/{tenantId}/guardrail-policy / PUT (same shape) → TenantGuardrailPolicyResponse. Readable by any tenant member, writable only by a tenant admin.

Response

{
  "tenantId": "tnt_personal_7b8f18bf675f11395a442ba2",
  "enabledCheckIds": ["copyleft-license-check", "pii-pattern-scan"]
}

Only lists which configurable (Level 2–4) checks are on — Level 1 mandatory checks are never in this list because they can’t be turned off; see the level model.

Auth

POST /api/v1/auth/login (dev-login path) → AuthResponse

{ "email": "owner@jaas.local", "password": "<JAAS_DEV_LOGIN_PASSWORD>" }

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rtk_8e7f6d5c4b3a2910",
  "user": {
    "id": "usr_7b8f18bf675f11395a442ba2",
    "email": "owner@jaas.local",
    "name": "App Owner",
    "pictureUrl": null,
    "displayName": null
  },
  "tenants": [
    { "id": "tnt_personal_7b8f18bf675f11395a442ba2", "name": "App Owner's Workspace", "role": "owner" }
  ],
  "activeTenantId": "tnt_personal_7b8f18bf675f11395a442ba2"
}

POST /api/v1/auth/google takes { "idToken": "...", "tenantId": null } and returns the same AuthResponse shape. POST /api/v1/auth/refresh takes { "refreshToken": "...", "tenantId": null } and returns an access token + tenant list without a new refresh token.

Guardrails service endpoints

Separate service, separate base URL (:8028 locally) — see Architecture.

Method	Path	Purpose
`GET`	`/catalog`	Every rule’s metadata — no auth, static data
`POST`	`/scan`	Runs the catalog (+ any `customRules`) against a package’s files
`POST`	`/validate-rule`	Schema + config + regex check on one rule — no files, no scan
`GET`	`/healthz`	`{ "status": "ok", "ruleCount": 19 }` — for readiness probes

GET /healthz — real response

{ "status": "ok", "ruleCount": 19 }

Introduction

Getting Started

Skill Packages

Guide

Publishing

Guardrails

Access Model

Reference

Endpoint index

Search

Ranking model

Skill metadata

Create, validate, and publish a draft

Artifact download

Tenant guardrail policy

Auth

Guardrails service endpoints

​Endpoint index

​Search

​Ranking model

​Skill metadata

​Create, validate, and publish a draft

​Share a skill

​Artifact download

​Tenant guardrail policy

​Auth

​Guardrails service endpoints

Endpoint index

Search

Ranking model

Skill metadata

Create, validate, and publish a draft

Share a skill

Artifact download

Tenant guardrail policy

Auth

Guardrails service endpoints