Quandela Api - Perceval Job API

openapi: 3.2.0
info:
  title: Quandela Cloud Api - Perceval Job API
  version: v2.8.0-rc4
  description: "\nThis is the official API documentation.\n\n## Overview\n\nThis API provides access to various features and services.  \n\n## Authentication\n\nAll endpoints require an access token generated by the authorization server.\n\nInclude the token in the request headers:\n\n```http\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\nEnsure the token is valid and not expired.\n\n"
  contact:
    name: Support
    url: https://www.quandela.com/about-us/contact-us/
  termsOfService: https://www.quandela.com/legal-terms/
servers:
- url: https://api.cloud.quandela.com/
tags:
- name: Api - Perceval Job
  description: Operations about job - Authenticate by `Cloud Job Token`
paths:
  /api/job:
    post:
      deprecated: true
      description: 'API for job creation.


        Authenticate by `Cloud Job Token`.'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobId'
          description: Success Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: " Bad Request (`InvalidDataError` / `ValidationError`).\n    These occur when the request data is malformed or violates business rules:\n*   `\"Invalid payload, expected a json object\"`\n*   `\"Require platform_id or platform_name\"`\n*   `\"Invalid platform: {platform_id}\"`\n*   `\"Cannot create more than {MAX_WAITING_JOBS} jobs\"` (Global or offer-specific limit)\n*   `\"Max duration must not be zero\"` or `\"Max duration too large, exceeding 864000\"`\n*   `\"Max_duration {value}(s) exceeds the platform limit of {limit}(s)\"`\n*   `\"Invalid max_shots, should be a positive number\"`\n*   `\"Max shots must less than or equal to {shots_limit}\"`\n*   `\"Create job disabled, Platform in {status} status\"` (e.g., decommissioned or retired)\n*   `\"Command '{command}' is not available on platform '{platform_name}'\"`\n*   `\"Quantum Toolbox command '{command}' is not defined\"`\n*   `\"Invalid iterator: must be a non-empty list\"`\n*   `\"process_id is existed and assigned to another user job\"`\n    "
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: "Unauthorized (`AuthenticationError`)\n    Returned when the `Cloud Job Token` is invalid or there are account issues:\n*   `\"Invalid or expired job token\"`\n*   `\"Authentication failed: explorer tokens are not allowed\"` (If specifically restricted)\n*   `\"Invalid user\"` (Returned if the user account associated with the token is deactivated)\n*   **Credit/Time Issues:**\n    *   `\"Not enough credits\"`\n    *   `\"Not enough credits: all remaining credits are reserved by waiting or running jobs\"`\n    *   `\"Not enough {platform_type} time left\"` (For Enterprise offers)\n    "
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: "Permission denied. \n    Returned when the user has a valid token but is restricted from this specific action:\n*   `\"Cannot have more than {MAX_QT_JOBS} running Quantum Toolbox jobs\"`\n*   `\"No permission to use platform {platform_name}\"`\n*   `\"No permission to use algorithm {command}\"`\n*   `\"Platform {name} is locked, please upgrade your offer to use it\"`"
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Platform not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Missing data for required field
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Perceval - Create a job'
      tags:
      - Api - Perceval Job
      operationId: post_api_job
  /api/job/cancel/{job_id}:
    post:
      deprecated: true
      description: 'API for cancel a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Can not cancel job
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'invalid job_id: {job_id}'
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Perceval - Cancel a job'
      tags:
      - Api - Perceval Job
      operationId: post_api_job_cancel_by_job_id
  /api/job/rerun/{job_id}:
    post:
      deprecated: true
      description: 'API for rerun a job by id.

        Require `job:rerun` permission.


        Authenticate by `Cloud Job Token`'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerunJob'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerunJobResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Invalid data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'invalid job_id: {job_id}'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Perceval - Rerun a job'
      tags:
      - Api - Perceval Job
      operationId: post_api_job_rerun_by_job_id
  /api/job/result/{job_id}:
    get:
      deprecated: true
      description: 'API for get result of a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResult'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Invalid job id: {job_id}'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Perceval - Get a job result'
      tags:
      - Api - Perceval Job
      operationId: get_api_job_result_by_job_id
  /api/job/status/{job_id}:
    get:
      deprecated: true
      description: 'API for get status of a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Invalid job id: {job_id}'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Perceval - Get status of a job.'
      tags:
      - Api - Perceval Job
      operationId: get_api_job_status_by_job_id
  /api/jobs:
    post:
      description: 'API for job creation.


        Authenticate by `Cloud Job Token`.'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobId'
          description: Success Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: " Bad Request (`InvalidDataError` / `ValidationError`).\n    These occur when the request data is malformed or violates business rules:\n*   `\"Invalid payload, expected a json object\"`\n*   `\"Require platform_id or platform_name\"`\n*   `\"Invalid platform: {platform_id}\"`\n*   `\"Cannot create more than {MAX_WAITING_JOBS} jobs\"` (Global or offer-specific limit)\n*   `\"Max duration must not be zero\"` or `\"Max duration too large, exceeding 864000\"`\n*   `\"Max_duration {value}(s) exceeds the platform limit of {limit}(s)\"`\n*   `\"Invalid max_shots, should be a positive number\"`\n*   `\"Max shots must less than or equal to {shots_limit}\"`\n*   `\"Create job disabled, Platform in {status} status\"` (e.g., decommissioned or retired)\n*   `\"Command '{command}' is not available on platform '{platform_name}'\"`\n*   `\"Quantum Toolbox command '{command}' is not defined\"`\n*   `\"Invalid iterator: must be a non-empty list\"`\n*   `\"process_id is existed and assigned to another user job\"`\n    "
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: "Unauthorized (`AuthenticationError`)\n    Returned when the `Cloud Job Token` is invalid or there are account issues:\n*   `\"Invalid or expired job token\"`\n*   `\"Authentication failed: explorer tokens are not allowed\"` (If specifically restricted)\n*   `\"Invalid user\"` (Returned if the user account associated with the token is deactivated)\n*   **Credit/Time Issues:**\n    *   `\"Not enough credits\"`\n    *   `\"Not enough credits: all remaining credits are reserved by waiting or running jobs\"`\n    *   `\"Not enough {platform_type} time left\"` (For Enterprise offers)\n    "
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: "Permission denied. \n    Returned when the user has a valid token but is restricted from this specific action:\n*   `\"Cannot have more than {MAX_QT_JOBS} running Quantum Toolbox jobs\"`\n*   `\"No permission to use platform {platform_name}\"`\n*   `\"No permission to use algorithm {command}\"`\n*   `\"Platform {name} is locked, please upgrade your offer to use it\"`"
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Platform not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Missing data for required field
      security:
      - BearerAuth: []
      summary: Perceval - Create a job
      tags:
      - Api - Perceval Job
      operationId: post_api_jobs
  /api/jobs/availability:
    get:
      description: Authenticate by `Cloud Job Token`
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAvailabilityResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
      security:
      - BearerAuth: []
      summary: Perceval - Get Job availability
      tags:
      - Api - Perceval Job
      operationId: get_api_jobs_availability
  /api/jobs/{job_id}/cancel:
    post:
      description: 'API for cancel a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Can not cancel job
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'invalid job_id: {job_id}'
      security:
      - BearerAuth: []
      summary: Perceval - Cancel a job
      tags:
      - Api - Perceval Job
      operationId: post_api_jobs_by_job_id_cancel
  /api/jobs/{job_id}/data:
    get:
      description: Authenticate by `Cloud Job Token`
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobDataResonse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Not found job: {job_id}'
      security:
      - BearerAuth: []
      summary: Perceval - Get Job Data
      tags:
      - Api - Perceval Job
      operationId: get_api_jobs_by_job_id_data
  /api/jobs/{job_id}/rerun:
    post:
      description: 'API for rerun a job by id.

        Require `job:rerun` permission.


        Authenticate by `Cloud Job Token`'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RerunJob'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerunJobResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Invalid data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'invalid job_id: {job_id}'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Perceval - Rerun a job
      tags:
      - Api - Perceval Job
      operationId: post_api_jobs_by_job_id_rerun
  /api/jobs/{job_id}/result:
    get:
      description: 'API for get result of a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResult'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Invalid job id: {job_id}'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      security:
      - BearerAuth: []
      summary: Perceval - Get a job result
      tags:
      - Api - Perceval Job
      operationId: get_api_jobs_by_job_id_result
  /api/jobs/{job_id}/status:
    get:
      description: 'API for get status of a job by id.


        Authenticate by `Cloud Job Token`.


        Permission granted only to the job creator'
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Invalid job id: {job_id}'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Not found
      security:
      - BearerAuth: []
      summary: Perceval - Get status of a job.
      tags:
      - Api - Perceval Job
      operationId: get_api_jobs_by_job_id_status
components:
  schemas:
    GetJobDataResonse:
      additionalProperties: true
      properties:
        command:
          type:
          - string
          - 'null'
        created_date:
          format: date-time
          type:
          - string
          - 'null'
        duration:
          type:
          - integer
          - 'null'
        failure_code:
          type:
          - string
          - 'null'
        job_id:
          type:
          - string
          - 'null'
        job_name:
          type:
          - string
          - 'null'
        payload:
          readOnly: true
        pcvl_version:
          type:
          - string
          - 'null'
        platform_id:
          type:
          - string
          - 'null'
        platform_name:
          type:
          - string
          - 'null'
        process_id:
          type:
          - string
          - 'null'
        rerun_from:
          type:
          - string
          - 'null'
        shots:
          type:
          - integer
          - 'null'
        start_time:
          format: date-time
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        token_id:
          type:
          - integer
          - 'null'
        token_label:
          type:
          - string
          - 'null'
      type: object
    JobStatusResponse:
      additionalProperties: true
      properties:
        creation_datetime:
          description: Job creation time
          type:
          - number
          - 'null'
        duration:
          description: Job duration in seconds
          example: 60
          type:
          - integer
          - 'null'
        failure_code:
          description: Job failure code
          example: error
          type:
          - string
          - 'null'
        last_intermediate_results:
          additionalProperties: {}
          description: Last intermediate results
          example:
            key: value
          type:
          - object
          - 'null'
        msg:
          description: Message
          example: ok
          type:
          - string
          - 'null'
        progress:
          description: Job progress in percentage
          example: 50
          type:
          - number
          - 'null'
        progress_message:
          description: Job progress message
          example: Job is running
          type:
          - string
          - 'null'
        shots:
          description: Shots
          example: 1
          type:
          - integer
          - 'null'
        start_time:
          description: Job start time
          type:
          - number
          - 'null'
        status:
          description: Job status
          example: waiting
          type:
          - string
          - 'null'
        status_message:
          description: Job status message
          example: Job is running
          type:
          - string
          - 'null'
      type: object
    DefaultResponse:
      additionalProperties: true
      properties:
        message:
          example: ok
          type:
          - string
          - 'null'
      type: object
    JobAvailabilityResponse:
      additionalProperties: true
      properties:
        max_concurrent_jobs:
          type:
          - integer
          - 'null'
        max_jobs_in_queue:
          type:
          - integer
          - 'null'
        max_running_qt_jobs:
          type:
          - integer
          - 'null'
        num_concurrent_jobs:
          type:
          - integer
          - 'null'
        num_jobs_in_queue:
          type:
          - integer
          - 'null'
        num_running_qt_jobs:
          type:
          - integer
          - 'null'
      type: object
    JobResult:
      additionalProperties: true
      properties:
        duration:
          description: Duration
          example: 1
          type:
          - integer
          - 'null'
        intermediate_results:
          description: Intermediate Results
          items:
            additionalProperties: {}
            example:
              key: value
            type: object
          type:
          - array
          - 'null'
        job_id:
          description: Job ID
          example: 5f8b9b0c-4b1c-4b1c-9b0c-4b1c4b1c4b1c
          type:
          - string
          - 'null'
        results:
          description: Result as JSON string
          example: '{"key":"value"}'
          type:
          - string
          - 'null'
        results_type:
          description: Job result type
          example: test
          type:
          - string
          - 'null'
        shots:
          description: Number of shots
          example: 100
          type:
          - integer
          - 'null'
      type: object
    JobCreate:
      additionalProperties: true
      properties:
        job_group_name:
          description: Job group name to create
          example: Job Group Name 1
          type:
          - string
          - 'null'
        job_name:
          description: Job name to create
          example: Job Name 1
          type: string
        max_duration:
          description: Max duration of the job in seconds
          example: 60
          type:
          - integer
          - 'null'
        payload:
          additionalProperties: {}
          description: Payload to create job
          example:
            key: value
          type:
          - object
          - 'null'
        pcvl_version:
          description: PCVL version, will be passed in `payload`
          example: 1.0.0
          type:
          - string
          - 'null'
        platform_id:
          description: Platform ID
          example: 05cfb499-1789-41ac-8653-eb78039b76a2
          type:
          - string
          - 'null'
        platform_name:
          description: Platform name use when platform_id is not provided
          example: Platform Name 1
          type:
          - string
          - 'null'
        process_id:
          description: Process ID
          example: 05cfb499-1789-41ac-8653-eb78039b76a2
          type:
          - string
          - 'null'
      required:
      - job_name
      - payload
      type: object
    HTTPError:
      properties:
        detail:
          type: object
        error:
          type: string
      type: object
    RerunJobResponse:
      additionalProperties: true
      properties:
        job_id:
          type:
          - string
          - 'null'
      type: object
    RerunJob:
      additionalProperties: true
      properties:
        job_name:
          description: Job name to rerun
          example: Job Name 1
          type:
          - string
          - 'null'
        payload:
          additionalProperties: {}
          description: Payload to rerun job
          example:
            key: value
          type:
          - object
          - 'null'
        platform_id:
          description: Platform ID
          example: 05cfb499-1789-41ac-8653-eb78039b76a2
          type:
          - string
          - 'null'
      type: object
    JobId:
      additionalProperties: true
      properties:
        job_id:
          description: Job ID of the created job
          example: 05cfb499-1789-41ac-8653-eb78039b76a2
          type:
          - string
          - 'null'
      type: object
    ValidationError:
      properties:
        detail:
          properties:
            <location>:
              properties:
                <field_name>:
                  items:
                    type: string
                  type: array
              type: object
          type: object
        message:
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http