Default
root
Introduced in version 1
Summary: GET /
Return service description.
get_macaroon
Introduced in version 1
Summary: GET /v1/tokens
Return existing macaroons for the authenticated account.
If request is not authenticated, return a bakery v2 macaroon to be discharged by Candid.
get_macaroon changelog
- Version 10: Return existing macaroons when authenticated
URL Parameters
{ "properties": { "include-inactive": { "type": "string" } }, "type": "object" }
- include-inactive
Response JSON Schema
{ "additionalProperties": false, "oneOf": [ { "required": [ "macaroons" ] }, { "required": [ "macaroon" ] } ], "properties": { "macaroon": { "type": "string" }, "macaroons": { "introduced_at": 10, "items": { "properties": { "description": { "type": [ "string", "null" ] }, "revoked-at": { "type": [ "string", "null" ] }, "revoked-by": { "type": [ "string", "null" ] }, "session-id": { "type": "string" }, "valid-since": { "format": "date-time", "type": "string" }, "valid-until": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }
issue_macaroon
Introduced in version 1
Summary: POST /v1/tokens
Return a bakery v2 macaroon to be discharged by Candid.
issue_macaroon changelog
- Version 9: Add optional attenuation input fields: "permissions", "channels" and "packages"
- Version 8: Add optional "description" input field
Request JSON Schema
{ "additionalProperties": false, "properties": { "channels": { "introduced_at": 9, "items": { "description": "Valid channel name.", "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "description": { "description": "Description to help identify the macaroon", "introduced_at": 8, "type": "string" }, "packages": { "introduced_at": 9, "items": { "anyOf": [ { "required": [ "id", "type" ] }, { "required": [ "name", "type" ] } ], "description": "A dict with package type and one of name or id values.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "bin", "bundle", "charm", "rock", "rockcraft", "snap", "snapcraft", "sourcecraft" ], "type": "string" } }, "type": "object" }, "minItems": 1, "type": "array", "uniqueItems": true }, "permissions": { "introduced_at": 9, "items": { "enum": [ "account-manage-keys", "account-manage-metadata", "account-register-package", "account-view-packages", "package-manage", "package-manage-acl", "package-manage-metadata", "package-manage-releases", "package-manage-revisions", "package-view", "package-view-acl", "package-view-metadata", "package-view-metrics", "package-view-releases", "package-view-revisions", "store-manage", "store-view" ], "type": "string" }, "type": "array" }, "ttl": { "description": "Time to live, in seconds", "minimum": 10, "type": "integer" } }, "type": "object" }
Response JSON Schema
{ "type": "object" }
exchange_macaroons
Introduced in version 1
Summary: POST /v1/tokens/exchange
Return an exchanged snapstore-only authentication macaroon.
Request JSON Schema
{ "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "macaroon": { "type": "string" } }, "required": [ "macaroon" ], "type": "object" }
offline_exchange_macaroon
Introduced in version 12
Summary: POST /v1/tokens/offline/exchange
Return an exchanged offline store specific admin authentication macaroon.
publishergw has to be configured for offline use with local publishing to enable this endpoint via offline_mode setting in the store section and store_admin_* settings in the auth section.
offline_exchange_macaroon changelog
- Version 12: Added offline macaroon exchange API
Request JSON Schema
{ "additionalProperties": false, "properties": { "macaroon": { "type": "string" } }, "required": [ "macaroon" ], "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "macaroon": { "type": "string" } }, "required": [ "macaroon" ], "type": "object" }
revoke_macaroon
Introduced in version 1
Summary: POST /v1/tokens/revoke
Revoke an existing macaroon for the authenticated account.
revoke_macaroon changelog
- Version 10: Added revoke macaroon API
Request JSON Schema
{ "additionalProperties": false, "properties": { "session-id": { "type": "string" } }, "required": [ "session-id" ], "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "macaroons": { "introduced_at": 10, "items": { "properties": { "description": { "type": [ "string", "null" ] }, "revoked-at": { "type": [ "string", "null" ] }, "revoked-by": { "type": [ "string", "null" ] }, "session-id": { "type": "string" }, "valid-since": { "format": "date-time", "type": "string" }, "valid-until": { "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "macaroons" ], "type": "object" }
macaroon_info
Introduced in version 11
Summary: GET /v1/tokens/whoami
Return information about the authenticated macaroon token.
Response JSON Schema
{ "additionalProperties": false, "properties": { "account": { "additionalProperties": false, "properties": { "display-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "id": { "type": "string" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "validation": { "type": "string" } }, "required": [ "display-name", "id", "username" ], "type": "object" }, "channels": { "oneOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ] }, "packages": { "oneOf": [ { "items": { "anyOf": [ { "required": [ "id", "type" ] }, { "required": [ "name", "type" ] } ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "bin", "bundle", "charm", "rock", "rockcraft", "snap", "snapcraft", "sourcecraft" ], "type": "string" } }, "type": "object" }, "type": "array" }, { "type": "null" } ] }, "permissions": { "oneOf": [ { "items": { "enum": [ "account-manage-keys", "account-manage-metadata", "account-register-package", "account-view-packages", "package-manage", "package-manage-acl", "package-manage-metadata", "package-manage-releases", "package-manage-revisions", "package-view", "package-view-acl", "package-view-metadata", "package-view-metrics", "package-view-releases", "package-view-revisions", "store-manage", "store-view" ], "type": "string" }, "type": "array" }, { "type": "null" } ] } }, "required": [ "account", "channels", "packages", "permissions" ], "type": "object" }
list_registered_names
Introduced in version 1
Summary: GET /v1/<namespace>
Return names registered by the authenticated user.
Passing ?include-collaborations=true will also include package names for which the user is a collaborator.
list_registered_names changelog
- Version 20: Added "tracks", "guardrails" fields to VALIDATION_SCHEMA_PACKAGE output
- Version 19: Added "default-track" field to output
- Version 16: Added "links" field to output
- Version 5: Added "media" field to output
URL Parameters
{ "properties": { "fields": { "description": "A comma-separated list of fields to retrieve. Available fields: authority, contact, default-track, description, id, links, media, name, private, publisher, status, store, summary, title, track-guardrails, tracks, type, website.", "type": "string" }, "include-collaborations": { "type": "string" } }, "type": "object" }
- fields
- description: A comma-separated list of fields to retrieve. Available fields: authority, contact, default-track, description, id, links, media, name, private, publisher, status, store, summary, title, track-guardrails, tracks, type, website.
- include-collaborations
Response JSON Schema
{ "additionalProperties": false, "properties": { "results": { "items": { "additionalProperties": false, "properties": { "authority": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ] }, "default-track": { "introduced_at": 19, "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "links": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "introduced_at": 16, "type": [ "object", "null" ] }, "media": { "introduced_at": 5, "items": { "properties": { "type": { "enum": [ "icon" ], "introduced_at": 5, "type": "string" }, "url": { "introduced_at": 5, "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "type": "array" }, "name": { "type": [ "string", "null" ] }, "private": { "type": "boolean" }, "publisher": { "additionalProperties": false, "properties": { "display-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "id": { "type": "string" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "validation": { "type": "string" } }, "required": [ "display-name", "id", "username" ], "type": "object" }, "status": { "type": "string" }, "store": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "track-guardrails": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "created-at": { "type": "string" }, "pattern": { "type": "string" } }, "required": [ "pattern", "created-at" ], "type": "object" }, "type": [ "array", "null" ] }, "tracks": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "automatic-phasing-percentage": { "oneOf": [ { "type": "null" }, { "type": "number" } ] }, "created-at": { "type": "string" }, "name": { "type": "string" }, "version-pattern": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "name", "version-pattern", "created-at", "automatic-phasing-percentage" ], "type": "object" }, "type": [ "array", "null" ] }, "type": { "type": "string" }, "website": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "results" ], "type": "object" }
register_name
Introduced in version 1
Summary: POST /v1/<namespace>
Register the specified name for the authenticated user.
register_name changelog
- Version 4: Add optional "team" field
- Version 3: Add optional "private" field
Request JSON Schema
{ "additionalProperties": false, "properties": { "name": { "type": "string" }, "private": { "default": false, "introduced_at": 3, "type": "boolean" }, "team": { "introduced_at": 4, "type": [ "string", "null" ] }, "type": { "enum": [ "bin", "bundle", "charm", "rock", "rockcraft", "snap", "snapcraft", "sourcecraft" ], "type": "string" } }, "required": [ "name" ], "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "id": { "type": "string" } }, "required": [ "id" ], "type": "object" }
package_metadata
Introduced in version 1
Summary: GET /v1/<namespace>/<name>
Get general metadata for a package.
package_metadata changelog
- Version 20: Added "tracks", "guardrails" fields to output
- Version 19: Added "default-track" field to output
- Version 16: Added "links" field to output
- Version 5: Added "media" field to output
URL Parameters
{ "properties": { "fields": { "description": "A comma-separated list of fields to retrieve. Available fields: authority, contact, default-track, description, id, links, media, name, private, publisher, status, store, summary, title, track-guardrails, tracks, type, website.", "type": "string" } }, "type": "object" }
- fields
- description: A comma-separated list of fields to retrieve. Available fields: authority, contact, default-track, description, id, links, media, name, private, publisher, status, store, summary, title, track-guardrails, tracks, type, website.
Response JSON Schema
{ "additionalProperties": false, "properties": { "metadata": { "additionalProperties": false, "properties": { "authority": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ] }, "default-track": { "introduced_at": 19, "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "links": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "introduced_at": 16, "type": [ "object", "null" ] }, "media": { "introduced_at": 5, "items": { "properties": { "type": { "enum": [ "icon" ], "introduced_at": 5, "type": "string" }, "url": { "introduced_at": 5, "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "type": "array" }, "name": { "type": [ "string", "null" ] }, "private": { "type": "boolean" }, "publisher": { "additionalProperties": false, "properties": { "display-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "id": { "type": "string" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "validation": { "type": "string" } }, "required": [ "display-name", "id", "username" ], "type": "object" }, "status": { "type": "string" }, "store": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "track-guardrails": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "created-at": { "type": "string" }, "pattern": { "type": "string" } }, "required": [ "pattern", "created-at" ], "type": "object" }, "type": [ "array", "null" ] }, "tracks": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "automatic-phasing-percentage": { "oneOf": [ { "type": "null" }, { "type": "number" } ] }, "created-at": { "type": "string" }, "name": { "type": "string" }, "version-pattern": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "name", "version-pattern", "created-at", "automatic-phasing-percentage" ], "type": "object" }, "type": [ "array", "null" ] }, "type": { "type": "string" }, "website": { "type": [ "string", "null" ] } }, "type": "object" } }, "required": [ "metadata" ], "type": "object" }
update_package_metadata
Introduced in version 1
Summary: PATCH /v1/<namespace>/<name>
Update general metadata for a package.
update_package_metadata changelog
- Version 20: Added "tracks", "guardrails" fields to VALIDATION_SCHEMA_PACKAGE output
- Version 19: Added support for the "default-track" field
- Version 16: Added "links" field to output
- Version 5: Added "media" field to output
Request JSON Schema
{ "additionalProperties": false, "properties": { "contact": { "type": "string" }, "default-track": { "introduced_at": 19, "type": [ "string", "null" ] }, "description": { "type": "string" }, "private": { "type": "boolean" }, "summary": { "type": "string" }, "title": { "type": "string" }, "website": { "type": "string" } }, "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "metadata": { "additionalProperties": false, "properties": { "authority": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ] }, "default-track": { "introduced_at": 19, "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "links": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "introduced_at": 16, "type": [ "object", "null" ] }, "media": { "introduced_at": 5, "items": { "properties": { "type": { "enum": [ "icon" ], "introduced_at": 5, "type": "string" }, "url": { "introduced_at": 5, "type": "string" } }, "required": [ "type", "url" ], "type": "object" }, "type": "array" }, "name": { "type": [ "string", "null" ] }, "private": { "type": "boolean" }, "publisher": { "additionalProperties": false, "properties": { "display-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "id": { "type": "string" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "validation": { "type": "string" } }, "required": [ "display-name", "id", "username" ], "type": "object" }, "status": { "type": "string" }, "store": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "track-guardrails": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "created-at": { "type": "string" }, "pattern": { "type": "string" } }, "required": [ "pattern", "created-at" ], "type": "object" }, "type": [ "array", "null" ] }, "tracks": { "introduced_at": 20, "items": { "additionalProperties": false, "properties": { "automatic-phasing-percentage": { "oneOf": [ { "type": "null" }, { "type": "number" } ] }, "created-at": { "type": "string" }, "name": { "type": "string" }, "version-pattern": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "name", "version-pattern", "created-at", "automatic-phasing-percentage" ], "type": "object" }, "type": [ "array", "null" ] }, "type": { "type": "string" }, "website": { "type": [ "string", "null" ] } }, "type": "object" } }, "required": [ "metadata" ], "type": "object" }
unregister_package
Introduced in version 1
Summary: DELETE /v1/<namespace>/<name>
Unregister the package matching the provided (namespace, name) pair.
Expects:
Nothing.
Returns:
On success: HTTP 200 with a JSON object containing a required package-id property which indicates the ID of the name that was unregistered.
On failing to find the package with the given namespace and name: HTTP 404
with message "Name
On attempting to unregister a charm with invalid credentials: HTTP 401 with message "discharge required" or HTTP 401 with message "Unauthorized", depending on if the payload contains a macaroon or not.
On attempting to unregister a snap with Charmhub credentials: HTTP 401 with message "Unregistering snaps requires Snapcraft credentials".
On attempting to unregister a package with existing revisions: HTTP 403 with message "Cannot unregister a package with existing revisions".
On attempting to unregister a charm as a collaborator instead of as the publisher: HTTP 401 with message "Charms can only be unregistered by their publisher"
Note: Charm Bundles do live in the charm namespace.
Note: Snap authentication and authorization is handled by passing the usual Dashboard 'Authorization:' header to this endpoint.
Response JSON Schema
{ "additionalProperties": false, "properties": { "package-id": { "type": "string" } }, "required": [ "package-id" ], "type": "object" }
list_revisions
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/revisions
List existing revisions for a package.
list_revisions changelog
- Version 13: Add support for snaps
- Version 7: Add "bases" field to response
URL Parameters
{ "properties": { "fields": { "description": "A comma-separated list of fields to retrieve. Available fields depend on namespace - **bin**: created-at, created-by, revision, sha3-384, size, status, version; **charm**: bases, created-at, errors, revision, sha3-384, size, status, version; **snap**: apps, architectures, base, build-url, confinement, created-at, created-by, grade, revision, sha3-384, size, status, type, version; **snapcraft**: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status; **sourcecraft**: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status; **rock**: created-at, created-by, revision, sha256, status; **rockcraft**: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status.", "type": "string" }, "include-craft-yaml": { "description": "Return craft.yaml file of revision if true.", "type": "string" }, "revision": { "description": "The number of a specific revision to retrieve.", "pattern": "^[0-9]+$", "type": "string" } }, "type": "object" }
- fields
- description: A comma-separated list of fields to retrieve. Available fields depend on namespace - bin: created-at, created-by, revision, sha3-384, size, status, version; charm: bases, created-at, errors, revision, sha3-384, size, status, version; snap: apps, architectures, base, build-url, confinement, created-at, created-by, grade, revision, sha3-384, size, status, type, version; snapcraft: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status; sourcecraft: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status; rock: created-at, created-by, revision, sha256, status; rockcraft: commit-id, craft-yaml, created-at, created-by, revision, sha3-384, status.
- include-craft-yaml
- description: Return craft.yaml file of revision if true.
- revision
- description: The number of a specific revision to retrieve.
- Must match regex "^[0-9]+$"
Response JSON Schema
{ "additionalProperties": false, "properties": { "revisions": { "anyOf": [ { "items": { "additionalProperties": false, "properties": { "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" } }, { "items": { "additionalProperties": false, "properties": { "bases": { "description": "The revision's supported bases.", "introduced_at": 7, "items": { "additionalProperties": false, "introduced_at": 7, "properties": { "architecture": { "introduced_at": 7, "type": "string" }, "channel": { "introduced_at": 7, "type": "string" }, "name": { "introduced_at": 7, "type": "string" } }, "type": [ "object", "null" ] }, "type": "array" }, "created-at": { "format": "date-time", "type": "string" }, "errors": { "oneOf": [ { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" }, { "type": "null" } ] }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" } }, { "items": { "additionalProperties": false, "properties": { "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha256": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } }, { "items": { "additionalProperties": false, "properties": { "apps": { "items": { "type": "string" }, "type": "array" }, "architectures": { "items": { "type": "string" }, "type": "array" }, "base": { "type": [ "string", "null" ] }, "build-url": { "type": [ "string", "null" ] }, "confinement": { "enum": [ "strict", "classic", "devmode" ], "type": "string" }, "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "grade": { "enum": [ "stable", "devel" ], "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "type": { "enum": [ "app", "os", "gadget", "kernel", "base", "snapd" ], "type": "string" }, "version": { "type": "string" } }, "type": "object" } }, { "items": { "additionalProperties": false, "properties": { "commit-id": { "type": "string" }, "craft-yaml": { "type": "object" }, "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "status": { "type": "string" } }, "type": "object" } } ], "type": "array" } }, "required": [ "revisions" ], "type": "object" }
push_resource
Introduced in version 1
Summary: POST /v1/<namespace>/<name>/resources/<resource_name>/revisions
Push a new revision for a package resource.
push_resource changelog
- Version 27: Added optional "package-revision" input field
- Version 25: Added optional "bases" input field
- Version 6: Added optional "resource_type" input field
Request JSON Schema
{ "additionalProperties": false, "properties": { "bases": { "description": "List of architectures supported by this resource revision", "introduced_at": 25, "items": { "additionalProperties": false, "introduced_at": 25, "properties": { "architectures": { "introduced_at": 25, "items": { "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "channel": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "channel", "architectures" ], "type": "object" }, "minItems": 1, "type": "array", "uniqueItems": true }, "package-revision": { "description": "Optional revision of the package this resource is valid for. This value is only relevant for snap resources currently.", "introduced_at": 27, "minimum": 1, "type": "integer" }, "type": { "enum": [ "file", "oci-image", "component/test", "component/kernel-modules", "component/standard" ], "introduced_at": 6, "type": "string" }, "upload-id": { "type": "string" } }, "required": [ "upload-id" ], "type": "object" }
Response JSON Schema
{ "properties": { "status-url": { "type": "string" } }, "required": [ "status-url" ], "type": "object" }
push_revision
Introduced in version 1
Summary: POST /v1/<namespace>/<name>/revisions
Push a new revision for a package.
push_revision changelog
- Version 13: Add support for snaps
Request JSON Schema
{ "additionalProperties": false, "properties": { "upload-id": { "type": "string" } }, "required": [ "upload-id" ], "type": "object" }
Response JSON Schema
{ "properties": { "status-url": { "type": "string" } }, "required": [ "status-url" ], "type": "object" }
list_upload_reviews
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/revisions/review
List existing uploads review status for a package.
list_upload_reviews changelog
- Version 13: Add support for snaps
URL Parameters
{ "properties": { "upload-id": { "description": "The ID of a specific upload to view the status of.", "type": "string" } }, "type": "object" }
- upload-id
- description: The ID of a specific upload to view the status of.
Response JSON Schema
{ "additionalProperties": false, "properties": { "revisions": { "items": { "additionalProperties": false, "properties": { "errors": { "oneOf": [ { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" }, { "type": "null" } ] }, "revision": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "status": { "type": "string" }, "upload-id": { "type": "string" } }, "required": [ "errors", "revision", "status", "upload-id" ], "type": "object" }, "type": "array" } }, "required": [ "revisions" ], "type": "object" }
list_resources
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/resources
List existing declared resources for a package.
URL Parameters
{ "properties": { "revision": { "description": "A specific revision to list resources for.", "pattern": "^[0-9]+$", "type": "string" } }, "type": "object" }
- revision
- description: A specific revision to list resources for.
- Must match regex "^[0-9]+$"
Response JSON Schema
{ "additionalProperties": false, "properties": { "resources": { "items": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "optional": { "type": "boolean" }, "revision": { "type": "integer" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "type": "array" } }, "required": [ "resources" ], "type": "object" }
list_resource_revisions
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/resources/<resource_name>/revisions
List existing revisions for a package resource.
list_resource_revisions changelog
- Version 28: Added "architectures" field to output for snap resources. Mutually exclusive with bases
- Version 25: Added "bases", "updated-at" and "updated-by" fields to output
- Version 6: Added "type" field to output
Response JSON Schema
{ "additionalProperties": false, "properties": { "revisions": { "items": { "additionalProperties": false, "oneOf": [ { "not": { "required": [ "architectures" ] }, "required": [ "name", "bases" ] }, { "not": { "required": [ "bases" ] }, "required": [ "name", "architectures" ] } ], "properties": { "architectures": { "introduced_at": 28, "items": { "introduced_at": 28, "type": "string" }, "type": "array" }, "bases": { "description": "List of architectures supported by this resource revision", "introduced_at": 25, "items": { "additionalProperties": false, "introduced_at": 25, "properties": { "architectures": { "introduced_at": 25, "items": { "type": "string" }, "type": "array" }, "channel": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "channel", "architectures" ], "type": "object" }, "type": "array" }, "created-at": { "format": "date-time", "type": "string" }, "name": { "type": "string" }, "revision": { "type": "integer" }, "sha256": { "type": "string" }, "sha3-384": { "type": "string" }, "sha384": { "type": "string" }, "sha512": { "type": "string" }, "size": { "type": "integer" }, "type": { "introduced_at": 6, "type": "string" }, "updated-at": { "introduced_at": 25, "type": [ "string", "null" ] }, "updated-by": { "introduced_at": 25, "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" } }, "required": [ "revisions" ], "type": "object" }
update_resource_revisions
Introduced in version 25
Summary: PATCH /v1/<namespace>/<name>/resources/<resource_name>/revisions
Update the metadata for a package resource revision.
Currently, the only editable metadata for a resource revision is the set of bases it supports. A base refers to the OS, OS version, and machine architectures for that OS/version pair. Specify 'all' (['all'] for machine architectures) for any of the fields to indicate that the resource revision is agnostic to that field.
update_resource_revisions changelog
- Version 25: New endpoint to update resource revision architectures
Request JSON Schema
{ "additionalProperties": false, "properties": { "resource-revision-updates": { "introduced_at": 25, "items": { "additionalProperties": false, "properties": { "bases": { "description": "List of architectures supported by this resource revision", "introduced_at": 25, "items": { "additionalProperties": false, "introduced_at": 25, "properties": { "architectures": { "introduced_at": 25, "items": { "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "channel": { "type": "string" }, "name": { "type": "string" } }, "required": [ "name", "channel", "architectures" ], "type": "object" }, "minItems": 1, "type": "array", "uniqueItems": true }, "revision": { "type": "integer" } }, "required": [ "revision", "bases" ], "type": "object" }, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "resource-revision-updates" ], "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "num-resource-revisions-updated": { "type": "integer" } }, "required": [ "num-resource-revisions-updated" ], "type": "object" }
oci_image_resource_upload_credentials
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/resources/<resource_name>/oci-image/upload-credentials
Get Charmstore docker registry auth server credential for oci-image upload.
Returns image name and Charmstore docker registry auth server credentials for for a specific image upload to this registry.
Response JSON Schema
{ "additionalProperties": false, "properties": { "image-name": { "type": "string" }, "password": { "type": "string" }, "username": { "type": "string" } }, "required": [ "image-name", "username", "password" ], "type": "object" }
oci_image_resource_blob
Introduced in version 1
Summary: POST /v1/<namespace>/<name>/resources/<resource_name>/oci-image/blob
Return OCI-image resource blob as expected by Juju.
Request JSON Schema
{ "additionalProperties": false, "properties": { "image-digest": { "type": "string" } }, "required": [ "image-digest" ], "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "ImageName": { "type": "string" }, "Password": { "type": "string" }, "Username": { "type": "string" } }, "required": [ "ImageName", "Username", "Password" ], "type": "object" }
list_releases
Introduced in version 1
Summary: GET /v1/<namespace>/<name>/releases
List current releases for a package.
list_releases changelog
- Version 41: Add support for architecture & progressive releases in rocks channelmap
- Version 13: Add support for snaps
- Version 7: Add "bases" to revisions and "base" to channel-map response fields
- Version 2: Add resources output in channelmap
Response JSON Schema
{ "anyOf": [ { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "channel": { "description": "The channel name, including \"latest\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "channel", "expiration-date", "revision", "when" ], "type": "object" }, "type": "array" }, "package": { "properties": { "channels": { "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested package.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "type": "array" } }, "required": [ "channels" ], "type": "object" }, "revisions": { "items": { "additionalProperties": false, "properties": { "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "channel-map", "package", "revisions" ] }, { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "base": { "additionalProperties": false, "introduced_at": 7, "properties": { "architecture": { "introduced_at": 7, "type": "string" }, "channel": { "introduced_at": 7, "type": "string" }, "name": { "introduced_at": 7, "type": "string" } }, "type": [ "object", "null" ] }, "channel": { "description": "The channel name, including \"latest\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "properties": { "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage" ], "type": "object" }, "resources": { "introduced_at": 2, "items": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "revision": { "type": [ "integer", "null" ] }, "type": { "type": "string" } }, "type": "object" }, "type": "array" }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "base", "channel", "expiration-date", "progressive", "resources", "revision", "when" ], "type": "object" }, "type": "array" }, "package": { "properties": { "channels": { "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested package.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "type": "array" } }, "required": [ "channels" ], "type": "object" }, "revisions": { "items": { "additionalProperties": false, "properties": { "bases": { "description": "The revision's supported bases.", "introduced_at": 7, "items": { "additionalProperties": false, "introduced_at": 7, "properties": { "architecture": { "introduced_at": 7, "type": "string" }, "channel": { "introduced_at": 7, "type": "string" }, "name": { "introduced_at": 7, "type": "string" } }, "type": [ "object", "null" ] }, "type": "array" }, "created-at": { "format": "date-time", "type": "string" }, "errors": { "oneOf": [ { "items": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" }, { "type": "null" } ] }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "channel-map", "package", "revisions" ] }, { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "architecture": { "introduced_at": 13, "type": "string" }, "channel": { "description": "The channel name, including \"latest\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "properties": { "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage" ], "type": "object" }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "architecture", "channel", "expiration-date", "progressive", "revision", "when" ], "type": "object" }, "type": "array" }, "package": { "properties": { "channels": { "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested package.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "type": "array" } }, "required": [ "channels" ], "type": "object" }, "revisions": { "items": { "additionalProperties": false, "properties": { "apps": { "items": { "type": "string" }, "type": "array" }, "architectures": { "items": { "type": "string" }, "type": "array" }, "base": { "type": [ "string", "null" ] }, "build-url": { "type": [ "string", "null" ] }, "confinement": { "enum": [ "strict", "classic", "devmode" ], "type": "string" }, "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "grade": { "enum": [ "stable", "devel" ], "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "size": { "type": "integer" }, "status": { "type": "string" }, "type": { "enum": [ "app", "os", "gadget", "kernel", "base", "snapd" ], "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "channel-map", "package", "revisions" ] }, { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "channel": { "description": "The channel name, including \"latest\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "properties": { "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage" ], "type": "object" }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "channel", "expiration-date", "progressive", "revision", "when" ], "type": "object" }, "type": "array" }, "package": { "properties": { "channels": { "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested package.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "type": "array" } }, "required": [ "channels" ], "type": "object" }, "revisions": { "items": { "additionalProperties": false, "properties": { "commit-id": { "type": "string" }, "craft-yaml": { "type": "object" }, "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha3-384": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "channel-map", "package", "revisions" ] }, { "additionalProperties": false, "properties": { "channel-map": { "items": { "additionalProperties": false, "properties": { "architecture": { "introduced_at": 41, "type": "string" }, "channel": { "description": "The channel name, including \"latest\" for the latest track.", "type": "string" }, "expiration-date": { "description": "The date when this release expires, in RFC 3339 format. If null, the release does not expire.", "format": "date-time", "type": [ "string", "null" ] }, "progressive": { "additionalProperties": false, "introduced_at": 41, "properties": { "paused": { "type": [ "boolean", "null" ] }, "percentage": { "type": [ "number", "null" ] } }, "required": [ "paused", "percentage" ], "type": "object" }, "revision": { "type": "integer" }, "when": { "description": "The date when this release was made, in RFC 3339 format.", "format": "date-time", "type": "string" } }, "required": [ "architecture", "channel", "expiration-date", "progressive", "revision", "when" ], "type": "object" }, "type": "array" }, "package": { "properties": { "channels": { "items": { "additionalProperties": false, "description": "A list of channels and their metadata for the requested package.", "properties": { "branch": { "description": "The branch name for this channel, can be null.", "type": [ "string", "null" ] }, "fallback": { "description": "The name of the channel that this channel would fall back to if there were no releases in it. If null, this channel has no fallback channel.", "type": [ "string", "null" ] }, "name": { "description": "The channel name, including \"latest/\" for the latest track.", "type": "string" }, "risk": { "description": "The risk name for this channel.", "type": "string" }, "track": { "description": "The track name for this channel.", "type": "string" } }, "required": [ "name", "track", "risk", "branch", "fallback" ], "type": "object" }, "type": "array" } }, "required": [ "channels" ], "type": "object" }, "revisions": { "items": { "additionalProperties": false, "properties": { "created-at": { "format": "date-time", "type": "string" }, "created-by": { "type": "string" }, "revision": { "type": "integer" }, "sha256": { "type": "string" }, "status": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "channel-map", "package", "revisions" ] } ], "type": "object" }
release
Introduced in version 1
Summary: POST /v1/<namespace>/<name>/releases
Release one or more revisions for a package.
release changelog
- Version 17: Add list of released revisions to response
- Version 13: Add support for snaps
Request JSON Schema
{ "items": { "additionalProperties": false, "properties": { "channel": { "type": "string" }, "resources": { "items": { "properties": { "name": { "type": "string" }, "revision": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "revision": { "type": [ "integer", "null" ] } }, "required": [ "channel", "revision" ], "type": "object" }, "type": "array" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "released": { "introduced_at": 17, "items": { "properties": { "channel": { "type": "string" }, "resources": { "items": { "properties": { "name": { "type": "string" }, "revision": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" }, "revision": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array" } }, "type": "object" }
exchange_dashboard_macaroons
Introduced in version 15
Summary: POST /v1/tokens/dashboard/exchange
Exchange dashboard.snapcraft.io SSO discharged macaroons for a developer token. The macaroons are expected to be passed in as the Authorization header.
Request JSON Schema
{ "additionalProperties": false, "properties": { "client-description": { "maxLength": 1024, "type": [ "string", "null" ] } }, "type": "object" }
Response JSON Schema
{ "additionalProperties": false, "properties": { "macaroon": { "type": "string" } }, "required": [ "macaroon" ], "type": "object" }
create_tracks
Introduced in version 20
Summary: POST /v1/<namespace>/<name>/tracks
Create new tracks for a package.
Track creation requests must match an existing track creation pattern. In order to register such a pattern in the store, please contact the snap store admins in the https://forum.snapcraft.io/ (for snaps) or https://discourse.charmhub.io/ (for charms).
Request JSON Schema
{ "items": { "additionalProperties": false, "properties": { "automatic-phasing-percentage": { "oneOf": [ { "type": "null" }, { "type": "number" } ] }, "name": { "maxLength": 28, "pattern": "^[a-zA-Z0-9](?:[_.-]?[a-zA-Z0-9])*$", "type": "string" }, "version-pattern": { "oneOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "name" ], "type": "object" }, "type": "array" }
Response JSON Schema
{ "properties": { "num-tracks-created": { "type": "integer" } }, "required": [ "num-tracks-created" ], "type": "object" }
whoami (DEPRECATED)
Deprecated: Deprecated from version 11
Introduced in version 1
Summary: GET /v1/whoami
Return authenticated user details.
Deprecation notice: /v1/tokens/whoami should be used instead.
Response JSON Schema
{ "additionalProperties": false, "properties": { "display-name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "id": { "type": "string" }, "username": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "validation": { "type": "string" } }, "required": [ "display-name", "id", "username" ], "type": "object" }