> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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/{id}    | None                                                     | Full experiment record with state and results | Required |
| GET    | /models/{id}         | None                                                     | Model record with lineage and current status  | Required |
| GET    | /artifacts/{id}      | 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

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant C as Client
    participant A as API Gateway
    participant M as MergeEngine
    participant V as MergeValidation
    participant S as ArtifactStore
    C->>A: POST /merge/execute
    A->>M: Forward request with auth
    M->>M: Load models from ModelRegistry
    M->>M: Run ModelCompatibilityAnalyzer
    M->>M: Execute TensorEngine operations
    M->>V: Validate merged output
    V->>M: PASS / FAIL
    M->>S: Store merged weights
    M->>A: Return job ID + status URL
    A->>C: 202 Accepted
    loop Polling
        C->>A: GET /experiments/{job_id}
        A->>C: State: RUNNING / COMPLETED / FAILED
    end
```

## Representative Endpoint: POST /merge/execute

<ParamField body="source_model_ids" type="array[string]" required>
  Array of model IDs to merge. Minimum 2, maximum 8.
</ParamField>

<ParamField body="strategy" type="string" required>
  Merge strategy name. One of: slerp, ties, dare, task\_arithmetic, franken\_merge.
</ParamField>

<ParamField body="parameters" type="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`.
</ParamField>

<ParamField body="output_model_id" type="string" required>
  Desired ID for the merged model. Must be unique in the registry.
</ParamField>

<ResponseField name="job_id" type="string">
  Unique identifier for the merge job. Use this to poll status.
</ResponseField>

<ResponseField name="status_url" type="string">
  Absolute URL to GET for progress updates.
</ResponseField>

<ResponseField name="initial_state" type="string">
  Always `CREATED`. Transitions to PREPARING, RUNNING, EVALUATING, COMPLETED, or FAILED.
</ResponseField>

## Error Responses

All endpoints return structured errors:

```json theme={null}
{
  "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.