API Details

The Mavis Camera API uses a WebSocket connection to let another application control the camera, query current camera state, and receive updates when values change.

If you are new to the API, start with the Introduction and try the API Playground first. This page covers the technical details you need when building your own integration.

Connection and API keys

Mavis Camera exposes the API over the local network while the app is open in the foreground.

In Mavis Camera:

1. Open Settings.
2. Open API.
3. Turn on Enable API Access.
4. Open URLs to view the addresses available for the API.

The Playground and WebSocket URLs use unencrypted local-network connections, so use them only on a network you trust.

Use the WebSocket URL shown in URLs to establish the API connection from your application. If API keys are enabled, use the URL associated with the API key you want to use.

Using API keys

API keys are optional. For simple testing on a trusted local network, you can leave Use API Keys turned off.

If you turn on Use API Keys, create or enable a key in Mavis Camera and use the URL associated with that key.

A key-specific URL contains the token required to connect. Treat that URL as a secret.

Commands

A command asks Mavis Camera to do something. Commands use a dotted path followed by parentheses.

camerasystem.record.start()
focus.mode(manual)
exposure.iso(100)
colorgrade.matrix.hue(0,0.25)

Commands can have:

• No arguments: camerasystem.record.start()
• One argument: camerasystem.bars(true)
• Multiple arguments: colorgrade.matrix.hue(0,0.25)

Arguments are positional, so their order matters.

Templates and placeholders

The live API schema describes commands using templates. Braces indicate a placeholder:

focus.value({value})

Replace the complete placeholder with the value you want to send:

focus.value(0.5)

Do not include the braces in the command you send.

Argument types

Follow the ranges, allowed values, steps, and units published by the live schema. Some constraints depend on the current camera and configuration.

Calling a command

Send a WebSocket text message containing a JSON call operation.

For example, to show color bars:

{
  "call": {
    "command": "camerasystem.bars(true)",
    "replyTo": "bars-on-1"
  }
}

replyTo is optional. It is a client-defined string that is copied into the direct response, making it easy to match a response with the request that caused it.

A successful call returns an acknowledgement:

{
  "status": "ok",
  "command": "camerasystem.bars(true)",
  "replyTo": "bars-on-1"
}

The returned command is the canonical command. A successful response means the command was accepted and executed.

If your application needs to know the resulting state, query or subscribe to the corresponding state path.

Command errors

A failed call returns status: "error" and an error object:

{
  "status": "error",
  "command": "focus.mode(unsupported)",
  "error": {
    "code": "invalidArgumentValue",
    "message": "A diagnostic explanation is returned here."
  },
  "replyTo": "focus-mode-1"
}

Use error.code for application logic and error.message for diagnostics.

A rejected request does not close or invalidate the WebSocket session. Correct the request and continue.

Requests are strict. Unknown fields, invalid JSON types, empty required strings, unsupported operations, and invalid command arguments are rejected.

State and events

The API represents camera state as subscribable state paths.

Examples include:

cameraSystem.record.isRecording
focus.mode
exposure.iso
zoom.factor

Use:

• query for a one-time read.
• registerState to receive the current value and future updates.
• unregisterState to remove selected subscriptions.
• clearRegisteredState to remove every subscription in the current session.

Query a state path

To read the current recording state:

{
  "query": {
    "path": "cameraSystem.record.isRecording",
    "replyTo": "record-state-1"
  }
}

The response is a mergeable JSON fragment rooted at the requested path:

{
  "cameraSystem": {
    "record": {
      "isRecording": false
    }
  },
  "replyTo": "record-state-1"
}

You can merge this fragment into a client-side state tree without replacing unrelated state.

Subscribe to state changes

Register a single path:

{
  "registerState": {
    "path": "exposure.iso",
    "replyTo": "iso-subscription"
  }
}

Or register several paths together:

{
  "registerState": {
    "paths": [
      "cameraSystem.record.isRecording",
      "cameraSystem.bars",
      "exposure.iso"
    ],
    "replyTo": "camera-subscription"
  }
}

Supply path or paths, never both.

The registration response reports the canonical registered paths and their current values:

{
  "status": "registered",
  "registeredStatePaths": [
    "cameraSystem.record.isRecording",
    "cameraSystem.bars",
    "exposure.iso"
  ],
  "state": [
    {
      "cameraSystem": {
        "record": {
          "isRecording": false
        }
      }
    },
    {
      "cameraSystem": {
        "bars": false
      }
    },
    {
      "exposure": {
        "iso": 100
      }
    }
  ],
  "replyTo": "camera-subscription"
}

The values above are examples. The camera returns its current state.

After registration, a change produces an unsolicited event:

{
  "exposure": {
    "iso": 200
  }
}

Unsolicited events do not contain replyTo because they are not direct responses to a request.

Canonical paths and group subscriptions

Use the exact state-path spelling published by discovery.

Command roots and event roots do not always use the same capitalization. For example:

• Command root: camerasystem
• Event root: cameraSystem

You can subscribe to a leaf such as exposure.iso or to a group such as exposure. A group event contains the available state beneath that group.

Equivalent input spellings are deduplicated, but registrations, responses, and errors use the canonical schema spelling.

A schema-known value may be temporarily unavailable. It can remain registered and begin producing events when it becomes available.

Unsubscribe

Remove one or more paths with unregisterState:

{
  "unregisterState": {
    "path": "cameraSystem.bars",
    "replyTo": "remove-bars"
  }
}

The response reports removed and remaining paths:

{
  "status": "unregistered",
  "removedStatePaths": [
    "cameraSystem.bars"
  ],
  "registeredStatePaths": [
    "cameraSystem.record.isRecording",
    "exposure.iso"
  ],
  "replyTo": "remove-bars"
}

To clear every registered state path:

{
  "clearRegisteredState": {
    "replyTo": "clear-all-state"
  }
}

Subscriptions belong to one WebSocket session. A reconnect creates a new session, so register the state paths you need again after reconnecting.

Discovery

Discovery tells your application what the connected camera supports now.

A client should discover the live schema when it connects instead of permanently embedding a copied list of commands and constraints. Available commands, choices, ranges, and other constraints can depend on the device and its current configuration.

Request the schema

{
  "enumerateSchema": {
    "mode": "ai",
    "includeDynamicConstraints": true,
    "replyTo": "schema-1"
  }
}

All three request fields are optional:

• mode accepts ai, compact, or debug and defaults to ai.
• includeDynamicConstraints is a Boolean and defaults to true.
• replyTo is copied into the response when supplied.

Use ai unless your integration has a reason to request another published serialization mode. Keep dynamic constraints enabled when you need the camera's current ranges and allowed values.

What discovery returns

The protocol has no version field. Treat the schema response as the authority for the connected camera.

Recommended discovery workflow

1. Open the WebSocket connection.
2. Request the schema with dynamic constraints enabled.
3. Build or validate command controls from roots.
4. Build event choices from stateRoots.
5. Use each command's template and argument metadata.
6. Use only state paths whose access includes the operation you need.
7. Register the smallest useful set of state paths.
8. Discover and register again after reconnecting.

Command reference

Templates below use braces for argument placeholders. Replace placeholders with values before calling the command.

Camera System

Focus

Exposure

White Balance

Zoom

Lens Controls

Tally

Color Grade

Subscribable state reference

Every path below supports both one-time query and ongoing subscription.

Group paths return a mergeable fragment containing their available descendants. Structured means the published schema does not declare a scalar type for that leaf; discover and inspect its live JSON value rather than assuming a fixed shape.

Camera System

Focus

Exposure

White Balance

Zoom

Lens Controls

Tally

Color Grade