API Reference

MediaMoth's application API is gRPC with Protocol Buffers. Use a generated protobuf client for an integration; the protobuf repository owns the wire schema and the mediamoth repository implements the services below.

Discover a running server

Servers enable gRPC reflection. Run these commands against a development Job Service to inspect the exact services and descriptors exposed by that build:

grpcurl -plaintext localhost:50053 list
grpcurl -plaintext localhost:50053 describe

The first command lists the available service names. Development ports are listed in Getting Started.

Service surface

Job Service

Commands:

• QueueJob and bidirectional QueueJobStream;
• RerunPipeline and RecordRerun;
• NotifyJobStart and NotifyJobFinished;
• ApplyJobCorrection;
• RetryJob;
• CancelJob.

Queries:

• GetJob;
• server-streaming GetJobsByInstanceId.

Media Service

Commands:

• CreateMedia;
• UpdateMedia;
• client-streaming CreateMediaStream.

Query:

• GetMediaById.

Workflow Service

Pipeline commands:

• CreatePipeline, UpdatePipeline, and DeletePipeline;
• AddTemplate and UpdateTemplate.

Monitor commands:

• RegisterService;
• CheckServiceStatus.

Queries:

• GetService;
• GetPipeline;
• GenerateNodeId;
• CheckServicesExist.

Search Service

Search operations:

• SearchJobs;
• SearchServices;
• SearchPipelines;
• SearchMedia.

Search requests support filters, sorts, pagination, and aggregations; responses include a total count.

Worker services

Video Service, Chapter Inserter, and both VHS modules implement the common worker surface:

• QueueJob;
• RequeueJob;
• CancelJob;
• GetServiceMetadata.

Service metadata includes the parameter JSON Schema, UI Schema, and service version advertised through health checks.

Do not copy request JSON from this overview without checking the descriptors for your deployed version.

CQRS and events

Command services load event-sourced aggregates and append domain events. Query services read projections. Kafka handlers update cross-service projections and move jobs between services. Administrative projection rebuilds replay stored events through the same event handlers; see CLI Commands.

Optional MCP access

Job, Media, Workflow, and Search server commands can expose an MCP SSE endpoint with --mcp and --mcp-addr. Job Service can additionally enable its MQTT listener with --mqtt.

MCP and MQTT are adapters around the underlying service operations; they do not replace the protobuf contract.

Related documentation

• Key Concepts
• Building Custom Workers
• CLI Commands