POST /v8/missions — Create a Governed Agent Mission

The POST /v8/missions endpoint is your entry point for every governed operation on the Praxa Integration Gateway. You submit a goal specification describing what you want the agent to accomplish alongside a resource budget that caps how much work it can do. The gateway records your intent durably, assigns a unique run ID, and hands the mission off to the private policy and broker plane for execution. Because the intake is idempotent, you can safely retry on network failure by re-sending the same Idempotency-Key.

The gateway returns 202 Accepted — not 201 — because recording the intake mission is itself a governed operation. Provider outcomes are verified asynchronously; the response confirms durable receipt, not completion.

Endpoint

POST /v8/missions

Required scope: missions:write Required headers:

Header	Description
`Authorization`	`Bearer <access_token>` — short-lived Ed25519 delegated OAuth token
`Idempotency-Key`	16–128 character alphanumeric key used to deduplicate retries
`Content-Type`	`application/json`

Request Body

goalSpec

object

required

The goal specification that describes what the mission should accomplish. The gateway treats this object as opaque and forwards it intact to the policy plane.

Show goalSpec properties

task

string

required

Natural language description of the task you want the agent to complete. Be specific — the policy plane uses this text to select capabilities, plan steps, and scope tool calls.Example: "Prepare the weekly revenue review for the EMEA region and send a summary to the team Slack channel."

resourceBudget

object

required

Hard limits that govern how many resources the mission may consume. All four fields are required. The mission transitions to failed if any limit is reached before the goal is satisfied.

Show resourceBudget properties

maximumSteps

integer

required

Maximum number of reasoning steps the agent may take. Must be ≥ 1. A step represents one cycle of the agent’s plan–act–observe loop.

maximumToolCalls

integer

required

Maximum number of tool invocations across all steps. Must be ≥ 0. Set to 0 to allow a planning-only mission with no tool use.

maximumElapsedMs

integer

required

Wall-clock time limit in milliseconds from the moment the mission begins executing. Must be ≥ 1. The mission is cancelled if this limit elapses regardless of step or tool call counts.

maximumParallelism

integer

required

Maximum number of concurrent branches the agent may execute simultaneously. Must be between 1 and 64. Set to 1 for fully sequential execution.

Example Request

curl -X POST https://your-gateway.example/v8/missions \
  -H "Authorization: Bearer $PRAXA_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "goalSpec": { "task": "Prepare the weekly review" },
    "resourceBudget": {
      "maximumSteps": 12,
      "maximumToolCalls": 8,
      "maximumElapsedMs": 120000,
      "maximumParallelism": 2
    }
  }'

import { PraxaClient } from "@praxa/sdk";

const client = new PraxaClient({ accessToken: process.env.PRAXA_ACCESS_TOKEN });

const mission = await client.createMission(
  {
    goalSpec: { task: "Prepare the weekly review" },
    resourceBudget: {
      maximumSteps: 12,
      maximumToolCalls: 8,
      maximumElapsedMs: 120_000,
      maximumParallelism: 2,
    },
  },
  crypto.randomUUID() // idempotencyKey
);

console.log(mission.runId);   // "018e2f3a-..."
console.log(mission.status);  // "running"

Response

Status: 202 Accepted The response body is a MissionProjection object. It reflects the initial state of the mission immediately after intake — the agent has not yet taken any steps.

runId

string (UUID)

required

Globally unique identifier for this mission run. Store this value — you will use it to poll status, stream events, send signals, and cancel.

status

string

required

The mission’s current lifecycle state immediately after intake. On a successful create this is almost always "running" or "waiting".

Value	Meaning
`running`	The agent is actively executing steps
`waiting`	The agent is paused waiting for a signal or external event
`succeeded`	The mission completed successfully
`failed`	The mission failed (budget exceeded, policy rejection, or unrecoverable error)
`cancelled`	The mission was cancelled via `POST /v8/missions/{runId}/cancel`

sequence

integer

required

A monotonically increasing version counter for this projection. Use this value to detect stale reads when polling concurrently.

steps

array

required

List of step summaries recorded so far. Each element contains a stepId (string) and a status (string). This array is empty immediately after mission creation.

Example 202 response

{
  "runId": "018e2f3a-7c14-7000-b1e2-4d3f8a20c911",
  "status": "running",
  "sequence": 1,
  "steps": []
}

Error Responses

All errors follow RFC 9457 Problem Details. Sensitive fields are redacted before the response leaves the gateway.

HTTP Status	Typical cause
`400 Bad Request`	Missing required fields, budget values out of range, or malformed JSON
`401 Unauthorized`	Missing or expired `Authorization` bearer token
`403 Forbidden`	Token lacks `missions:write` scope
`409 Conflict`	An existing mission was already recorded under the same `Idempotency-Key` with a different request body
`429 Too Many Requests`	Rate limit exceeded for your principal

SDK Equivalent

const mission = await client.createMission(input, idempotencyKey);

Parameter	Type	Description
`input`	`CreateMissionRequest`	Object containing `goalSpec` and `resourceBudget`
`idempotencyKey`	`string`	Unique key for deduplication; generate with `crypto.randomUUID()`

Returns: Promise<MissionProjection>

Overview

Missions

Capabilities & Memory

Skills & Traces

Context & World Model

POST /v8/missions — Create a Governed Agent Mission

Endpoint

Request Body

Example Request

Response

Error Responses

SDK Equivalent

​Endpoint

​Request Body

​Example Request

​Response

​Error Responses

​SDK Equivalent

Endpoint

Request Body

Example Request

Response

Error Responses

SDK Equivalent