EMEP REST API Specification

REST API surface for EMEP including endpoints for models, compatibility, merge, experiments, candidates, evolution, benchmarks, and artifacts.

The EMEP REST API exposes the full platform surface: model registration, compatibility checks, merge execution, experiment management, candidate evaluation, evolution runs, and artifact retrieval. All endpoints require authentication via API key in the Authorization header.

Authentication

Pass your API key in every request:

Authorization: Bearer <api_key>

Missing or invalid keys return HTTP 401. Insufficient permissions return HTTP 403.

Endpoint Table

Method	Path	Request Summary	Response Summary	Auth
POST	/models/register	Model manifest (id, source, format, config)	Model record with lifecycle state	Required
POST	/compatibility/check	Two model IDs, optional merge strategy hint	Compatibility state and detailed report	Required
POST	/merge/execute	Source model IDs, strategy, parameters	Merge job ID and status URL	Required
POST	/experiments	Experiment type, config, dataset references	Experiment record with ID and state	Required
POST	/candidates/evaluate	Candidate model ID, benchmark suite IDs	Evaluation job ID and status URL	Required
POST	/evolution/runs	Population config, fitness objectives, stopping criteria	Evolution run ID and initial population	Required
GET	/experiments/	None	Full experiment record with state and results	Required
GET	/models/	None	Model record with lineage and current status	Required
GET	/artifacts/	None	Artifact metadata and download URL	Required
POST	/benchmarks/run	Benchmark suite ID, model IDs, backend config	Benchmark job ID and status URL	Required

Merge Request Sequence

Representative Endpoint: POST /merge/execute

source_model_ids · array[string] · required

Array of model IDs to merge. Minimum 2, maximum 8.

strategy · string · required

Merge strategy name. One of: slerp, ties, dare, task_arithmetic, franken_merge.

parameters · object

Strategy-specific parameters. For SLERP (Shoemake 1985): t (interpolation factor). For TIES (Yadav et al. 2023): density, epsilon. For DARE (Yu et al. 2023): drop_rate, rescale.

output_model_id · string · required

Desired ID for the merged model. Must be unique in the registry.

job_id · string

Unique identifier for the merge job. Use this to poll status.

status_url · string

Absolute URL to GET for progress updates.

initial_state · string

Always CREATED. Transitions to PREPARING, RUNNING, EVALUATING, COMPLETED, or FAILED.

Error Responses

All endpoints return structured errors:

{
  "error": "INCOMPATIBLE_MODELS",
  "message": "Models m1 and m2 are INCOMPATIBLE due to tensor shape mismatch in layer 12",
  "details": {
    "layer": "transformer.h.12.attn.c_attn.weight",
    "expected": [768, 2304],
    "actual": [768, 3072]
  }
}

Common error codes: INCOMPATIBLE_MODELS, INVALID_STRATEGY, MODEL_NOT_FOUND, QUOTA_EXCEEDED, GPU_UNAVAILABLE, VALIDATION_FAILED.

Rate Limits

Authenticated requests are rate-limited per API key. Default limits: 100 requests per minute for reads, 10 per minute for merge and evolution jobs. Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Integration Points

• ModelRegistry: stores and retrieves model metadata.
• MergeEngine: executes merge jobs asynchronously.
• ExperimentTracker: creates and updates experiment records.
• ArtifactStore: stores and serves artifact binaries.
• EvaluationEngine: runs benchmark and candidate evaluation jobs.