Canonical Replicators API

The replicators API from Canonical — 4 operation(s) for replicators.

Documentation GitHub OpenAPI

Operations 10

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 /1.0/replicators List replicators as URLs · Get the replicators #

Ask an LLM

“Which replicators are configured on my LXD cluster?”

“Can I list replicator URLs across every project?”

Tell an agent

List the URLs of my replicators.

List replicator URLs in project {project}.

POST /1.0/replicators Create a replicator · Add a replicator #

Ask an LLM

“How do I set up a new replicator for a project?”

“Can I give a replicator config and a description when creating it?”

Tell an agent

Create replicator {name}.

Add replicator {name} with config {config} in project {project}.

DELETE /1.0/replicators/{name} Delete a replicator · Delete the replicator #

Ask an LLM

“How do I remove a replicator I no longer need?”

“Can I delete a replicator from a specific project?”

Tell an agent destructive · confirm first

Delete this replicator.

Remove the replicator from project {project}.

GET /1.0/replicators/{name} Get a replicator · Get the replicator #

Ask an LLM

“What configuration does a particular replicator have?”

“Where can I read one replicator's settings?”

Tell an agent

Show this replicator's configuration.

Get the replicator details in project {project}.

PATCH /1.0/replicators/{name} Partially update a replicator · Partially update the replicator #

Ask an LLM

“Can I change just the description of a replicator?”

“How do I update one replicator config key without resending everything?”

Tell an agent

Patch the replicator description to {description}.

Merge config keys {config} into the replicator's settings.

POST /1.0/replicators/{name} Rename a replicator · Rename the replicator #

Ask an LLM

“Is it possible to rename an existing replicator?”

“Can I change a replicator's name without recreating it?”

Tell an agent

Rename the replicator to {name}.

Give the replicator in project {project} the new name {name}.

PUT /1.0/replicators/{name} Replace a replicator's configuration · Update the replicator #

Ask an LLM

“How do I overwrite a replicator's full configuration?”

“Will replacing a replicator's config drop keys I omit?”

Tell an agent

Replace the replicator config with {config}.

Overwrite the replicator config {config} and description {description}.

GET /1.0/replicators/{name}/state Get a replicator's current state · Get the replicator state #

Ask an LLM

“Is my replicator currently running, and what did its last run do?”

“What state is a given replicator in?”

Tell an agent

Show the current state of this replicator.

Check the replicator run state in project {project}.

PUT /1.0/replicators/{name}/state Trigger a replicator run or restore · Update the replicator state #

Ask an LLM

“How do I kick off a replicator run on demand?”

“Why does a replicator restore fail when instances are still running?”

Tell an agent

Trigger the replicator with action {action}.

Run a restore from the replicator in project {project} after instances are stopped.

GET /1.0/replicators?recursion=1 List replicators with full details · Get the replicators #

Ask an LLM

“How do I get every replicator with its config in one call?”

“Can I see full replicator objects across all projects?”

Tell an agent

List all replicators as full objects with config.

Get expanded replicators for project {project}.

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-replicators-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:
  contact:
    email: lxd@lists.canonical.com
    name: LXD upstream
    url: https://github.com/canonical/lxd
  description: 'This is the REST API used by all LXD clients.

    Internal endpoints aren''t included in this documentation.


    The LXD API is available over both a local unix+http and remote https API.

    Authentication for local users relies on group membership and access to the unix socket.

    For remote users, the default authentication method is TLS client.'
  license:
    name: AGPL-3.0-only
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  title: LXD external REST Replicators API
  version: '1.0'
tags:
- name: replicators
paths:
  /1.0/replicators:
    get:
      description: Returns a list of replicators (URLs).
      operationId: replicators_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Retrieve replicators from all projects
        example: true
        in: query
        name: all-projects
        schema:
          type: boolean
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of endpoints
                    example: "[\n  \"/1.0/replicators/foo?project=default\",\n  \"/1.0/replicators/bar?project=default\"\n]"
                    items:
                      type: string
                    type: array
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the replicators
      tags:
      - replicators
    post:
      description: Creates a new replicator.
      operationId: replicators_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Add a replicator
      tags:
      - replicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicatorsPost'
        description: Replicator
        required: true
  /1.0/replicators/{name}:
    delete:
      description: Deletes the replicator.
      operationId: replicator_delete
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Delete the replicator
      tags:
      - replicators
    get:
      description: Gets a specific replicator.
      operationId: replicator_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Replicator
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/Replicator'
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the replicator
      tags:
      - replicators
    patch:
      description: Updates a subset of the replicator configuration.
      operationId: replicator_patch
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Partially update the replicator
      tags:
      - replicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicatorPut'
        description: Replicator configuration
        required: true
    post:
      description: Renames the replicator.
      operationId: replicator_post
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Rename the replicator
      tags:
      - replicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicatorPost'
        description: Replicator rename options
        required: true
    put:
      description: Updates the replicator configuration.
      operationId: replicator_put
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EmptySyncResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the replicator
      tags:
      - replicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicatorPut'
        description: Replicator configuration
        required: true
  /1.0/replicators/{name}/state:
    get:
      description: Gets the current state of the replicator.
      operationId: replicator_state_get
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '200':
          description: Replicator state
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    $ref: '#/components/schemas/ReplicatorState'
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the replicator state
      tags:
      - replicators
    put:
      description: 'Triggers a replicator run using the specified action.

        The "restore" action requires all local project instances to be stopped;

        it returns 400 if any instance is running to prevent partial restores.'
      operationId: replicator_state_put
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      responses:
        '202':
          $ref: '#/components/responses/Operation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update the replicator state
      tags:
      - replicators
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplicatorStatePut'
        description: Replicator state
        required: true
  /1.0/replicators?recursion=1:
    get:
      description: Returns a list of replicators (structs).
      operationId: replicators_get_recursion1
      parameters:
      - description: Project name
        example: default
        in: query
        name: project
        schema:
          type: string
      - description: Retrieve replicators from all projects
        example: true
        in: query
        name: all-projects
        schema:
          type: boolean
      responses:
        '200':
          description: API endpoints
          content:
            application/json:
              schema:
                description: Sync response
                properties:
                  metadata:
                    description: List of replicators
                    items:
                      $ref: '#/components/schemas/Replicator'
                    type: array
                  status:
                    description: Status description
                    example: Success
                    type: string
                  status_code:
                    description: Status code
                    example: 200
                    type: integer
                  type:
                    description: Response type
                    example: sync
                    type: string
                type: object
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get the replicators
      tags:
      - replicators
components:
  schemas:
    Operation:
      description: Operation represents a LXD background operation
      properties:
        child_count:
          description: 'Number of child operations.


            API extension: operation_child_count'
          example: 2
          format: int64
          type: integer
          x-go-name: ChildCount
        class:
          description: Type of operation (task, token or websocket)
          example: websocket
          type: string
          x-go-name: Class
        created_at:
          description: Operation creation time
          example: '2021-03-23T17:38:37.753398689-04:00'
          format: date-time
          type: string
          x-go-name: CreatedAt
        description:
          description: Description of the operation
          example: Executing command
          type: string
          x-go-name: Description
        err:
          description: Operation error message
          example: Some error message
          type: string
          x-go-name: Err
        err_code:
          description: 'Operation error code


            API extension: bulk_operations'
          example: 404
          format: int64
          type: integer
          x-go-name: ErrCode
        id:
          description: UUID of the operation
          example: 6916c8a6-9b7d-4abd-90b3-aedfec7ec7da
          type: string
          x-go-name: ID
        location:
          description: 'Which cluster member this record was found on


            API extension: operation_location'
          example: lxd01
          type: string
          x-go-name: Location
        may_cancel:
          description: Whether the operation can be canceled
          example: false
          type: boolean
          x-go-name: MayCancel
        metadata:
          additionalProperties: {}
          description: Operation specific metadata
          example:
            command:
            - bash
            environment:
              HOME: /root
              LANG: C.UTF-8
              PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
              TERM: xterm
              USER: root
            fds:
              '0': da3046cf02c0116febf4ef3fe4eaecdf308e720c05e5a9c730ce1a6f15417f66
              '1': 05896879d8692607bd6e4a09475667da3b5f6714418ab0ee0e5720b4c57f754b
            interactive: true
          type: object
          x-go-name: Metadata
        requestor:
          $ref: '#/components/schemas/OperationRequestor'
        resources:
          additionalProperties:
            items:
              type: string
            type: array
          description: Affected resources
          example:
            instances:
            - /1.0/instances/foo
            - /1.0/instances/bar
          type: object
          x-go-name: Resources
        status:
          description: Status name
          example: Running
          type: string
          x-go-name: Status
        status_code:
          $ref: '#/components/schemas/StatusCode'
        updated_at:
          description: Operation last change
          example: '2021-03-23T17:38:37.753398689-04:00'
          format: date-time
          type: string
          x-go-name: UpdatedAt
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    Replicator:
      properties:
        access_entitlements:
          description: AccessEntitlements represents the entitlements that are granted to the requesting user on the attached entity.
          example:
          - can_view
          - can_edit
          items:
            type: string
          type: array
          x-go-name: AccessEntitlements
        config:
          additionalProperties:
            type: string
          description: Replicator configuration map (refer to doc/reference/replicator_config.md).
          example:
            schedule: '@daily'
          type: object
          x-go-name: Config
        description:
          description: Description of the replicator.
          example: Backup LXD cluster
          type: string
          x-go-name: Description
        last_run_at:
          description: Timestamp when the replicator job was last run.
          example: '2021-03-23T17:38:37.753398689-04:00'
          format: date-time
          type: string
          x-go-name: LastRunAt
        last_run_status:
          description: Status of the last replicator run (Pending, Completed, or Failed).
          example: Completed
          type: string
          x-go-name: LastRunStatus
        name:
          description: Name of the replicator.
          example: lxd02
          type: string
          x-go-name: Name
        project:
          description: Source project for replication.
          example: default
          type: string
          x-go-name: Project
      title: Replicator represents high-level information about a replicator.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ReplicatorsPost:
      properties:
        config:
          additionalProperties:
            type: string
          description: Replicator configuration map (refer to doc/reference/replicator_config.md).
          example:
            schedule: '@daily'
          type: object
          x-go-name: Config
        description:
          description: Description of the replicator.
          example: Backup cluster
          type: string
          x-go-name: Description
        name:
          description: Name of the replicator.
          example: backup-lxd02
          type: string
          x-go-name: Name
      title: ReplicatorsPost represents the fields available for a new replicator.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ReplicatorStatePut:
      properties:
        action:
          description: Action to perform on the replicator (start, restore).
          example: start
          type: string
          x-go-name: Action
      title: ReplicatorStatePut represents the fields available to change the state of a replicator.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    StatusCode:
      format: int64
      title: StatusCode represents a valid LXD operation and container status.
      type: integer
      x-go-package: github.com/canonical/lxd/shared/api
    ReplicatorPut:
      properties:
        config:
          additionalProperties:
            type: string
          description: Replicator configuration map (refer to doc/reference/replicator_config.md).
          example:
            schedule: '@daily'
          type: object
          x-go-name: Config
        description:
          description: Description of the replicator.
          example: Backup cluster
          type: string
          x-go-name: Description
      title: ReplicatorPut represents the modifiable fields of a replicator.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ReplicatorPost:
      properties:
        name:
          description: New name of the replicator.
          example: my-replicator-renamed
          type: string
          x-go-name: Name
      title: ReplicatorPost represents the fields for renaming a replicator.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    OperationRequestor:
      description: 'API extension: operation_requestor.'
      properties:
        address:
          description: Address is the origin address of the request.
          example: 10.0.2.15
          type: string
          x-go-name: Address
        protocol:
          description: Protocol represents the method used to authenticate the requestor.
          example: oidc
          type: string
          x-go-name: Protocol
        username:
          description: Username is the username of the requestor. This is the identifier of the identity, or the username if using the unix socket.
          example: jane.doe@example.com
          type: string
          x-go-name: Username
      title: OperationRequestor represents the initial requestor of an operation
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
    ReplicatorState:
      properties:
        status:
          description: Status of the replicator job.
          example: Pending
          type: string
          x-go-name: Status
      title: ReplicatorState represents the state of a replicator job.
      type: object
      x-go-package: github.com/canonical/lxd/shared/api
  responses:
    Operation:
      description: Operation
      content:
        application/json:
          schema:
            properties:
              metadata:
                $ref: '#/components/schemas/Operation'
              operation:
                example: /1.0/operations/66e83638-9dd7-4a26-aef2-5462814869a1
                type: string
                x-go-name: Operation
              status:
                example: Operation created
                type: string
                x-go-name: Status
              status_code:
                example: 100
                format: int64
                type: integer
                x-go-name: StatusCode
              type:
                example: async
                type: string
                x-go-name: Type
            type: object
    EmptySyncResponse:
      description: Empty sync response
      content:
        application/json:
          schema:
            properties:
              status:
                example: Success
                type: string
                x-go-name: Status
              status_code:
                example: 200
                format: int64
                type: integer
                x-go-name: StatusCode
              type:
                example: sync
                type: string
                x-go-name: Type
            type: object
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            properties:
              error:
                example: bad request
                type: string
                x-go-name: Error
              error_code:
                example: 400
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            properties:
              error:
                example: not authorized
                type: string
                x-go-name: Error
              error_code:
                example: 403
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            properties:
              error:
                example: internal server error
                type: string
                x-go-name: Error
              error_code:
                example: 500
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            properties:
              error:
                example: precondition failed
                type: string
                x-go-name: Error
              error_code:
                example: 412
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            properties:
              error:
                example: not found
                type: string
                x-go-name: Error
              error_code:
                example: 404
                format: int64
                type: integer
                x-go-name: ErrorCode
              type:
                example: error
                type: string
                x-go-name: Type
            type: object

Canonical Replicators API

Operations 10

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification