# Testflinger API

**Canonical:** https://apis.io/apis/canonical/testflinger-api/  
**Provider:** Canonical — https://apis.io/providers/canonical/  
**Base URL:** https://testflinger.canonical.com  
**Documentation:** https://canonical-testflinger.readthedocs-hosted.com/en/latest/

Testflinger API is one of 22 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 Testing, Hardware, and CI. The published artifact set on APIs.io includes an OpenAPI specification and API documentation.

Testflinger is Canonical's hardware test-orchestration service. Its REST API accepts test jobs against named device queues, reports job status and results, serves build artifacts, and exposes agent and queue inventory. The OpenAPI 3.0.3 contract is served live from the production host.

## Operations (43)

| 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. |
| POST | `/oidc/auth-init` | Initiate client request and proxy request to OIDC provider. |
| 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. |
| POST | `/oidc/auth-poll/{request_id}` | Poll for OIDC authentication result based on request ID. |
| 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 (4)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/openapi/canonical-testflinger-api-openapi.json
- **Overlay** — https://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/overlays/canonical-testflinger-api-overlay.yaml
- **Documentation** — https://canonical-testflinger.readthedocs-hosted.com/en/latest/
- **SourceCode** — https://github.com/canonical/testflinger

## Other Canonical APIs (12)

- [Snap Store API](https://apis.io/apis/canonical/snap-store-api/)
- [Charmhub API](https://apis.io/apis/canonical/charmhub-api/)
- [snapd REST API](https://apis.io/apis/canonical/snapd-rest-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/)
- [Landscape API](https://apis.io/apis/canonical/landscape-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/)
- [LXD REST API](https://apis.io/apis/canonical/lxd-rest-api/)

## Tags

Testing, Hardware, CI

---

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