# Canonical V1 API

**Canonical:** https://apis.io/apis/canonical/canonical-v1-api/  
**Provider:** Canonical — https://apis.io/providers/canonical/  
**Base URL:** https://api.snapcraft.io  
**Documentation:** https://api.snapcraft.io/docs/

Canonical V1 API is one of 114 APIs that [Canonical](https://apis.io/providers/canonical/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include v1. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and release notes.

The V1 API from Canonical — 29 operation(s) for v1.

## Operations (41)

| Method | Path | Summary |
|---|---|---|
| GET | `/v1/` | Identify ourselves |
| GET | `/v1/job` | Request a job to run from supported queues |
| POST | `/v1/job` | Add a job to the queue |
| GET | `/v1/job/search` | Search for jobs by tags |
| GET | `/v1/agents/data` | Get all agent data |
| GET | `/v1/job/{job_id}` | Request the json job definition for a specified job, even if it has |
| POST | `/v1/oauth2/token` | Issue both access token and refresh token for a client |
| GET | `/v1/agents/queues` | Get all advertised queues from this server |
| POST | `/v1/agents/queues` | Tell testflinger the queue names that are being serviced |
| POST | `/v1/agents/images` | Tell testflinger about known images for a specified queue |
| POST | `/v1/oauth2/revoke` | Revoke a refresh token. Only admins can perform this action |
| POST | `/v1/oauth2/refresh` | Refresh access token using a valid refresh token |
| GET | `/v1/result/{job_id}` | Return results for a specified job_id |
| POST | `/v1/result/{job_id}` | Post a result for a specified job_id |
| GET | `/v1/queues/wait_times` | Get wait time metrics - optionally take a list of queues |
| GET | `/v1/restricted-queues` | List all agent's restricted queues and its owners |
| GET | `/v1/client-permissions` | Retrieve all client permissions from database |
| POST | `/v1/job/{job_id}/action` | Take action on the job status for a specified job ID |
| POST | `/v1/job/{job_id}/events` | Post status updates from the agent to the server to be forwarded |
| GET | `/v1/agents/images/{queue}` | Get a dict of known images for a given queue |
| GET | `/v1/job/{job_id}/position` | Return the position of the specified jobid in the queue |
| GET | `/v1/result/{job_id}/status` | Return job state and phase exit codes for a specified job_id |
| GET | `/v1/job/{job_id}/attachments` | Return the attachments bundle for a specified job_id |
| POST | `/v1/job/{job_id}/attachments` | Post attachment bundle for a specified job_id |
| GET | `/v1/result/{job_id}/artifact` | Return artifact bundle for a specified job_id |
| POST | `/v1/result/{job_id}/artifact` | Post artifact bundle for a specified job_id |
| GET | `/v1/agents/data/{agent_name}` | Get the information from a specified agent |
| POST | `/v1/agents/data/{agent_name}` | Post information about the agent to the server |
| GET | `/v1/queues/{queue_name}/jobs` | Get the jobs in a specified queue along with its state |
| GET | `/v1/queues/{queue_name}/agents` | Get the list of all data for agents listening to a specified queue |
| GET | `/v1/restricted-queues/{queue_name}` | Get restricted queues for a specific agent |
| POST | `/v1/restricted-queues/{queue_name}` | Add an owner to the specific restricted queue |
| DELETE | `/v1/restricted-queues/{queue_name}` | Delete an owner from the specific restricted queue |
| GET | `/v1/client-permissions/{client_id}` | Retrieve single client-permissions from database |
| PUT | `/v1/client-permissions/{client_id}` | Add or create client permissions for a specified user |
| DELETE | `/v1/client-permissions/{client_id}` | Delete client id along with its permissions |
| PUT | `/v1/secrets/{client_id}/{path}` | Store a secret value for the specified client_id and path |
| DELETE | `/v1/secrets/{client_id}/{path}` | Remove a secret value for the specified client_id and path |
| POST | `/v1/agents/provision_logs/{agent_name}` | Post provision logs for the agent to the server |
| GET | `/v1/result/{job_id}/log/{log_type}` | Get logs for a specified job_id |
| POST | `/v1/result/{job_id}/log/{log_type}` | Post logs for a specified job ID |

## Machine-readable artifacts (25)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/openapi/canonical-v1-api-openapi.yml
- **Documentation** — https://snapcraft.io/docs/reference/development/snapd-rest-api/
- **HowTo** — https://snapcraft.io/docs/how-to-guides/snap-development/use-the-rest-api/
- **Documentation** — https://ubuntu.com/landscape/docs
- **APIReference** — https://documentation.ubuntu.com/landscape/reference/api/
- **ReleaseNotes** — https://documentation.ubuntu.com/landscape/reference/release-notes/
- **Portal** — https://ubuntu.com/landscape
- **Documentation** — https://documentation.ubuntu.com/lxd/latest/rest-api/
- **APIReference** — https://documentation.ubuntu.com/lxd/latest/api-extensions/
- **SourceCode** — https://github.com/canonical/lxd
- **Portal** — https://canonical.com/lxd
- **Documentation** — https://ubuntu.com/security/api/docs
- **APIReference** — https://ubuntu.com/security/api/spec.json
- **Portal** — https://ubuntu.com/security
- **Documentation** — https://documentation.ubuntu.com/pebble/
- **SourceCode** — https://github.com/canonical/pebble
- **Documentation** — https://canonical-testflinger.readthedocs-hosted.com/en/latest/
- **SourceCode** — https://github.com/canonical/testflinger
- **SourceCode** — https://github.com/canonical/hardware-api
- **Portal** — https://ubuntu.com/certified
- **SourceCode** — https://github.com/canonical/identity-platform-api
- **SourceCode** — https://github.com/canonical/test_observer
- **Documentation** — https://documentation.ubuntu.com/anbox-cloud/
- **Portal** — https://canonical.com/anbox-cloud
- **SourceCode** — https://github.com/canonical/cos-registration-server

## Other Canonical APIs (12)

- [Snap Store API](https://apis.io/apis/canonical/snap-store-api/)
- [Charmhub API](https://apis.io/apis/canonical/charmhub-api/)
- [MAAS API](https://apis.io/apis/canonical/maas-api/)
- [Juju Client / Controller API](https://apis.io/apis/canonical/juju-api/)
- [Launchpad Web Services API](https://apis.io/apis/canonical/launchpad-api/)
- [Ubuntu Pro Client API](https://apis.io/apis/canonical/ubuntu-pro-api/)
- [Canonical Assertions API](https://apis.io/apis/canonical/canonical-assertions-api/)
- [Canonical Search API](https://apis.io/apis/canonical/canonical-search-api/)
- [Canonical Snaps API](https://apis.io/apis/canonical/canonical-snaps-api/)
- [MicroCeph REST API](https://apis.io/apis/canonical/microceph-api/)
- [Canonical App Authorization Service API](https://apis.io/apis/canonical/canonical-appauthorizationservice-api/)
- [Canonical Application API](https://apis.io/apis/canonical/canonical-application-api/)

## Tags

v1

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/canonical/canonical-v1-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/canonical/.