> ## Documentation Index > Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Transpile Circuits > Submit one or more circuits for transpilation on a target backend. Use this tool when the caller needs backend-aware transpilation before execution, comparison, or further circuit analysis. The request accepts existing ``circuit_ids`` or inline ``circuits_qasm``. When QASM is supplied, the endpoint creates persistent circuit records associated with the experiment before submitting the transpilation job. When to Use: - Call this after ``list_qpus_and_simulators`` returns a valid ``device_id`` for the target backend. - Call this when the user wants transpiled circuit IDs, not immediate final circuits inline. Constraints: - Provide at least one of ``circuit_ids`` or ``circuits_qasm``. - ``device_id`` should be passed exactly as returned by ``list_qpus_and_simulators``. - The response is a lightweight context wrapper; use ``get_job_results_and_status`` to retrieve terminal outputs such as ``transpiled_circuit_ids``. Notes: - ``transpilation_options`` is forwarded to the backend-facing transpilation path and may contain device-specific settings. - Circuits created from inline QASM are stored under the experiment so they remain visible in Haiqu UI flows and later MCP calls. - There is no practical size limit on ``circuits_qasm``. For circuits already stored, prefer ``circuit_ids`` so large QASM payloads are sent at most once; never downscale an instance because its QASM looks large. Args: user: Authenticated user resolved from the API key. data: Transpilation payload containing the experiment scope, target backend, existing circuit IDs and/or inline QASM circuits, and optional transpilation settings. db: Active database session. Returns: A lightweight context wrapper summarizing the created transpilation job and the next polling step. Raises: HTTPException: Raised with ``400`` when neither ``circuit_ids`` nor ``circuits_qasm`` is provided, ``402`` when the caller cannot submit billable jobs, or ``404`` when the experiment is not available to the caller. ## OpenAPI ````yaml https://api.haiqu.ai/openapi.json post /ai/transpile_circuits openapi: 3.1.0 info: title: Haiqu API summary: Haiqu RESTful API service. description: Cloud service providing the access to Haiqu cloud runtime contact: name: Haiqu Inc. url: https://haiqu.ai/ email: info@haiqu.ai version: 1.3.0 servers: [] security: [] paths: /ai/transpile_circuits: post: summary: Transpile Circuits description: >- Submit one or more circuits for transpilation on a target backend. Use this tool when the caller needs backend-aware transpilation before execution, comparison, or further circuit analysis. The request accepts existing ``circuit_ids`` or inline ``circuits_qasm``. When QASM is supplied, the endpoint creates persistent circuit records associated with the experiment before submitting the transpilation job. When to Use: - Call this after ``list_qpus_and_simulators`` returns a valid ``device_id`` for the target backend. - Call this when the user wants transpiled circuit IDs, not immediate final circuits inline. Constraints: - Provide at least one of ``circuit_ids`` or ``circuits_qasm``. - ``device_id`` should be passed exactly as returned by ``list_qpus_and_simulators``. - The response is a lightweight context wrapper; use ``get_job_results_and_status`` to retrieve terminal outputs such as ``transpiled_circuit_ids``. Notes: - ``transpilation_options`` is forwarded to the backend-facing transpilation path and may contain device-specific settings. - Circuits created from inline QASM are stored under the experiment so they remain visible in Haiqu UI flows and later MCP calls. - There is no practical size limit on ``circuits_qasm``. For circuits already stored, prefer ``circuit_ids`` so large QASM payloads are sent at most once; never downscale an instance because its QASM looks large. Args: user: Authenticated user resolved from the API key. data: Transpilation payload containing the experiment scope, target backend, existing circuit IDs and/or inline QASM circuits, and optional transpilation settings. db: Active database session. Returns: A lightweight context wrapper summarizing the created transpilation job and the next polling step. Raises: HTTPException: Raised with ``400`` when neither ``circuit_ids`` nor ``circuits_qasm`` is provided, ``402`` when the caller cannot submit billable jobs, or ``404`` when the experiment is not available to the caller. operationId: transpile_circuits requestBody: content: application/json: schema: $ref: '#/components/schemas/ContextSubmitTranspilationModel' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContextTranspilationJobModel' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyQuery: [] - APIKeyHeader: [] components: schemas: ContextSubmitTranspilationModel: properties: experiment_id: type: string title: Experiment Id circuit_ids: items: {} type: array title: Circuit Ids default: [] device_id: type: string title: Device Id transpilation_options: anyOf: - additionalProperties: true type: object - type: 'null' title: Transpilation Options description: >- Backend-specific transpilation options. For example: `{'optimization_level': 2}`. default: {} name: anyOf: - type: string - type: 'null' title: Name default: '' description: anyOf: - type: string - type: 'null' title: Description default: '' circuits_qasm: anyOf: - items: type: string type: array - type: 'null' title: Circuits Qasm description: >- List of quantum circuits in QASM 2.0 or 3.0 format. Use either this field or `circuit_ids` field to specify the existing circuits IDs to transpile. type: object required: - experiment_id - device_id title: ContextSubmitTranspilationModel description: >- Define payload for MCP transpilation submissions. This model extends :class:`haiqu.sdk.schemas.SubmitTranspilationModel` with optional inline QASM input so agents can submit and transpile circuits in one operation. Attributes: experiment_id: Parent experiment identifier for the transpilation job. circuit_ids: Existing stored circuit IDs to transpile. Use either this field or ``circuits_qasm``. circuits_qasm: Inline QASM circuits to persist and transpile in one step. device_id: Backend identifier returned by ``list_qpus_and_simulators``. transpilation_options: Optional backend-specific transpilation options forwarded to the underlying transpilation path. name: Optional job name inherited from the SDK model. description: Optional plain-text job description inherited from the SDK model. ContextTranspilationJobModel: properties: context: type: string title: Context type: object required: - context title: ContextTranspilationJobModel description: |- Represent context payload returned after transpilation job creation. Attributes: context: Submission summary text including the created job ID, the input circuit references, and the next polling step. This response model does not expose structured ``job_id`` or ``transpiled_circuit_ids`` fields outside the text payload. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyQuery: type: apiKey in: query name: HAIQU_API_KEY APIKeyHeader: type: apiKey in: header name: authorization ````