Canonical Agents API

The Agents API from Canonical — 6 operation(s) for agents.

Documentation GitHub OpenAPI

Operations 8

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /v1/agents/data List data for all test agents · Get all agent data #

Ask an LLM

“Which Testflinger agents are registered and what state is each one in?”

“Can I see the queues and location of every agent at once?”

Tell an agent

List the data for every agent.

Show me the current state of all agents on the server.

GET /v1/agents/queues List advertised queues · Get all advertised queues from this server #

Ask an LLM

“Which queues does this server advertise as valid to submit to?”

“What is each advertised queue described as?”

Tell an agent

List all advertised queues with their descriptions.

Show me which queue names the server knows about.

POST /v1/agents/queues Advertise the queues an agent services · Tell testflinger the queue names that are being serviced #

Ask an LLM

“How does an agent tell the server which queues it listens on?”

“Can I publish a description alongside each queue name I advertise?”

Tell an agent

Advertise these queue names and descriptions to the server.

Register the queues this agent services so users can see they are valid.

POST /v1/agents/images Publish known images for a queue · Tell testflinger about known images for a specified queue #

Ask an LLM

“How do I record which provisioning images are available on a queue?”

“Can an agent map image names like core22 to provision data for its queue?”

Tell an agent

Publish this image-name to provision-data mapping for the queue.

Tell the server about the images known on my queue.

GET /v1/agents/images/{queue} Get known images for a queue · Get a dict of known images for a given queue #

Ask an LLM

“Which images can I provision on a particular queue?”

“What provision data is stored for each image on a queue?”

Tell an agent

List the known images for queue {queue}.

Show the provision data for images on queue {queue}.

GET /v1/agents/data/{agent_name} Get one agent's information · Get the information from a specified agent #

Ask an LLM

“What state is a specific agent in right now?”

“Which job is a named agent currently running?”

Tell an agent

Show the information for agent {agent_name}.

Get the current state and queues of agent {agent_name}.

POST /v1/agents/data/{agent_name} Update an agent's reported status · Post information about the agent to the server #

Ask an LLM

“How does an agent report its state and location back to the server?”

“Can an agent post the job it is working on and a comment about its device?”

Tell an agent

Set agent {agent_name} state to {state}.

Report agent {agent_name} at location {location} listening on queues {queues}.

POST /v1/agents/provision_logs/{agent_name} Post an agent's provision log · Post provision logs for the agent to the server #

Ask an LLM

“How do I record whether provisioning succeeded on an agent?”

“Can an agent attach detail to the exit code of a provisioning attempt?”

Tell an agent

Post a provision log for agent {agent_name}: job {job_id} exited with {exit_code}.

Log provisioning result {exit_code} for job {job_id} on agent {agent_name} with detail {detail}.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/canonical:canonical-agents-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

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

OpenAPI Specification

openapi: 3.2.0
info:
  title: Testflinger Agents API
  version: 1.0.0
servers:
- url: https://testflinger.ps7.canonical.com/
tags:
- name: Agents
paths:
  /v1/agents/data:
    get:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOut'
          description: Successful response
      tags:
      - Agents
      summary: Get all agent data
      operationId: getV1AgentsData
      x-operation-id-source: derived
  /v1/agents/queues:
    get:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  device001: Queue for device001
                  some-queue: some other queue
          description: Mapping of queue names and descriptions
      tags:
      - Agents
      summary: Get all advertised queues from this server
      description: 'Returns a dict of queue names and descriptions, ex:

        {

        "some_queue": "A queue for testing",

        "other_queue": "A queue for something else"

        }'
      operationId: getV1AgentsQueues
      x-operation-id-source: derived
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Agents
      summary: Tell testflinger the queue names that are being serviced
      description: 'Some agents may want to advertise some of the queues they listen on so that

        the user can check which queues are valid to use.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueuesIn'
      operationId: postV1AgentsQueues
      x-operation-id-source: derived
  /v1/agents/images:
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Agents
      summary: Tell testflinger about known images for a specified queue
      description: 'images will be stored in a dict of key/value pairs as part of the queues

        collection. That dict will contain image_name:provision_data mappings, ex:

        {

        "some_queue": {

        "core22": "http://cdimage.ubuntu.com/.../core-22.tar.gz",

        "jammy": "http://cdimage.ubuntu.com/.../ubuntu-22.04.tar.gz"

        },

        "other_queue": {

        ...

        }

        }.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImagesIn'
      operationId: postV1AgentsImages
      x-operation-id-source: derived
  /v1/agents/images/{queue}:
    get:
      parameters:
      - in: path
        name: queue
        schema:
          type: string
        required: true
      responses:
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  core22: 'url: http://.../core22.img.xz'
                  server-22.04: 'url: http://.../ubuntu-22.04.img.xz'
          description: Mapping of image names and provision data
      tags:
      - Agents
      summary: Get a dict of known images for a given queue
      operationId: getV1AgentsImagesByQueue
      x-operation-id-source: derived
  /v1/agents/data/{agent_name}:
    get:
      parameters:
      - in: path
        name: agent_name
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentOut'
          description: Successful response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Agents
      summary: Get the information from a specified agent
      description: ':param agent_name:

        String with the name of the agent to retrieve information from.

        :return:

        JSON data with the specified agent information.'
      operationId: getV1AgentsDataByAgentName
      x-operation-id-source: derived
    post:
      parameters:
      - in: path
        name: agent_name
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Agents
      summary: Post information about the agent to the server
      description: 'The json sent to this endpoint may contain data such as the following:

        {

        "state": string, # State the device is in

        "queues": array[string], # Queues the device is listening on

        "location": string, # Location of the device

        "job_id": string, # Job ID the device is running, if any

        "log": array[string], # push and keep only the last 100 lines

        }'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentIn'
      operationId: postV1AgentsDataByAgentName
      x-operation-id-source: derived
  /v1/agents/provision_logs/{agent_name}:
    post:
      parameters:
      - in: path
        name: agent_name
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Agents
      summary: Post provision logs for the agent to the server
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionLogsIn'
      operationId: postV1AgentsProvisionLogsByAgentName
      x-operation-id-source: derived
components:
  schemas:
    ImagesIn:
      type: object
      properties: {}
      additionalProperties: true
    AgentIn:
      type: object
      properties:
        identifier:
          type: string
        job_id:
          type: string
        location:
          type: string
        log:
          type: array
          items:
            type: string
        provision_type:
          type: string
        queues:
          type: array
          items:
            type: string
        state:
          type: string
        comment:
          type: string
      additionalProperties: false
    AgentJob:
      type: object
      properties:
        job_id:
          type: string
        submitted_by:
          type:
          - string
          - 'null'
          default: null
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        job_queue:
          type: string
        job_state:
          type: string
        job_priority:
          type: integer
        tags:
          type: array
          items:
            type: string
      required:
      - job_id
      additionalProperties: false
    HTTPError:
      properties:
        detail:
          type: object
        message:
          type: string
      type: object
    ProvisionLogsIn:
      type: object
      properties:
        job_id:
          type: string
        exit_code:
          type: integer
        detail:
          type: string
      required:
      - exit_code
      - job_id
      additionalProperties: false
    QueuesIn:
      type: object
      properties: {}
      additionalProperties: true
    ValidationError:
      properties:
        detail:
          type: object
          properties:
            <location>:
              type: object
              properties:
                <field_name>:
                  type: array
                  items:
                    type: string
        message:
          type: string
      type: object
    AgentOut:
      type: object
      properties:
        name:
          type: string
        job_id:
          type: string
        state:
          type: string
        queues:
          type: array
          items:
            type: string
        location:
          type: string
        provision_type:
          type: string
        comment:
          type: string
        restricted_to:
          type: object
          additionalProperties: {}
        job:
          anyOf:
          - type:
            - object
            - 'null'
          - $ref: '#/components/schemas/AgentJob'
      required:
      - name
      additionalProperties: false

Canonical Agents API

Operations 8

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification