The AI•Pkg Registry API provides all endpoints needed to publish, discover, and install packages. All endpoints are under /v3/ and return JSON.
The registry publishes a machine-readable OpenAPI specification at GET /v3/openapi.json. Consuming this endpoint is the recommended way to generate client SDKs or interactive documentation for the registry.
Service Index
Returns the service index listing all available resource endpoints.
{
"@context": { "@vocab": "http://schema.nuget.org/services#" },
"version": "3.0.0",
"resources": [
{
"@id": "https://aipkg.org/v3/registration/",
"@type": "RegistrationsBaseUrl/3.6.0",
"comment": "Base URL for package registration blobs."
},
{
"@id": "https://aipkg.org/v3/flatcontainer/",
"@type": "PackageBaseAddress/3.0.0",
"comment": "Base URL for package downloads."
},
{
"@id": "https://aipkg.org/v3/search",
"@type": "SearchQueryService/3.5.0",
"comment": "Search endpoint with APM and capability filters."
},
{
"@id": "https://aipkg.org/v3/autocomplete",
"@type": "SearchAutocompleteService/3.5.0",
"comment": "Autocomplete for package IDs."
},
{
"@id": "https://aipkg.org/v3/package",
"@type": "PackagePublish/2.0.0",
"comment": "Package push endpoint."
},
{
"@id": "https://aipkg.org/v3/platforms",
"@type": "PlatformList/1.0.0",
"comment": "List of known AI Platform Monikers."
}
]
}
Registration
GET /v3/registration/{id}/index.json
GET /v3/registration/{id}/{lower-version}.json
- Replace
packageTypes → capabilities
- Replace
targetFrameworks → targets (APM monikers)
- Add
permissions, mcpServers, modelCompatibility
- Remove:
requireLicenseAcceptance, developmentDependency, semVerLevel
Flat Container (Downloads)
GET /v3/flatcontainer/{id}/index.json
→ { "versions": ["1.0.0", "1.1.0", "2.0.0"] }
GET /v3/flatcontainer/{id}/{version}/{id}.{version}.aipkg
→ 200 application/x-aipkg (binary stream)
GET /v3/flatcontainer/{id}/{version}/{id}.{version}.aispec
→ 200 application/json (manifest only, unzipped)
The .aispec endpoint lets clients read manifest metadata without downloading the full archive.
Search
Query Parameters:
| Parameter | Type | Description |
|---|
q | string | Full-text search query |
skip | integer | Pagination offset (default: 0) |
take | integer | Page size (default: 20, max: 100) |
prerelease | boolean | Include pre-release versions (default: false) |
apm | string | Filter by AI Platform Moniker (uses fallback graph expansion) |
capability | string | Filter by capability value |
permission | string | Filter by declared permission |
{
"@context": { "@vocab": "http://schema.nuget.org/services#" },
"totalHits": 142,
"data": [
{
"@id": "https://aipkg.org/v3/registration/git-helpers/index.json",
"@type": "Package",
"id": "git-helpers",
"version": "1.0.0",
"description": "A collection of Git workflow skills for AI coding assistants.",
"authors": ["Jane Developer"],
"capabilities": ["skill"],
"targets": ["claude-code", "copilot-vscode", "cursor"],
"tags": ["git", "workflow"],
"totalDownloads": 8432,
"verified": false,
"versions": [
{ "version": "0.9.0", "@id": "...", "downloads": 1200 },
{ "version": "1.0.0", "@id": "...", "downloads": 7232 }
]
}
]
}
Autocomplete
GET /v3/autocomplete?q={prefix}&take={n}
→ { "totalHits": 5, "data": ["git-helpers", "git-flow", ...] }
GET /v3/autocomplete?id={id}&prerelease=false
→ { "totalHits": 3, "data": ["1.0.0", "1.1.0", "2.0.0"] }
Package Push
PUT /v3/package
Authorization: ApiKey {key}
Content-Type: multipart/form-data
Body: multipart with the .aipkg file
201 Created with Location: /v3/registration/{id}/{version}.json
Error responses:
| Code | Condition |
|---|
| 400 | Invalid package (validation failure, malformed archive, missing manifest) |
| 401 | Missing or invalid API key |
| 403 | API key does not have push permission for this package ID |
| 409 | Version already exists |
| 413 | Archive exceeds 512 MB size limit |
Package Delete (Unlist)
DELETE /v3/package/{id}/{version}
Authorization: ApiKey {key}
listed: false). Does not physically delete the package from storage. Returns 204 No Content.
{
"version": "1.0.0",
"platforms": [
{
"moniker": "claude-code",
"displayName": "Claude Code",
"parent": "claude",
"installPath": ".claude/",
"stability": "stable"
},
{
"moniker": "cursor",
"displayName": "Cursor",
"parent": "ai",
"installPath": ".cursor/",
"stability": "stable"
}
]
}
GET /v3/registration/{id}/{version}/install/{apm}
{
"id": "git-helpers",
"version": "1.0.0",
"apm": "claude-code",
"resolvedChain": ["apm/claude-code", "apm/claude", "apm/ai", "shared"],
"files": [
{
"sourcePath": "shared/prompts/base-prompt.md",
"installPath": ".claude/prompts/base-prompt.md",
"resolvedFrom": "shared"
},
{
"sourcePath": "apm/claude-code/skills/my-tool.md",
"installPath": ".claude/plugins/git-helpers/skills/my-tool.md",
"resolvedFrom": "apm/claude-code"
}
]
}
Non-Functional Requirements
| Requirement | Target |
|---|
| Package push latency | < 10s for packages < 10 MB |
| Search query p99 | < 500ms |
| Registration blob cache TTL | 5 minutes |
| Package download | Streaming; no buffering in server memory |
| API rate limiting | 100 req/min per IP (unauthenticated), 1,000/min (authenticated) |
| Max concurrent pushes per key | 5 |
Search Index Fields
The following fields are indexed and available for filtering in the search endpoint:
| Field | Type | Searchable | Filterable | Sortable |
|---|
id | string | yes | yes | yes |
version | string | no | no | no |
title | string | yes | no | no |
description | string | yes | no | no |
authors | string[] | yes | yes | no |
tags | string[] | yes | yes | no |
capabilities | string[] | no | yes | no |
targets | string[] | no | yes | no |
permissions | string[] | no | yes | no |
totalDownloads | int64 | no | no | yes |
lastPublished | DateTimeOffset | no | yes | yes |
listed | bool | no | yes | no |
verified | bool | no | yes | no |