---
title: "Open (create or attach) a mission"
method: POST
path: "/preview/missions"
tags: ["missions"]
---

# Open (create or attach) a mission

`POST /preview/missions`

## Request

- Base URL: `https://autoresearch.sfcompute.com`
- URL: `https://autoresearch.sfcompute.com/preview/missions`
- Auth: HTTP bearer

Open (create or attach) a mission: the investigation-level grouping over nodes, jobs, commands, and artifacts, with an org-unique human-readable name. Use one per question you are answering ("serve llama-70b under $X"), and open it FIRST - before the first create_node or submit_job - then pass mission: "<name>" on create_node / run_command / submit_job / submit_jobs / export_file: their work and cost roll up on the mission's page and get_mission, telemetry arrives labeled by mission (query_metrics / query_logs / search_traces), starter charts draw automatically, and save_chart adds the views worth keeping. The response's url is the human's window on the work - hand it over early, not with the final report. The page is org-private (sign-in, workspace visibility): the url discloses nothing outside the org. Create-or-attach by name: reconnecting (or a fleet of parallel agents) reuses the same name and lands in the same mission. Names are permanent org-wide handles - pick a meaningful one. Missions are optional and never required; they never cap or gate anything (workspaces are policy; missions are reporting). Declare the verdict with finish_mission when the question is answered. If the org cannot start paid work right now (no credit, an unpaid invoice, a suspended org), the response carries a `warning` naming the blocker and its cure - surface it to the human WITH the url, so they fix billing before watching an empty page.

## Query parameters

- `workspace` string

## Request body

- object
  - `name` string, nullable: Mission name: lowercase letters, digits, '-' (1-63 chars), unique in your organization and PERMANENT (missions are never deleted or renamed). Pick a meaningful one - it is the receipt's handle, the URL, and the invoice line. An existing name attaches instead of creating (create-or-attach): reconnecting agents and parallel sessions share one mission by using one name. Omitted = auto-generated.
  - `title` string, nullable: One-line human description, shown beside the name on the mission page. Ignored when attaching to an existing mission.

## Response `200`

The capability's JSON result.

- Result: The capability's result: the same object the MCP tool returns as structuredContent. Resources carry an `object` type discriminator and an immutable id; money is integer micro-dollars in `*_usd_micros` fields.
  - `object` string: The resource type, when the result is one resource.

## Other responses

- `400`: Malformed request: bad JSON, a parameter that does not parse, or a value outside its range. Code `invalid`.
- `401`: No bearer token, or one this API cannot verify. Code `unauthenticated`.
- `403`: Authenticated, but the token's scopes or the account's role do not reach this operation. The message names the scope word to request. Code `forbidden`.
- `404`: No such route. Code `not_found`; the body names the OpenAPI document.
- `422`: A well-formed request the platform declined: no such node, a cap reached, a state that forbids the move. The message says which, and what to do instead. Code `refused`.
- `429`: Over this door's per-customer budget. Wait `Retry-After` seconds. Code `rate_limited`.
- `500`: Our fault. Retry; if it persists, quote the request-id. Code `internal`.

---

[API](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api.md) · [All operations](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/givemeanode/apis/autoresearch-customer-api/revisions/f88dcb70ac6c?raw)