Quandela Api - Perceval Job Token API

openapi: 3.2.0
info:
  title: Quandela Cloud Api - Perceval Job Token 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 Token
  description: Operations about job token - Authenticate by `Cloud Job Token`
paths:
  /api/auth/token/delete:
    post:
      deprecated: true
      description: 'API used to delete token.

        Authenticate by `Cloud Job Token`'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTokensByKey'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Tokens not found | Can't delete the current active token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: You do not have permission to delete this token
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Delete tokens by keys'
      tags:
      - Api - Perceval Job Token
      operationId: post_api_auth_token_delete
  /api/auth/tokens/delete:
    post:
      deprecated: true
      description: 'API used to delete token.

        Authenticate by `Cloud Job Token`'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTokensByKey'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Tokens not found | Can't delete the current active token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: You do not have permission to delete this token
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: 'DEPRECATED: Delete tokens by keys'
      tags:
      - Api - Perceval Job Token
      operationId: post_api_auth_tokens_delete
  /api/tokens:
    get:
      description: 'API used to get list of job tokens for current user or specified user.


        If user_id is not provided, defaults to the current user''s tokens.


        Require `token:view` permission.


        Authenticate by `Cloud Job Token`'
      parameters:
      - description: Default value = 1000 if null
        in: query
        name: limit
        required: false
        schema:
          example: 1000
          maximum: 10000
          minimum: 1
          type:
          - integer
          - 'null'
      - description: Default value = 0 if null
        in: query
        name: offset
        required: false
        schema:
          example: 0
          type:
          - integer
          - 'null'
      - description: 'Optional: User ID to filter tokens. If not provided, defaults to current user'
        in: query
        name: user_id
        required: false
        schema:
          example: null
          type:
          - integer
          - 'null'
      - description: 'Optional: Whether to include expired tokens in the results. Default is true to include expired tokens, set to false to exclude them'
        in: query
        name: include_expired
        required: false
        schema:
          type:
          - boolean
          - 'null'
      - description: 'Optional: Whether to include revoked tokens in the results. Default is true to include revoked tokens, set to false to exclude them'
        in: query
        name: include_revoked
        required: false
        schema:
          type:
          - boolean
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TokensListUnitResponse'
                type: array
          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
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Get list of tokens
      tags:
      - Api - Perceval Job Token
      operationId: get_api_tokens
    post:
      description: 'API used to generate job token for current or another user.


        Authenticate by `Cloud Job Token`'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenGenerateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenGenerateResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Unknown user, Can''t assign priority higher than user priority,         Label already exists: {label}'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Generate a job token
      tags:
      - Api - Perceval Job Token
      operationId: post_api_tokens
  /api/tokens/delete:
    post:
      description: 'API used to delete token.

        Authenticate by `Cloud Job Token`'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTokensByKey'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Tokens not found | Can't delete the current active token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: You do not have permission to delete this token
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Delete tokens by keys
      tags:
      - Api - Perceval Job Token
      operationId: post_api_tokens_delete
  /api/tokens/delete-by-ids:
    post:
      description: 'API used to delete token.


        Require `token:delete` permission.


        Authenticate by `Cloud Job Token`'
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTokenIds'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Tokens not found or Can't delete the current active token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Delete tokens by ids
      tags:
      - Api - Perceval Job Token
      operationId: post_api_tokens_delete_by_ids
  /api/tokens/reopen:
    post:
      description: 'The API was used to reopen a previously revoked token by key.


        Require `token:edit` permission.


        Authenticate by `Cloud Job Token`.'
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Invalid token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Reopen a job token
      tags:
      - Api - Perceval Job Token
      operationId: post_api_tokens_reopen
  /api/tokens/revoke:
    post:
      description: 'API used to revoke token by key.


        Require `token:edit` permission.


        Authenticate by `Cloud Job Token`.'
      parameters: []
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeToken'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Invalid token
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Revoke a job token
      tags:
      - Api - Perceval Job Token
      operationId: post_api_tokens_revoke
  /api/tokens/usage/report:
    get:
      description: 'API used to get the usage of given job tokens.


        Require `token:view` permission


        Authenticate by `Cloud Job Token`.'
      parameters:
      - description: 'List of token IDs to query usage for. If empty, returns all tokens of the authenticated user.

          Accept: `[1,2,3]` , `1,2,3` or null'
        explode: true
        in: query
        name: token_ids
        required: false
        schema:
          example:
          - 1
          - 2
          - 3
          items:
            type: integer
          type:
          - array
          - 'null'
        style: form
      - description: Start time for usage query (with timezone). Format YYYY-MM-DDTHH:MM:SS+xx:yy
        in: query
        name: start_time
        required: false
        schema:
          example: '2026-04-07T17:00:00+07:00'
          format: date-time
          type:
          - string
          - 'null'
      - description: End time for usage query (with timezone). Format YYYY-MM-DDTHH:MM:SS+xx:yy
        in: query
        name: end_time
        required: false
        schema:
          example: '2026-04-07T17:00:00+07:00'
          format: date-time
          type:
          - string
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TokenUsageResponse'
                type: array
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Token not found or invalid
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Authentication error
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: Permission denied
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Get usage statistics of job tokens.
      tags:
      - Api - Perceval Job Token
      operationId: get_api_tokens_usage_report
  /api/tokens/{token_id}:
    get:
      description: 'API used to get token detail.


        Require `token:view` permission


        Authenticate by `Cloud Job Token`'
      parameters:
      - in: path
        name: token_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
          description: 'Invalid token: {token_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: Get a job token
      tags:
      - Api - Perceval Job Token
      operationId: get_api_tokens_by_token_id
    put:
      description: 'Update label and priority of token from token id.


        Require `token:edit` permission


        Authenticate by `Cloud Job Token`.'
      parameters:
      - in: path
        name: token_id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenUpdate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultResponse'
          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: Not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: Validation error
      security:
      - BearerAuth: []
      summary: Update a job token
      tags:
      - Api - Perceval Job Token
      operationId: put_api_tokens_by_token_id
components:
  schemas:
    RevokeToken:
      additionalProperties: true
      properties:
        token:
          example: _T_eyJhbGciOiJIUzUxMiIsImlhdCI6MTY3MTg0ODU0NSwiZXhwIjoxNjc0NDQwNT
          type: string
      required:
      - token
      type: object
    DefaultResponse:
      additionalProperties: true
      properties:
        message:
          example: ok
          type:
          - string
          - 'null'
      type: object
    TokenUsageResponse:
      additionalProperties: true
      properties:
        token_id:
          description: ID of the token
          type:
          - integer
          - 'null'
        total_jobs:
          description: Total number of jobs executed across all platforms
          type:
          - integer
          - 'null'
        usage:
          description: List of usage statistics grouped by platform
          items:
            $ref: '#/components/schemas/TokenUsageUnit'
          type:
          - array
          - 'null'
      type: object
    TokenGenerateResponse:
      additionalProperties: true
      properties:
        duration:
          description: Duration of access token in seconds
          example: 3600
          type:
          - integer
          - 'null'
        token:
          description: Access token for authentication
          example: _T_eyJhbGciOiJIUzUxMiIsImlhdCI6MTY3MTg0ODU0NSwiZXhwIjoxNjc0NDQwNTQ1fQ.eyJpZCI6NDl9.M4UuwDLw2BrATJPpzoAvFw7Z84BttKaWGPHgSmMO9xGi3E84q4JRzwze5PcNrAZXaNWo1tCshWTQxYBN1Sxorw
          type:
          - string
          - 'null'
        token_id:
          type:
          - integer
          - 'null'
      type: object
    TokensListUnitResponse:
      additionalProperties: true
      properties:
        count:
          type:
          - integer
          - 'null'
        created_date:
          format: date-time
          type:
          - string
          - 'null'
        expiration_date:
          format: date-time
          type:
          - string
          - 'null'
        id:
          type:
          - integer
          - 'null'
        is_revoked:
          type:
          - boolean
          - 'null'
        key:
          type:
          - string
          - 'null'
        label:
          type:
          - string
          - 'null'
        last_used_time:
          format: date-time
          type:
          - string
          - 'null'
        priority:
          type:
          - integer
          - 'null'
        user_id:
          type:
          - integer
          - 'null'
      type: object
    TokenUsageUnit:
      additionalProperties: true
      properties:
        credits:
          description: Total credits consumed on this platform
          type:
          - number
          - 'null'
        duration_seconds:
          description: Total execution time on this platform, measured in seconds
          type:
          - integer
          - 'null'
        free_credits:
          description: Total free credits consumed on this platform
          type:
          - number
          - 'null'
        nb_jobs:
          description: Number of jobs executed on this platform
          type:
          - integer
          - 'null'
        platform_name:
          description: Platform identifier where the token was used (e.g. qpu:belenos, sim:gpu)
          type:
          - string
          - 'null'
      type: object
    Token:
      additionalProperties: true
      properties:
        company_id:
          description: ID of the company that the user who owns the API key belongs to
          example: 1
          type:
          - integer
          - 'null'
        company_name:
          description: Company name
          example: Quandela
          type:
          - string
          - 'null'
        count:
          description: Number of times the API key was used
          example: 1
          type:
          - integer
          - 'null'
        created_date:
          description: Date when the API key was created
          format: date-time
          type:
          - string
          - 'null'
        email:
          description: Email of the user who owns the API key
          example: admin@quande.la
          format: email
          type:
          - string
          - 'null'
        expiration_date:
          description: Date when the API key will expire
          format: date-time
          type:
          - string
          - 'null'
        id:
          description: ID of the API key
          example: 1
          type:
          - integer
          - 'null'
        is_apikey:
          description: Whether the API key is an API key or not
          example: true
          type:
          - boolean
          - 'null'
        is_explorer_token:
          type:
          - boolean
          - 'null'
        label:
          description: Label of the API key
          example: None
          type:
          - string
          - 'null'
        last_used_duration:
          description: Last use duration of the token
          example: 1
          type:
          - integer
          - 'null'
        last_used_time:
          description: Date when the API key was last used
          format: date-time
          type:
          - string
          - 'null'
        priority:
          description: Priority of the API key
          example: 1
          type:
          - integer
          - 'null'
        token:
          description: API key
          example: _T_eyJhbGciOiJIUzUxMiIsImlhdCI6MTY3MTg0ODU0NSwiZXhwIjoxNjc0NDQwNTQ1fQ.eyJpZCI6NDl9.M4UuwDLw2BrATJPpzoAvFw7Z84BttKaWGPHgSmMO9xGi3E84q4JRzwze5PcNrAZXaNWo1tCshWTQxYBN1Sxorw
          type:
          - string
          - 'null'
        user_id:
          description: ID of the user who owns the API key
          example: 1
          type:
          - integer
          - 'null'
        user_priority:
          description: Priority of the user who owns the API key
          example: 1
          type:
          - integer
          - 'null'
        valid:
          description: Whether the API key is valid or not
          example: true
          type:
          - boolean
          - 'null'
      type: object
    TokenGenerateRequest:
      additionalProperties: true
      properties:
        duration:
          default: 86400
          description: Duration of access token in seconds
          example: 86400
          type:
          - integer
          - 'null'
        is_explorer_token:
          type:
          - boolean
          - 'null'
        label:
          default: unknown
          description: Label of the token
          example: unknown
          type:
          - string
          - 'null'
        priority:
          default: 0
          description: Number presenting the priority, must be lower than the user's priority, default is 0
          example: 1
          type:
          - integer
          - 'null'
        user_id:
          description: ID of the User, default is id of current user
          example: 1
          type:
          - integer
          - 'null'
      type: object
    ListTokenIds:
      additionalProperties: true
      properties:
        token_ids:
          items:
            type: integer
          type: array
      required:
      - token_ids
      type: object
    HTTPError:
      properties:
        detail:
          type: object
        error:
          type: string
      type: object
    DeleteTokensByKey:
      additionalProperties: true
      properties:
        tokens:
          items:
            type: string
          type:
          - array
          - '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
    TokenUpdate:
      additionalProperties: true
      properties:
        label:
          default: unknown
          description: Label of the token
          example: unknown
          type:
          - string
          - 'null'
        priority:
          description: Number presenting the priority, must be lower than the user's priority, default is 0
          example: 1
          type:
          - integer
          - 'null'
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http