---
id: public-api.managed-execution
title: Managed Harness Execution API
summary: Submit Harness source, prepare its runtime and request execution as distinct recoverable operations.
kind: api
product_area: public_api
status: stable
updated: 2026-10-31
canonical: /docs/public-api/managed-execution
---

# Managed Harness Execution API

## Definition

Managed execution runs an explicitly submitted Harness against the selected Benchmark Version. It is an alternative to [submitting application outputs](/docs/public-api/evaluation-outputs). Paths below are relative to `BENCHMARK_URL` from the [quickstart](/docs/public-api/quickstart).

## Operation sequence

| Method and path | Input | Retain |
| --- | --- | --- |
| `GET /managed-run-profile` | Selected scope | Execution policy and concurrency token |
| `POST /harness-submissions` | `name`, exact `source` | Issued Harness/Version IDs |
| `POST /harness-runtime-preparations` | `harness_id`, `harness_version_id` | Preparation acknowledgement/state |
| `POST /managed-runs` | Saved IDs and `expected_managed_run_profile_revision` | Every admitted execution |

Writes require the operation's `Idempotency-Key`. Preserve exact bytes and a separate key for each command.

## Source package

`source.schema_version` is `harness_working_copy.v1`. File entries have relative `path` and UTF-8 `content_text`. The runtime accepts Python `3.12` and the callable `main.py:generate_result(request)`. Source policy permits at most 64 files, 256 KiB each and 1 MiB total. Symlinks, traversal and credential/cache paths are rejected.

Use the [CLI managed-Harness guide](/docs/cli/managed-harness) to package local files and retain recovery receipts. The [OpenAPI](https://api.teammately.ai/v1/openapi.yaml) defines all source/runtime fields.

## Prepare and admit

Preparation uses the exact saved IDs; acknowledgement does not certify runtime readiness. Inspect returned state and failures. Admission takes those IDs and the current `expected_managed_run_profile_revision`, plus optional existing `compute_profile_id`. The profile token is a concurrency precondition supplied by the server, not a number to choose.

Managed admission can return multiple individual executions according to policy. Inspect every returned ID through the [results API](/docs/public-api/benchmark-results). Admission is not completed generation/judging, and it does not activate a Harness.

Prepare `managed-run.json` with the saved `harness_id` and exact `harness_version_id`. Read `GET /managed-run-profile` and copy its integer `data.revision` into the request field `expected_managed_run_profile_revision`. Export `BENCHMARK_URL` and `MANAGED_OPERATION_KEY`; the latter identifies this logical admission command. These examples submit the file bytes once, without adding automatic retries.

### Example: Request managed execution

```sh
curl --fail-with-body \
  --header "Authorization: Bearer ${TEAMMATELY_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: ${MANAGED_OPERATION_KEY}" \
  --data-binary @managed-run.json \
  "${BENCHMARK_URL}/managed-runs"
```

```python
import os
from pathlib import Path
from urllib.parse import quote
from urllib.request import HTTPRedirectHandler, Request, build_opener

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = build_opener(NoRedirect())
api_key = os.environ["TEAMMATELY_API_KEY"]

url = os.environ["BENCHMARK_URL"] + "/managed-runs"
headers = {"Authorization": "Bearer " + api_key}
headers["Idempotency-Key"] = os.environ["MANAGED_OPERATION_KEY"]
headers["Content-Type"] = "application/json"
body = Path("managed-run.json").read_bytes()
request = Request(url, data=body, headers=headers, method="POST")
with opener.open(request) as response:
    print(response.read().decode("utf-8"))
```

```typescript
import { readFile } from "node:fs/promises";

const apiKey = process.env.TEAMMATELY_API_KEY!;

{
  const url = new URL(process.env.BENCHMARK_URL! + "/managed-runs");
  const response = await fetch(url, {
    method: "POST",
    redirect: "error",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": process.env.MANAGED_OPERATION_KEY!,
      "Content-Type": "application/json",
    },
    body: new Uint8Array(await readFile("managed-run.json")).buffer,
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(await response.text());
}
```

```go
package main

import (
    "bytes"
    "context"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
)

func main() {
    if err := run(context.Background()); err != nil { log.Fatal(err) }
}

func run(ctx context.Context) error {
    client := &http.Client{
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    {
        target := os.Getenv("BENCHMARK_URL") + "/managed-runs"
        payload, err := os.ReadFile("managed-run.json")
        if err != nil { return err }
        request, err := http.NewRequestWithContext(ctx, "POST", target, bytes.NewReader(payload))
        if err != nil { return err }
        request.Header.Set("Authorization", "Bearer " + os.Getenv("TEAMMATELY_API_KEY"))
        request.Header.Set("Idempotency-Key", os.Getenv("MANAGED_OPERATION_KEY"))
        request.Header.Set("Content-Type", "application/json")
        response, err := client.Do(request)
        if err != nil { return err }
        payloadBytes, readErr := io.ReadAll(response.Body)
        response.Body.Close()
        if readErr != nil { return readErr }
        fmt.Println(string(payloadBytes))
        if response.StatusCode < 200 || response.StatusCode >= 300 { return fmt.Errorf("HTTP %d", response.StatusCode) }
    }
    return nil
}
```

## Related reference pages

{% related-card-grid %}
- [Authentication](/docs/public-api/authentication)
- [CLI managed Harness](/docs/cli/managed-harness)
- [Harnesses](/docs/assets/harnesses)
{% /related-card-grid %}