Marqov API Reference

Marqov provides two primary interfaces for interacting with the platform: a command-line interface (CLI) for local development and workflow management, and a REST API for programmatic integration. This reference covers both interfaces and their core operations.

Note: Marqov is currently in active development. API endpoints and CLI commands may evolve as we refine the platform based on user feedback.

CLI Commands

The Marqov CLI is the primary tool for local development, capsule management, and job execution. Install it via your preferred package manager to get started.

`marqov init`

Initialize a new capsule in the current directory.

marqov init [name]

Arguments:

name (optional): Name for the capsule. Defaults to the directory name.

Options:

--template <template>: Use a starter template (e.g., vqe, qaoa, hybrid-ml)
--backend <backend>: Set the default target backend
--no-git: Skip git repository initialization

Example:

marqov init my-vqe-experiment --template vqe

Creates a marqov.yaml specification file and the recommended directory structure for a reproducible capsule.

`marqov validate`

Validate a capsule specification against the Marqov schema.

marqov validate [path]

Arguments:

path (optional): Path to the capsule directory or marqov.yaml. Defaults to current directory.

Options:

--strict: Enable strict validation (warnings become errors)
--check-deps: Verify all dependencies are resolvable
--dry-run: Simulate execution without running

Example:

marqov validate ./my-capsule --strict

Returns validation status, warnings, and any schema violations that need to be addressed before publishing.

`marqov publish`

Publish a capsule to the Marqov registry.

marqov publish [path]

Arguments:

path (optional): Path to the capsule directory. Defaults to current directory.

Options:

--visibility <public|private>: Set capsule visibility (default: private)
--tag <tag>: Add a version tag (e.g., v1.0.0, latest)
--org <organization>: Publish under an organization namespace
--message <message>: Add a publish message

Example:

marqov publish --visibility public --tag v1.0.0

Validates, packages, and uploads the capsule to the registry. Returns a unique capsule identifier for reference.

`marqov run`

Execute a capsule on the specified backend(s).

marqov run <capsule> [options]

Arguments:

capsule: Capsule identifier, local path, or registry reference

Options:

--backend <backend>: Target backend (e.g., ibm-brisbane, ionq-aria, aws-sv1)
--params <file>: JSON file with runtime parameters
--priority <low|normal|high>: Job priority level
--wait: Block until job completes
--output <path>: Download results to specified path

Example:

marqov run marqov/vqe-h2@v1.0.0 --backend ibm-brisbane --wait

Submits the capsule for execution and returns a job ID for tracking.

`marqov status`

Check the status of a running or completed job.

marqov status <job-id>

Arguments:

job-id: The job identifier returned by marqov run

Options:

--watch: Continuously poll for updates
--json: Output in JSON format
--logs: Include execution logs

Example:

marqov status job_abc123xyz --watch

Returns job state (queued, running, completed, failed), resource usage, and result summary.

`marqov pull`

Download a capsule from the registry.

marqov pull <capsule> [path]

Arguments:

capsule: Capsule identifier or registry reference
path (optional): Destination directory

Options:

--version <version>: Specific version or tag to pull
--include-data: Include associated datasets
--force: Overwrite existing files

Example:

marqov pull marqov/qaoa-maxcut@latest ./local-copy

Downloads the capsule specification, source code, and optionally associated data to the local filesystem.

`marqov search`

Search the Marqov registry for capsules.

marqov search <query>

Arguments:

query: Search terms

Options:

--backend <backend>: Filter by compatible backend
--tag <tag>: Filter by tag
--org <organization>: Search within an organization
--limit <n>: Maximum results to return (default: 20)

Example:

marqov search "variational quantum" --backend ionq

Returns matching capsules with their descriptions, version info, and compatibility details.

REST API

The Marqov REST API enables programmatic access to all platform capabilities. All endpoints require authentication via API key.

Base URL

https://api.marqov.com/v1

Authentication

Include your API key in the request header:

Authorization: Bearer <your-api-key>

`POST /capsules`

Create a new capsule in the registry.

Request Body:

{
  "name": "my-vqe-experiment",
  "description": "VQE for H2 molecule ground state",
  "visibility": "private",
  "specification": {
    "version": "1.0",
    "compute": {
      "quantum": { "type": "gate-based", "min_qubits": 4 },
      "classical": { "type": "cpu", "memory": "4GB" }
    },
    "workflow": [...]
  },
  "tags": ["vqe", "chemistry"]
}

Response:

{
  "id": "cap_7kj3m9x2",
  "name": "my-vqe-experiment",
  "created_at": "2025-02-15T10:30:00Z",
  "status": "created"
}

`GET /capsules/{id}`

Retrieve details for a specific capsule.

Path Parameters:

id: Capsule identifier

Query Parameters:

include: Comma-separated list of related resources (specification, versions, stats)

Response:

{
  "id": "cap_7kj3m9x2",
  "name": "my-vqe-experiment",
  "description": "VQE for H2 molecule ground state",
  "visibility": "private",
  "owner": "user_abc123",
  "created_at": "2025-02-15T10:30:00Z",
  "updated_at": "2025-02-15T10:30:00Z",
  "latest_version": "v1.0.0",
  "compatible_backends": ["ibm-brisbane", "ionq-aria", "aws-sv1"]
}

`POST /capsules/{id}/run`

Execute a capsule on specified backend(s).

Path Parameters:

id: Capsule identifier

Request Body:

{
  "backend": "ibm-brisbane",
  "parameters": {
    "shots": 1024,
    "optimization_level": 2
  },
  "priority": "normal",
  "callback_url": "https://your-app.com/webhook/job-complete"
}

Response:

{
  "job_id": "job_abc123xyz",
  "capsule_id": "cap_7kj3m9x2",
  "backend": "ibm-brisbane",
  "status": "queued",
  "created_at": "2025-02-15T10:35:00Z",
  "estimated_start": "2025-02-15T10:40:00Z"
}

`GET /jobs/{id}`

Get the status and results of a job.

Path Parameters:

id: Job identifier

Query Parameters:

include: Comma-separated list (logs, metrics, results)

Response:

{
  "job_id": "job_abc123xyz",
  "capsule_id": "cap_7kj3m9x2",
  "status": "completed",
  "backend": "ibm-brisbane",
  "created_at": "2025-02-15T10:35:00Z",
  "started_at": "2025-02-15T10:41:00Z",
  "completed_at": "2025-02-15T10:43:22Z",
  "metrics": {
    "total_shots": 1024,
    "circuit_depth": 42,
    "execution_time_ms": 1842
  },
  "results_url": "https://api.marqov.com/v1/jobs/job_abc123xyz/results"
}

Status Values:

queued: Job is waiting for resources
running: Job is actively executing
completed: Job finished successfully
failed: Job encountered an error
cancelled: Job was cancelled by user

`GET /backends`

List all available compute backends.

Query Parameters:

type: Filter by backend type (quantum, classical, gpu)
provider: Filter by provider (ibm, ionq, aws, azure)
available: Only show currently available backends (true/false)

Response:

{
  "backends": [
    {
      "id": "ibm-brisbane",
      "name": "IBM Brisbane",
      "type": "quantum",
      "provider": "ibm",
      "qubits": 127,
      "status": "online",
      "queue_depth": 12,
      "features": ["dynamic-circuits", "mid-circuit-measurement"]
    },
    {
      "id": "ionq-aria",
      "name": "IonQ Aria",
      "type": "quantum",
      "provider": "ionq",
      "qubits": 25,
      "status": "online",
      "queue_depth": 3,
      "features": ["all-to-all-connectivity"]
    }
  ],
  "total": 15,
  "page": 1
}

Error Handling

All API responses follow a consistent error format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid capsule specification",
    "details": [
      {
        "field": "specification.compute.quantum.min_qubits",
        "issue": "Must be a positive integer"
      }
    ]
  }
}

Common Error Codes:

AUTHENTICATION_ERROR: Invalid or missing API key
AUTHORIZATION_ERROR: Insufficient permissions
VALIDATION_ERROR: Invalid request parameters
NOT_FOUND: Resource does not exist
RATE_LIMITED: Too many requests
BACKEND_UNAVAILABLE: Target backend is offline

Rate Limits

API requests are rate-limited based on your plan:

Plan	Requests/min	Concurrent Jobs
Free	60	2
Team	300	10
Enterprise	Custom	Custom

Rate limit headers are included in all responses:

X-RateLimit-Limit: Maximum requests per window
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets

What’s Next

This API reference will continue to evolve as we build out the platform. We’re actively working on:

SDK Libraries: Python, JavaScript, and Julia clients
Webhook Events: Real-time notifications for job state changes
Batch Operations: Submit and manage multiple jobs efficiently
Advanced Scheduling: Priority queues and resource reservation

Have feedback on the API design? Join our Discord or reach out to the team directly.

The Marqov API is designed to make hybrid quantum-classical orchestration accessible to every team building at the frontier of computing.