How AI is applied across API Evangelist and APIs.io. Read my AI disclosure →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

Need help?

Contact us
Canonical

Testflinger API

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.

Documentation Provider Profile APIs.io OpenAPI GitHub

Testflinger API is one of 22 APIs that Canonical publishes on the 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.

This API exposes 43 operations across 31 paths, organized into 2 resource areas, and defines 32 schemas. It is described by OpenAPI 3.0.3, at version 1.0.0.

Requests are made against a single base URL, https://testflinger.ps7.canonical.com/.

43 operations 31 paths 32 schemas 3 DELETE21 GET17 POST2 PUT

Metadata

The identity and technical contract details declared by the specification.

Specification
OpenAPI 3.0.3
API Version
1.0.0
Base URL
https://testflinger.canonical.com
Resource Areas
2

Paths & Operations 43

Across 31 paths, the API surfaces 43 operations — 3 DELETE, 21 GET, 17 POST, 2 PUT. They span 2 resource areas: V1, Oidc_Api. Each is listed below with its method, path, parameters, and response codes.

V1 41
GET
/v1/
Identify ourselves.
→ 200
GET
/v1/job
Request a job to run from supported queues.
→ 200204
POST
/v1/job
Add a job to the queue.
body → 200422
GET
/v1/job/search
Search for jobs by tags.
3 params → 200422
GET
/v1/agents/data
Get all agent data.
→ 200
GET
/v1/job/{job_id}
Request the json job definition for a specified job, even if it has
1 param → 200404
POST
/v1/oauth2/token
Issue both access token and refresh token for a client.
→ 200
GET
/v1/agents/queues
Get all advertised queues from this server.
→ 200
POST
/v1/agents/queues
Tell testflinger the queue names that are being serviced.
body → 200422
POST
/v1/agents/images
Tell testflinger about known images for a specified queue
body → 200422
POST
/v1/oauth2/revoke
Revoke a refresh token. Only admins can perform this action.
body → 200422
POST
/v1/oauth2/refresh
Refresh access token using a valid refresh token.
body → 200422
GET
/v1/result/{job_id}
Return results for a specified jobid.
1 param → 200404204
POST
/v1/result/{job_id}
Post a result for a specified jobid.
1 param body → 200422404
GET
/v1/queues/wait_times
Get wait time metrics - optionally take a list of queues.
→ 200
GET
/v1/restricted-queues
List all agent's restricted queues and its owners.
→ 200
GET
/v1/client-permissions
Retrieve all client permissions from database.
→ 200
POST
/v1/job/{job_id}/action
Take action on the job status for a specified job ID.
1 param body → 200422404
POST
/v1/job/{job_id}/events
Post status updates from the agent to the server to be forwarded
1 param body → 200422404
GET
/v1/agents/images/{queue}
Get a dict of known images for a given queue.
1 param → 404200
GET
/v1/job/{job_id}/position
Return the position of the specified jobid in the queue.
1 param → 200404
GET
/v1/result/{job_id}/status
Return job state and phase exit codes for a specified jobid.
1 param → 200404204
GET
/v1/job/{job_id}/attachments
Return the attachments bundle for a specified jobid.
1 param → 200404
POST
/v1/job/{job_id}/attachments
Post attachment bundle for a specified jobid.
1 param → 200404
GET
/v1/result/{job_id}/artifact
Return artifact bundle for a specified jobid.
1 param → 200404
POST
/v1/result/{job_id}/artifact
Post artifact bundle for a specified jobid.
1 param → 200404
GET
/v1/agents/data/{agent_name}
Get the information from a specified agent.
1 param → 200404
POST
/v1/agents/data/{agent_name}
Post information about the agent to the server.
1 param body → 200422404
GET
/v1/queues/{queue_name}/jobs
Get the jobs in a specified queue along with its state.
1 param → 200404
GET
/v1/queues/{queue_name}/agents
Get the list of all data for agents listening to a specified queue.
1 param → 200404
GET
/v1/restricted-queues/{queue_name}
Get restricted queues for a specific agent.
1 param → 200404
POST
/v1/restricted-queues/{queue_name}
Add an owner to the specific restricted queue.
1 param body → 200422404
DELETE
/v1/restricted-queues/{queue_name}
Delete an owner from the specific restricted queue.
1 param body → 200422404
GET
/v1/client-permissions/{client_id}
Retrieve single client-permissions from database.
1 param → 200404
PUT
/v1/client-permissions/{client_id}
Add or create client permissions for a specified user.
1 param body → 200422404
DELETE
/v1/client-permissions/{client_id}
Delete client id along with its permissions.
1 param → 200404
PUT
/v1/secrets/{client_id}/{path}
Store a secret value for the specified clientid and path.
2 params body → 200422404
DELETE
/v1/secrets/{client_id}/{path}
Remove a secret value for the specified clientid and path.
2 params → 200404
POST
/v1/agents/provision_logs/{agent_name}
Post provision logs for the agent to the server.
1 param body → 200422404
GET
/v1/result/{job_id}/log/{log_type}
Get logs for a specified jobid.
2 params → 200404
POST
/v1/result/{job_id}/log/{log_type}
Post logs for a specified job ID.
2 params body → 200422404
Oidc_Api 2
POST
/oidc/auth-init
Initiate client request and proxy request to OIDC provider.
→ 200
POST
/oidc/auth-poll/{request_id}
Poll for OIDC authentication result based on request ID.
1 param → 200404

Schemas 32

The contract defines 32 schemas that model the data the API accepts and returns. The most detailed are ResultGet (24 properties), JobOut (18 properties), Job (17 properties), AgentOut (9 properties). Each schema is shown below with its type and property counts.

JobId
object
1 property 1 required
ValidationError
object
2 properties
ProvisionData
object
Attachment
object
2 properties 1 required
TestData
object
5 properties
ReserveData
object
2 properties
Job
object
17 properties 1 required
JobSearchResponse
object
1 property 1 required
AgentJob
object
8 properties 1 required
AgentOut
object
9 properties 1 required
JobOut
object
18 properties 1 required
HTTPError
object
2 properties
QueuesIn
object
ImagesIn
object
RefreshTokenIn
object
1 property 1 required
ResultPost
object
4 properties
ResultGet
object
24 properties
RestrictedQueueOut
object
2 properties 2 required
ClientPermissionsOut
object
6 properties 5 required
ActionIn
object
1 property 1 required
JobEvent
object
3 properties 2 required
StatusUpdate
object
4 properties 1 required
ResultStatus
object
8 properties
AgentIn
object
8 properties
RestrictedQueueIn
object
1 property 1 required
ClientPermissionsIn
object
5 properties
SecretOut
object
1 property
SecretIn
object
3 properties 1 required
ProvisionLogsIn
object
3 properties 2 required
LogGetItem
object
2 properties 2 required
LogGet
object
2 properties
LogPost
object
4 properties 4 required

Specification

The full machine-readable OpenAPI contract behind this narrative.

Source

canonical-testflinger-api-openapi.json Raw ↑

Other APIs Canonical publishes across the network.

Snap Store API
AE Profile APIs.io
Charmhub API
AE Profile APIs.io
snapd REST API
AE Profile APIs.io
MAAS API
AE Profile APIs.io
Juju Client / Controller API
AE Profile APIs.io
Launchpad Web Services API
AE Profile APIs.io
Ubuntu Pro Client API
AE Profile APIs.io
Landscape API
AE Profile APIs.io
Canonical Assertions API
AE Profile APIs.io
Canonical Search API
AE Profile APIs.io
Canonical Snaps API
AE Profile APIs.io
LXD REST API
AE Profile APIs.io
#Testing#Hardware#CI
← Back to T APIs
API Details
ID
canonical:testflinger-api
Base URL
https://testflinger.canonical.com
Docs
https://canonical-testflinger.readthedocs-hosted.com/en/latest/
Provider
Canonical
APIs.io →  GitHub →
Explore more
All APIs Providers APIs.io Network
Work with this as data

Every API here is available over the API and to AI agents over MCP. APIs is not yet its own endpoint on the v1 API. Reach this content through network search and the tag graph, or the MCP server below.

Installs https://mcp.apievangelist.com/mcp in Claude, Cursor, VS Code and the rest — one button, every client.

MCP tools for apis
4 tools reach this content
  • search_api_evangelistSearch every content type across the network at once.
  • find_relatedThe shared-tag relevance graph — what else covers this.
  • get_tagEverything one tag labels, across all content types.
  • guide_topicPRO — a curated bundle for a topic: area, guidance, rules, papers, stories, services.
All tools & prompts
Call it yourself
curl for this page
Search the network for this 
curl "https://api.apievangelist.com/v1/search?q=testflinger-api&limit=10"
Everything under a tag 
curl "https://api.apievangelist.com/v1/tags/testflinger-api"

Discovery needs no key. Full bodies and the synthesis endpoints are Pro.

Get an API key

Free tier, no email required. Sign in with whichever identity you already have.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have. Your account

Where this information came from

This is an independent, third-party profile of Testflinger API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.

The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.

Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.

info@apievangelist.com · Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.