@evolvingmachines/evolve 0.0.65 → 0.0.67-train-harness-wave-2026-09-25.20260926.e00a8a6d

package/skills/evolve-evals/references/sdk/http.md

@@ -0,0 +1,110 @@
+---
+title: "HTTP API"
+description: "Submit and inspect evaluations from any language."
+---
+
+The CLI and SDKs call the same HTTP API. Use it directly when you need another language or an operation without an SDK method.
+
+## Connect
+
+Use `https://dashboard.evolvingmachines.ai` as the origin. Send your [API key](/getting-started/installation#connect-your-account) in the `Authorization` header. Writes require a full-access key.
+
+```bash
+curl -sS https://dashboard.evolvingmachines.ai/api/auth/status \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+`GET /api/meta` needs no key. It lists the current harnesses, models, limits, and error codes.
+
+## Start one evaluation
+
+Save the request as `job.json`:
+
+```json job.json
+{
+  "datasets": [{
+    "name": "harbor-examples",
+    "version": "1.0",
+    "task_names": ["hello-world"]
+  }],
+  "agents": [{
+    "name": "codex",
+    "model_name": "gpt-5.6-luna"
+  }],
+  "max_trial_spend_usd": 1,
+  "retry": {"max_retries": 0}
+}
+```
+
+```bash
+curl -sS https://dashboard.evolvingmachines.ai/api/jobs \
+  -H "Authorization: Bearer $EVOLVE_API_KEY" \
+  -H "Content-Type: application/json" \
+  --data-binary @job.json
+```
+
+Success returns `202` and the accepted job. Set `$JOB_ID` to its `id`. Closing the HTTP connection does not cancel the evaluation.
+
+The JSON fields match the [SDK job inputs](/sdk-reference/jobs#required-inputs). Add `org` to create the job in a team. Attach stored secrets through the request's [secret references](/sdk-reference/secrets#attach-it-to-a-job).
+
+**Note:**
+
+To retry the same submission safely after a transport failure, send an `Idempotency-Key` header with a unique value for that intended job. Reuse it only for retries of that submission. A new intended run needs a new key.
+
+## Follow the result
+
+### Read status
+
+```bash
+curl -sS "https://dashboard.evolvingmachines.ai/api/jobs/$JOB_ID" \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+### Read trials
+
+```bash
+curl -sS "https://dashboard.evolvingmachines.ai/api/jobs/$JOB_ID/trials" \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+### Stream progress
+
+```bash
+curl -N "https://dashboard.evolvingmachines.ai/api/jobs/$JOB_ID/events" \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+This endpoint returns server-sent events. The SDK watchers handle reconnection for you; `curl` does not.
+
+## Page through collections
+
+Collections use `{ items, nextCursor, hasMore }`. Pass the returned `nextCursor` as `cursor` on the next request, keeping the same filters. Treat it as an opaque string.
+
+```bash
+curl -sS --get https://dashboard.evolvingmachines.ai/api/jobs \
+  -H "Authorization: Bearer $EVOLVE_API_KEY" \
+  --data-urlencode "limit=20" \
+  --data-urlencode "cursor=$NEXT_CURSOR"
+```
+
+## Handle an error
+
+An API refusal returns a non-success HTTP status and an `error` object:
+
+| Field | Use |
+| --- | --- |
+| `code` | Choose how your client handles the failure |
+| `message` | Explain the problem to the caller |
+| `param`, `details` | Locate invalid input or read failure context, when present |
+| `request_id` | Identify the request when reporting a problem |
+| `retryAfterSec` | Requested delay, when present; also sent as `Retry-After` |
+
+The response also includes `X-Request-Id`. See [error handling](/sdk-reference/errors) for common codes and the difference between retrying an HTTP request and retrying a trial.
+
+## Operations beyond the SDK methods
+
+| Need | Reference |
+| --- | --- |
+| List or revoke API keys | [Key management](/sdk-reference/auth#manage-api-keys-over-http) |
+| Manage team names, roles, and invitations | [Team management](/sdk-reference/auth#manage-teams-over-http) |
+| Filter or sort the dataset catalog | [Dataset filters](/sdk-reference/datasets#browse-the-catalog) |

package/skills/evolve-evals/references/sdk/python.md

@@ -0,0 +1,108 @@
+---
+title: "Python"
+description: "Run one task from an async Python program. No Node bridge is needed."
+---
+
+Install the package and set your [API key](/getting-started/installation).
+
+```bash
+pip install evolvingmachines-evolve
+export EVOLVE_API_KEY="your-api-key"
+```
+
+## Run one task
+
+The managed evals client calls the API directly. Save this as `eval.py` and run `python eval.py`.
+
+```python eval.py
+import asyncio
+from evolve import hosted
+
+
+async def main():
+    async with hosted() as evolve:
+        job = await evolve.jobs.start(
+            datasets=[{
+                "name": "harbor-examples",
+                "version": "1.0",
+                "task_names": ["hello-world"],
+            }],
+            agents=[{"name": "codex", "model_name": "gpt-5.6-luna"}],
+            max_trial_spend_usd=0.50,
+            retry={"max_retries": 0},
+        )
+        print("Job:", job.id)
+
+        finished = await evolve.jobs.watch(job.id)
+        print("Status:", finished.status)
+        print("Model cost:", finished.stats.get("cost_usd"))
+
+        async for trial in evolve.jobs.trials(job.id):
+            print(trial.task_name, trial.status, trial.reward)
+
+        archive = await evolve.jobs.download(job.id, to="./results")
+        print("Saved:", archive)
+
+
+asyncio.run(main())
+```
+
+### 1. Submit
+
+`start()` returns the accepted job. It does not wait for the trial.
+
+### 2. Wait
+
+`watch()` follows progress and returns the terminal job.
+
+### 3. Inspect
+
+Use attributes for jobs and trials, and dictionary keys for stats.
+
+### 4. Keep the results
+
+`download()` saves a verified archive and returns its path.
+
+The example sets a $0.50 cap for the trial and disables configured infrastructure retries. Provider capacity waits are handled separately. A completed job can contain failed trials; inspect their statuses and rewards.
+
+## Show progress
+
+Use the following snippets inside the `async with hosted() as evolve` block in `main()`, after creating `job`.
+
+```python
+finished = await evolve.jobs.watch(
+    job.id,
+    on_event=lambda event: print(event.seq, event.type),
+)
+```
+
+Or consume the events directly:
+
+```python
+async for event in evolve.jobs.watch(job.id):
+    print(event.type, event.data)
+finished = await evolve.jobs.get(job.id)
+```
+
+Choose one consumption style for each watch handle.
+
+## Read a trial
+
+This uses the same `evolve` client and `job` from the program above.
+
+```python
+page = await evolve.jobs.trials(job.id, limit=1)
+if page.items:
+    trial = page.items[0]
+    trajectory = await evolve.trials.artifact(trial.id, "trace-atif")
+    files = await evolve.trials.files(trial.id)
+    print(trajectory, files.items)
+```
+
+**[Configure a job](/sdk-reference/jobs)**
+
+Models, task filters, attempts, limits, and analysis.
+
+**[Understand returned objects](/sdk-reference/types)**
+
+Dataclasses, dictionaries, nullable values, and status fields.

package/skills/evolve-evals/references/sdk/typescript.md

@@ -0,0 +1,104 @@
+---
+title: "TypeScript"
+description: "Run one task, follow its progress, and inspect the result."
+---
+
+Install the package and set your [API key](/getting-started/installation).
+
+```bash
+npm install @evolvingmachines/evolve
+export EVOLVE_API_KEY="your-api-key"
+```
+
+## Run one task
+
+Save this as `eval.mts` in your TypeScript project.
+
+```ts eval.mts
+import { hosted } from "@evolvingmachines/evolve";
+
+const evolve = hosted();
+
+const job = await evolve.jobs.start({
+  datasets: [{
+    name: "harbor-examples",
+    version: "1.0",
+    task_names: ["hello-world"],
+  }],
+  agents: [{ name: "codex", model_name: "gpt-5.6-luna" }],
+  max_trial_spend_usd: 0.50,
+  retry: { max_retries: 0 },
+});
+console.log("Job:", job.id);
+
+const finished = await evolve.jobs.watch(job.id);
+console.log("Status:", finished.status);
+console.log("Model cost:", finished.stats.cost_usd);
+
+for await (const trial of evolve.jobs.trials(job.id)) {
+  console.log(trial.task_name, trial.status, trial.reward);
+}
+
+const archive = await evolve.jobs.download(job.id, { to: "./results" });
+console.log("Saved:", archive);
+```
+
+### 1. Submit
+
+`start()` returns the accepted job. It does not wait for the trial.
+
+### 2. Wait
+
+`watch()` follows progress and returns the terminal job.
+
+### 3. Inspect
+
+Read each trial's status and reward. A completed job can contain failed trials.
+
+### 4. Keep the results
+
+`download()` saves a verified archive and returns its path.
+
+The example sets a $0.50 cap for the trial and disables configured infrastructure retries. Provider capacity waits are handled separately. These settings limit the example's work; they do not guarantee a passing result.
+
+## Show progress
+
+Use an event callback while awaiting completion:
+
+```ts
+const finished = await evolve.jobs.watch(job.id, {
+  onEvent: (event) => console.log(event.seq, event.type),
+});
+```
+
+Or consume events directly:
+
+```ts
+for await (const event of evolve.jobs.watch(job.id)) {
+  console.log(event.type, event.data);
+}
+const finished = await evolve.jobs.get(job.id);
+```
+
+Choose one consumption style for each watch handle.
+
+## Read a trial
+
+```ts
+const page = await evolve.jobs.trials(job.id, { limit: 1 });
+const trial = page.items[0];
+
+if (trial) {
+  const trajectory = await evolve.trials.artifact(trial.id, "trace-atif");
+  const files = await evolve.trials.files(trial.id);
+  console.log(trajectory, files.items);
+}
+```
+
+**[Configure a job](/sdk-reference/jobs)**
+
+Models, task filters, attempts, limits, and analysis.
+
+**[Inspect files](/sdk-reference/filesystem)**
+
+Live files, saved captures, logs, and processes.

package/skills/evolve-evals/references/sdk-reference/agents.md

@@ -0,0 +1,75 @@
+---
+title: "Custom agents"
+description: "Register your own harness and use it in a job arm."
+---
+
+[Method reference: calls, parameters, and response fields](/sdk-reference/methods/agents).
+
+Use `agents()` for your own agent registrations. To discover built-in harnesses, use [meta](/sdk-reference/meta).
+
+## Register an agent
+
+Provide a local source directory or an install script, plus the command that runs your agent.
+
+```ts TypeScript
+import { agents } from "@evolvingmachines/evolve";
+
+const agent = await agents().create({
+  name: "my-agent",
+  directory: "./my-agent",
+  run_command: "python agent.py",
+});
+```
+
+```python Python
+from evolve import agents
+
+agent = await agents().create(
+    name="my-agent",
+    directory="./my-agent",
+    run_command="python agent.py",
+)
+```
+
+The example assumes `./my-agent` contains that runnable program. See the [custom-agent contract](/core-concepts/agents) for how it receives a task and produces output.
+
+| Field | Required | Purpose |
+| --- | --- | --- |
+| `name` | Create only | Registration name used by job arms |
+| `run_command` | Yes | Command that starts the agent |
+| `directory` | One source | Local source folder, archived for upload |
+| `install_script` | One source | Script used to install the agent |
+| `env` | No | Declared non-secret environment map |
+| `org` | No | Owning team; overrides the client default |
+
+Choose exactly one of `directory` and `install_script`. Discover naming, reserved environment keys, and size limits through `meta().agent_registration`. Store credentials as [secrets](/sdk-reference/secrets).
+
+## Use the registration
+
+Name it in a job's `agents` list just like a built-in harness:
+
+```json
+{
+  "name": "my-agent",
+  "model_name": "your-model"
+}
+```
+
+Use the model your custom agent is written to run. Registration does not make every model compatible with its implementation.
+
+## Read or replace
+
+| Action | TypeScript | Python | Returns |
+| --- | --- | --- | --- |
+| List registrations | `list({scope, limit, cursor})` | `list(scope=..., limit=..., cursor=...)` | Paginated handle |
+| Read one | `get(name)` | `get(name)` | Agent registration |
+| Create or replace | `upsert(name, input)` | `upsert(name, run_command=..., ...)` | Agent registration |
+| Delete | `delete(name)` | `delete(name)` | No content |
+
+List scopes are `my`, `shared`, and `org`. Upsert accepts the same fields as create except `name`, which is its first argument.
+
+**Note:**
+
+Upsert is a full replacement. Include every setting you want to retain; omitting `env` clears it. It avoids the gap created by deleting and then registering again.
+
+Deleting a registration does not rewrite the agent identity already recorded on past jobs.

package/skills/evolve-evals/references/sdk-reference/analyses.md

@@ -0,0 +1,125 @@
+---
+title: "Analyses"
+description: "Analyze trial traces, then inspect the result and the analyzer's own run."
+---
+
+**Note:**
+
+For every method’s inputs, return values, and language differences, see the [analyses method reference](/sdk-reference/methods/analyses).
+
+Analysis asks an agent to read a trial's evidence against a rubric. It produces criterion outcomes and explanations. It does not replace the verifier's reward.
+
+```text
+Trial trace + task + rubric
+             │
+             ▼
+        Analyzer run
+             │
+             ▼
+ Summary + criterion outcomes + evidence
+```
+
+## Start an analysis
+
+Start work through the **jobs** client. Read analyzer runs through the **analyses** client.
+
+```ts TypeScript
+import { jobs, analyses } from "@evolvingmachines/evolve";
+
+await jobs().analyze(jobId, { failing: true });
+const job = await jobs().watchAnalysis(jobId);
+console.log(job.stats.analysis);
+```
+
+```python Python
+from evolve import jobs, analyses
+
+await jobs().analyze(job_id, failing=True)
+job = await jobs().watch_analysis(job_id)
+print(job.stats.get("analysis"))
+```
+
+Manual analysis requires a terminal job. It returns immediately after queuing work. Only one analysis wave can run for that job at a time.
+
+To analyze trials as they finish, pass `analyze: {}` / `analyze={}` when starting the job. Wait for job completion before calling the analysis watch.
+
+### Configuration
+
+The field names are the same in both languages. TypeScript passes an object; Python uses keyword arguments on `analyze()` or a dictionary inside job creation.
+
+| Field | Purpose |
+| --- | --- |
+| `agent` | Agent the analyzer runs on; default `claude` |
+| `model_name` | Analyzer model, one of that agent's models |
+| `reasoning_effort` | Effort that agent accepts |
+| `sandbox_provider` | Analyzer's sandbox provider |
+| `rubric` | `{criteria: [{name, description, guidance}, ...]}` |
+| `prompt` | Replacement prompt template text |
+| `n_concurrent` | Requested parallel analyses; integer 1–150, also bounded by team quota |
+| `passing` | Only scored trials with primary reward exactly 1 |
+| `failing` | Other analyzable trials |
+| `n_trials` | Positive cap after selection |
+| `trial_ids` | Explicit trial ids from this job; manual analysis only |
+
+`passing` and `failing` cannot both be true. Cancelled trials are excluded. Explicit ids are filtered before the cap; unknown, duplicate, or empty ids are refused.
+
+### Analysis watch options
+
+| TypeScript | Python | Purpose |
+| --- | --- | --- |
+| `onStats` | `on_stats` | Called with the job when analysis tally changes |
+| `pollIntervalMs` | `poll_interval_s` | Initial interval; default 2000 ms / 2 s |
+| `signal` | `timeout_s` | Stop waiting / bound the Python wait |
+
+Polling slows to at most 30 seconds while the tally stays unchanged. Call the watch after starting analysis; a job never analyzed can have a null tally indefinitely.
+
+## Read current defaults
+
+```ts TypeScript
+const defaults = await analyses().defaults();
+console.log(defaults.model_name, defaults.rubric, defaults.prompt);
+```
+
+```python Python
+defaults = await analyses().defaults()
+print(defaults["model_name"], defaults["rubric"], defaults["prompt"])
+```
+
+The response includes `agent`, `model_name`, `rubric`, `prompt`, `reasoning_effort`, and `sandbox_provider`. The prompt is the editable template text.
+
+A custom analyze prompt may use `{trial_path}`, `{task_section}`, and `{criteria_guidance}`. The required result schema is appended by the platform. See [analysis concepts](/core-concepts/analyze) for rubric design.
+
+## Read results
+
+```ts TypeScript
+for await (const result of analyses().list({ job: jobId })) {
+  console.log(result.id, result.status, result.checks);
+}
+```
+
+```python Python
+async for result in analyses().list(job=job_id):
+    print(result["id"], result["status"], result["checks"])
+```
+
+List options: `scope`, `job`, `status` list, `limit`, `cursor`. Status values are `queued`, `running`, `completed`, `failed`.
+
+The latest analysis also appears on `trial.analysis`. Each criterion reports `pass`, `fail`, `not_applicable`, or `unknown`, with an explanation and evidence. Evolve derives no verdict from them; compute what you need from the criteria.
+
+## Inspect the analyzer run
+
+| Method | TypeScript | Python |
+| --- | --- | --- |
+| List runs | `list(options)` | `list(...)` |
+| Read defaults | `defaults()` | `defaults()` |
+| Download run | `download(analysisId, { to })` | `download(analysis_id, to=...)` |
+| Browse sandbox files | `filesystem(analysisId)` | `filesystem(analysis_id)` |
+| Read one analysis directly | `get(analysisId)` | Use list results or `trial.analysis` |
+| Read analyzer transcript | `transcript(analysisId, { since })` | Not exposed |
+| Read raw stored artifact | `artifact(analysisId, stream)` | Not exposed |
+
+`analysisId` identifies the analyzer run, not the trial it read. `since` is an inclusive nonnegative event index; the transcript returns `events`, `total`, run metadata, and separate `gateway_calls`.
+
+TypeScript artifact selectors are `trace-stdout`, `trace-stderr`, and `agent-home`. The first two return text or null; `agent-home` returns a file map or null.
+
+Downloads return a wrapper-trial archive. See [filesystem and download options](/sdk-reference/filesystem).

package/skills/evolve-evals/references/sdk-reference/auth.md

@@ -0,0 +1,171 @@
+---
+title: "Identity and teams"
+description: "Read your identity, choose a team, and manage invitations."
+---
+
+[Method reference: calls, parameters, and response fields](/sdk-reference/methods/auth).
+
+Import `auth` for identity and `orgs` for teams. `hosted().orgs` is also available; `hosted().auth` is not.
+
+## Check your identity
+
+```ts TypeScript
+import { auth, orgs } from "@evolvingmachines/evolve";
+
+const identity = await auth().status();
+console.log(identity.user_id, identity.email, identity.key.label);
+```
+
+```python Python
+from evolve import auth, orgs
+
+identity = await auth().status()
+print(identity.user_id, identity.email, identity.key.label)
+```
+
+The response includes user id, email, and metadata for the API key used. It does not return the key's secret value. `status()` is the auth client's only method.
+
+## Manage API keys over HTTP
+
+Create keys in the [dashboard](https://dashboard.evolvingmachines.ai/api-keys). Choose **Full access** to submit or change work, or **Read-only** to inspect it. Write requests with a read-only key return `403 read_only_key`; full access still respects your account's permissions.
+
+Key listing and revocation are HTTP operations, without corresponding methods in either SDK. These examples use the same `EVOLVE_API_KEY` as the clients:
+
+```bash
+EVOLVE_URL="https://dashboard.evolvingmachines.ai"
+```
+
+### List your keys
+
+```bash
+curl -sS "$EVOLVE_URL/api/auth/keys?limit=50" \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+Returns `{ items, nextCursor, hasMore }`, newest first. `limit` defaults to `50`, with a maximum of `200`; pass `nextCursor` as the next request's `cursor`.
+
+Each item has `id`, `label`, `created_at`, and `last_used_at`. Secret values are never returned; `last_used_at` is currently null. Only your own account keys are listed, excluding credentials created for individual runs.
+
+### Revoke a key
+
+Set `$KEY_ID` to an `id` from the list, not the secret key value. Use a full-access key belonging to the same account.
+
+```bash
+curl -sS -X DELETE \
+  "$EVOLVE_URL/api/auth/keys/$KEY_ID" \
+  -H "Authorization: Bearer $EVOLVE_API_KEY"
+```
+
+Success returns `204` with no body. An unknown key, another account's key, or a run credential returns `404 invalid_api_key`.
+
+Revocation removes the key, but API servers can continue accepting a cached credential for up to 5 minutes.
+
+## Choose a team
+
+```ts TypeScript
+const teams = await orgs().list();
+for (const team of teams) console.log(team.slug, team.role);
+const team = await orgs().get("my-team");
+console.log(team.quota, team.usage);
+```
+
+```python Python
+teams = await orgs().list()
+for team in teams:
+    print(team.slug, team.role)
+team = await orgs().get("my-team")
+print(team.quota, team.usage)
+```
+
+`list()` returns an array/list, not a paginated handle. `get` accepts an organization slug or id. Detail includes membership count, quotas, and usage.
+
+Pass `org` in [client configuration](/sdk-reference/index#configure-once) or a supported create call to make that team own the resource.
+
+## Team methods
+
+| Action | TypeScript | Python | Returns |
+| --- | --- | --- | --- |
+| List your teams | `list()` | `list()` | Organizations |
+| Read one team | `get(org)` | `get(org)` | Organization detail |
+| Create a team | `create(name, { displayName })` | `create(name, display_name=...)` | Organization |
+| Create invite token | `invite(org)` | `invite(org)` | Invite metadata and token |
+| Join with token | `join(token)` | `join(token)` | Organization and `already_member` |
+| Read members | `members(org)` | `members(org)` | Member list |
+
+`name` in `create` is the slug; display name is optional. Creating an invite requires an organization owner. `invite` uses the server's defaults and takes no expiry/use-limit options in these SDKs.
+
+Team membership enables shared access to team-owned work. It does not grant every creator-only action, such as managing a job's external shares or deleting its record. See [teams](/core-concepts/teams) and [sharing](/core-concepts/sharing).
+
+## Manage teams over HTTP
+
+The operations below are not methods on either SDK client. Prefix each path with `https://dashboard.evolvingmachines.ai` and send `Authorization: Bearer $EVOLVE_API_KEY`. Writes require a full-access key. Send JSON bodies with `Content-Type: application/json`.
+
+Replace `{org}` with the team's slug or id. Get `{userId}` from `orgs().members(org)`; use the `user_id` returned by `auth().status()` when leaving your own membership. Get `{inviteId}` from an invitation's `invite_id`.
+
+### Rename or delete a team
+
+An owner can update the slug, display name, or both:
+
+**`PATCH`** `/api/orgs/{org}`
+
+```json
+{
+  "display_name": "Acme Lab"
+}
+```
+
+Optional `slug`: 1–48 lowercase letters, digits, or hyphens; no leading/trailing hyphen or reserved name. `display_name`: 1–120 characters after trimming. Success returns the updated organization; a taken slug returns `409 org_slug_taken`.
+
+`DELETE /api/orgs/{org}` deletes the team and returns `{ deleted: true, org_id }`. It requires an owner and returns `409 org_in_use` while jobs or datasets remain, with their counts in `details`.
+
+### Change a role, remove a member, or leave
+
+An owner can set a member's role to `owner` or `member`:
+
+**`PATCH`** `/api/orgs/{org}/members/{userId}`
+
+```json
+{
+  "role": "owner"
+}
+```
+
+Success returns the updated member. `DELETE` on the same path removes that member and returns `{ removed: true, user_id, role }`. Owners can remove others; members can remove themselves to leave.
+
+Demoting or removing the last owner returns `409 org_last_owner`. Promote another owner first. A missing member returns `404 org_member_not_found`.
+
+### Set invitation limits
+
+An owner can create a token with a chosen lifetime and use limit:
+
+**`POST`** `/api/orgs/{org}/invites`
+
+```json
+{
+  "expires_in_sec": 86400,
+  "max_uses": 1
+}
+```
+
+| Field | Values and default |
+| --- | --- |
+| `expires_in_sec` | Integer from `60` to `7776000` (90 days), or `null` for no expiry. Omitted: 7 days. |
+| `max_uses` | Positive integer, or `null` for unlimited uses. Omitted: unlimited. |
+
+Success returns `201` with invitation metadata and `token`. The token is returned only at creation. CLI and SDK `invite` calls expose neither option and use these defaults.
+
+Joining an existing membership returns `already_member: true` without consuming a use. For a new member, an expired, revoked, or exhausted token returns `410 invite_invalid`; an unknown token returns `404 invite_not_found`.
+
+### List or revoke invitations
+
+Both operations require an owner:
+
+**`GET`** `/api/orgs/{org}/invites`
+
+Returns `{ items }`, newest first. Items contain `invite_id`, `expires_at`, `max_uses`, `uses`, `revoked_at`, and `created_at`; tokens are not included.
+
+**`DELETE`** `/api/orgs/{org}/invites/{inviteId}`
+
+Returns the invitation metadata with `revoked_at` set. Repeating the request leaves it revoked. This prevents new joins without removing existing members. An unknown invitation returns `404 invite_not_found`.
+
+Personal organizations cannot be renamed or deleted, have their membership changed, or issue invitations. These actions return `403 org_personal_immutable`.