generated: '2026-08-06'
method: searched
source: >-
  https://felis.alice-bob.com/docs/reference/the_api/ and
  https://felis.alice-bob.com/docs/felis_cloud/connect_to_felis_cloud/ for the auth and
  base-URL conventions; the reference client
  https://github.com/Alice-Bob-SW/qiskit-alice-bob-provider (remote/api/client.py) for the
  exact header it sends; and openapi/alice--bob-felis-cloud-openapi.json for pagination,
  versioning and the error envelope.
description: >-
  Cross-cutting request/response semantics of the Felis Cloud API — the runtime rules
  that apply to every operation and that the OpenAPI does not express. Felis Cloud is a
  small, job-oriented REST API generated by FastAPI: a job is created, its QIR payload is
  uploaded as a separate multipart request, and the client polls until an event terminates
  the job.

base_url: https://api-gcp.alice-bob.com/v1
legacy_base_url: https://api.alice-bob.com/
api_style: REST over HTTPS, JSON responses; multipart/form-data for the circuit upload
spec_generator: FastAPI (OpenAPI 3.1.0)

authentication:
  scheme: API key sent in the HTTP Authorization header with the `Basic` auth-scheme token
  header: 'Authorization: Basic <API key>'
  note: >-
    The key is NOT base64-encoded RFC 7617 credentials — the raw API key string is placed
    after the literal word `Basic`. Verified in the reference client
    (qiskit_alice_bob_provider/remote/api/client.py) and in the curl example the docs publish.
  key_issuance: https://api-gcp.alice-bob.com/console/ ("API KEYS" tab)
  key_scope: One key per person is recommended by the docs so billing and revocation stay per-user.
  docs: https://felis.alice-bob.com/docs/felis_cloud/connect_to_felis_cloud/
  detail: authentication/alice--bob-authentication.yml
  spec_gap: >-
    The published OpenAPI declares an EMPTY components.securitySchemes and models the
    credential as an optional `authorization` header parameter on each operation. The real
    requirement is mandatory — every unauthenticated request to api-gcp.alice-bob.com
    returns 401. overlays/alice--bob-felis-cloud-overlay.yaml corrects this without
    mutating the original spec.

idempotency:
  supported: false
  mechanism: null
  note: >-
    No idempotency key, request-replay or de-duplication mechanism is documented or present
    in the spec. POST /v1/jobs/ creates a new job on every call; a retried create produces a
    second job (and second billable execution). Callers must de-duplicate client-side by
    correlating on the returned job `id`. Recorded honestly — no Idempotency pointer is wired.

pagination:
  styles:
    - surface: GET /v1/jobs/
      style: page-number
      request_params:
        page: {type: integer, minimum: 1, default: 1}
        limit: {type: integer, minimum: 0, maximum: 1000, default: 100}
    - surface: GET /v1/targets/{target}/availabilities
      style: limit-offset
      request_params:
        limit: {type: integer, default: 100}
        offset: {type: integer, default: 0}
  response_fields:
    note: >-
      Both list operations return a bare JSON array — there is no envelope, no total count
      and no has_more/next-cursor field. A client detects the end of a collection by
      receiving fewer items than `limit`.
  inconsistency: >-
    The two paginated collections use different paging idioms (page/limit vs limit/offset)
    in the same API version.

versioning:
  scheme: URI path prefix
  current: v1
  info_version: 0.1.0
  note: >-
    The API is versioned in the path (/v1/...). The OpenAPI `info.version` is 0.1.0 and is
    not the contract version clients pin to. No version request header exists.
  detail: lifecycle/alice--bob-lifecycle.yml

error_envelope:
  gateway:
    media_type: application/json
    shape: '{"error": {"code": <int>, "message": <string>}}'
    observed: 'HTTP 401 {"error":{"code":401,"message":"Unauthorized"}} on every path of api-gcp.alice-bob.com without a key'
  application:
    media_type: application/json
    shape: '{"detail": [{"loc": [...], "msg": "...", "type": "..."}]}'
    schema: HTTPValidationError
    note: Standard FastAPI validation envelope; the only 4xx declared in the spec is 422.
  rfc9457: false
  detail: errors/alice--bob-problem-types.yml

asynchrony:
  model: poll
  note: >-
    Job execution is asynchronous but there is no callback, webhook or streaming surface.
    A client creates the job, uploads the QIR input, then polls GET /v1/jobs/{job_id} and
    reads the `events[]` array, whose last entry carries one of the EventType terminal
    values (SUCCEEDED, EXECUTION_FAILED, COMPILATION_FAILED, TRANSPILATION_FAILED,
    CANCELLED, TIMED_OUT).
  event_types: [CREATED, FETCHING_INPUT, INPUT_READY, COMPILING, COMPILED, COMPILATION_FAILED,
    TRANSPILING, TRANSPILED, TRANSPILATION_FAILED, EXECUTING, SUCCEEDED, EXECUTION_FAILED,
    CANCELLED, TIMED_OUT]

rate_limit_signaling:
  documented: false
  note: >-
    No rate-limit headers (X-RateLimit-*, RateLimit, Retry-After) are documented or declared
    in the spec, and no 429 response is declared on any operation. Contention is managed by a
    hard 15-minute cap on job duration on the shared Boson 4 chip
    (https://felis.alice-bob.com/docs/reference/faq/) plus the published availability schedule,
    not by request-rate throttling.

request_tracing:
  documented: false
  note: No request-id / correlation-id response header is documented. The job `id` (UUID) is
    the only durable correlation handle.

field_conventions:
  case: lowerCamelCase in JSON bodies (inputDataFormat, outputDataFormat, inputParams,
    organizationName, createdAt) — but snake_case in the metrics object (qpu_duration_ns,
    simulation_duration_ns) and in query parameters.
  identifiers: Job ids are UUIDs; target names are opaque uppercase strings of the form
    '<CLASS>:<N>Q:<MODEL>' (e.g. QPU:1Q:BOSON_4A, EMU:6Q:PHYSICAL_CATS).
  timestamps: RFC 3339 date-time strings (createdAt).

payload_formats:
  input: HUMAN_QIR — Quantum Intermediate Representation (https://github.com/qir-alliance/qir-spec),
    uploaded as multipart/form-data to POST /v1/jobs/{job_id}/input
  output: HISTOGRAM — measurement bitstrings mapped to occurrence counts
  memory: Per-shot measurement results, available when requested

cross_links:
  authentication: authentication/alice--bob-authentication.yml
  errors: errors/alice--bob-problem-types.yml
  lifecycle: lifecycle/alice--bob-lifecycle.yml
  data_model: data-model/alice--bob-data-model.yml
  sandbox: sandbox/alice--bob-sandbox.yml