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. MediaMoth Core hosts the job, media, workflow, and search service contracts together on one gRPC endpoint.

Discover a running server

MediaMoth Core enables gRPC reflection. Run these commands against its development endpoint to inspect every core service and descriptor exposed by that build:

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe

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

Core service surface

The headings below are logical protobuf service families, not separate server processes. Configure generated clients for all four families with the same Core address, such as mediamoth-core:50051 inside Compose.

Job API

Commands:

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

Queries:

• GetJob;
• server-streaming GetJobsByInstanceId.

Media API

Commands:

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

Query:

• GetMediaById.

Workflow API

Pipeline commands:

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

Monitor commands:

• RegisterService;
• CheckServiceStatus.

Queries:

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

Search API

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

mediamoth-core serve can expose all four core API families through one MCP SSE endpoint with --mcp and --mcp-addr. The same process can enable the job module's 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