Canonical

Canonical Job API

The Job API from Canonical — 7 operation(s) for job.

Documentation GitHub OpenAPI

Operations 9

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/job/{job_id} Request the json job definition for a specified job, even if it has #

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/job/{job_id}/position Return the position of the specified jobid in the queue #

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 #

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-job-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 Job API
  version: 1.0.0
servers:
- url: https://testflinger.ps7.canonical.com/
tags:
- name: Job
paths:
  /v1/job:
    get:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: Successful response
        '204':
          content:
            application/json:
              schema:
                type: object
                properties: {}
          description: No job found
      tags:
      - Job
      summary: Request a job to run from supported queues
      description: 'The agent must identify itself via the ``agent_name`` cookie. One or more

        ``queue`` query parameters must be supplied; the server returns the first

        available job across those queues.


        Any secrets referenced in the job are resolved against the secrets store

        at this point. Secrets that are inaccessible (store unreachable, path not

        found, or insufficient permissions) are silently resolved to an empty

        string rather than causing the request to fail. Agents must therefore

        handle the possibility of empty secret values.'
      operationId: getV1Job
      x-operation-id-source: derived
    post:
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobId'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Job
      summary: Add a job to the queue
      description: 'The ``job_queue`` field in the submitted JSON determines which queue the

        job is placed on. All other fields are passed through to the agent

        unchanged.


        Returns HTTP 422 if the job references secrets that are inaccessible at

        submission time (e.g. the secrets store is unreachable or the secret path

        does not exist for the submitting client).'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Job'
      operationId: postV1Job
      x-operation-id-source: derived
  /v1/job/search:
    get:
      parameters:
      - in: query
        name: tags
        description: List of tags to search for
        schema:
          type: array
          items:
            type: string
        required: false
        explode: true
        style: form
      - in: query
        name: match
        description: Match mode - 'all' or 'any' (default 'any')
        schema:
          type: string
          enum:
          - any
          - all
        required: false
      - in: query
        name: state
        description: List of job states to include
        schema:
          type: array
          items:
            type: string
            enum:
            - setup
            - provision
            - firmware_update
            - test
            - allocate
            - allocated
            - reserve
            - cleanup
            - cancelled
            - completed
            - active
        required: false
        explode: true
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobSearchResponse'
          description: Successful response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      tags:
      - Job
      summary: Search for jobs by tags
      operationId: getV1JobSearch
      x-operation-id-source: derived
  /v1/job/{job_id}:
    get:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobOut'
          description: Successful response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Job
      summary: Request the json job definition for a specified job, even if it has
      description: 'already run.


        :param job_id:

        UUID as a string for the job

        :return:

        JSON data for the job or error string and http error'
      operationId: getV1JobByJobId
      x-operation-id-source: derived
  /v1/job/{job_id}/action:
    post:
      parameters:
      - in: path
        name: job_id
        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:
      - Job
      summary: Take action on the job status for a specified job ID
      description: ':param job_id:

        UUID as a string for the job'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionIn'
      operationId: postV1JobByJobIdAction
      x-operation-id-source: derived
  /v1/job/{job_id}/events:
    post:
      parameters:
      - in: path
        name: job_id
        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:
      - Job
      summary: Post status updates from the agent to the server to be forwarded
      description: 'to the server-configured webhook url.


        The json sent to this endpoint may contain data such as the following:

        {

        "agent_id": "",

        "job_queue": "",

        "job_status_webhook": "",

        "events": [

        {

        "event_name": "",

        "timestamp": "",

        "detail": ""

        },

        ...

        ]

        }


        :param job_id: UUID as a string for the job

        :param json_data: JSON data containing the status updates and webhook URL'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusUpdate'
      operationId: postV1JobByJobIdEvents
      x-operation-id-source: derived
  /v1/job/{job_id}/position:
    get:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Job
      summary: Return the position of the specified jobid in the queue
      operationId: getV1JobByJobIdPosition
      x-operation-id-source: derived
  /v1/job/{job_id}/attachments:
    get:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Job
      summary: Return the attachments bundle for a specified job_id
      description: ':param job_id:

        UUID as a string for the job

        :return:

        send_file stream of attachment tarball to download'
      operationId: getV1JobByJobIdAttachments
      x-operation-id-source: derived
    post:
      parameters:
      - in: path
        name: job_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      tags:
      - Job
      summary: Post attachment bundle for a specified job_id
      description: ':param job_id:

        UUID as a string for the job'
      operationId: postV1JobByJobIdAttachments
      x-operation-id-source: derived
components:
  schemas:
    TestData:
      type: object
      properties:
        test_cmds:
          type: string
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        test_username:
          type: string
        test_password:
          type: string
        secrets:
          type: object
          additionalProperties:
            type: string
            pattern: ^[a-zA-Z0-9_/-]+$
      additionalProperties: false
    ProvisionData:
      type: object
      properties: {}
      additionalProperties: false
    JobId:
      type: object
      properties:
        job_id:
          type: string
      required:
      - job_id
      additionalProperties: false
    Attachment:
      type: object
      properties:
        agent:
          type: string
        device:
          type: string
      required:
      - agent
      additionalProperties: false
    JobSearchResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
      required:
      - jobs
      additionalProperties: false
    ReserveData:
      type: object
      properties:
        ssh_keys:
          type: array
          items:
            type: string
            pattern: ^(lp|gh):(\S+)$
        timeout: {}
      additionalProperties: false
    JobEvent:
      type: object
      properties:
        event_name:
          type: string
        timestamp:
          type: string
        detail:
          type: string
      required:
      - event_name
      - timestamp
      additionalProperties: false
    Job:
      type: object
      properties:
        job_id:
          type: string
        parent_job_id:
          type: string
        name:
          type: string
        tags:
          type: array
          items:
            type: string
        job_queue:
          type: string
          minLength: 1
        global_timeout:
          type: integer
        output_timeout:
          type: integer
        allocation_timeout:
          type: integer
        provision_data:
          anyOf:
          - type:
            - object
            - 'null'
          - $ref: '#/components/schemas/ProvisionData'
        firmware_update_data:
          type: object
          additionalProperties: {}
        test_data:
          $ref: '#/components/schemas/TestData'
        allocate_data:
          type: object
          additionalProperties: {}
        reserve_data:
          $ref: '#/components/schemas/ReserveData'
        job_status_webhook:
          type: string
        job_priority:
          type: integer
        exclude_agents:
          type: array
          items:
            type: string
        debug:
          type: boolean
      required:
      - job_queue
      additionalProperties: false
    JobOut:
      type: object
      properties:
        job_id:
          type: string
        parent_job_id:
          type: string
        name:
          type: string
        tags:
          type: array
          items:
            type: string
        job_queue:
          type: string
          minLength: 1
        global_timeout:
          type: integer
        output_timeout:
          type: integer
        allocation_timeout:
          type: integer
        provision_data:
          anyOf:
          - type:
            - object
            - 'null'
          - $ref: '#/components/schemas/ProvisionData'
        firmware_update_data:
          type: object
          additionalProperties: {}
        test_data:
          $ref: '#/components/schemas/TestData'
        allocate_data:
          type: object
          additionalProperties: {}
        reserve_data:
          $ref: '#/components/schemas/ReserveData'
        job_status_webhook:
          type: string
        job_priority:
          type: integer
        exclude_agents:
          type: array
          items:
            type: string
        debug:
          type: boolean
        submitted_by:
          type:
          - string
          - 'null'
          default: null
      required:
      - job_queue
      additionalProperties: false
    HTTPError:
      properties:
        detail:
          type: object
        message:
          type: string
      type: object
    ActionIn:
      type: object
      properties:
        action:
          type: string
          enum:
          - cancel
      required:
      - action
      additionalProperties: false
    StatusUpdate:
      type: object
      properties:
        agent_id:
          type: string
        job_queue:
          type: string
        job_status_webhook:
          type: string
          format: url
        events:
          type: array
          items:
            $ref: '#/components/schemas/JobEvent'
      required:
      - job_status_webhook
      additionalProperties: false
    ValidationError:
      properties:
        detail:
          type: object
          properties:
            <location>:
              type: object
              properties:
                <field_name>:
                  type: array
                  items:
                    type: string
        message:
          type: string
      type: object