Tasks and context

Create one active Task Guard task per agent session, retrieve its current contract at the start of each work cycle, record meaningful milestones, and complete or transition it explicitly.

Start a task#

Use POST /v1/task-guard/tasks. POST /v1/task-guard/sessions is an alias with the same request and response.

Requires task_guard:tasks:write.

curl -X POST "https://api.maetra.io/v1/task-guard/tasks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ref": "conversation_01JY8Q",
    "title": "Ship approval flow",
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "agent_name": "release-agent",
    "host_type": "CUSTOM_API",
    "integration_mode": "ADVISORY",
    "confirmation_capable": true,
    "effect_reporting_capable": true,
    "idempotency_key": "task-start-01JY8Q"
  }'

session_ref, objective, and either idempotency_key or direct_user_event_id are required. Reusing the same event key with a different request returns a conflict.

{
  "ok": true,
  "session_id": "tgs_01JY8R",
  "session_ref": "conversation_01JY8Q",
  "task": {
    "id": "tgt_01JY8S",
    "sequence": 1,
    "status": "active",
    "title": "Ship approval flow",
    "completed_at": null
  },
  "contract_version": 1,
  "anchor": {
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "decisions": [],
    "open_questions": [],
    "accepted_expansions": [],
    "anchor_hash": "sha256:…",
    "anchor_text": "…"
  },
  "host": {
    "type": "custom_api",
    "integration_mode": "advisory"
  },
  "next_action": "Call get_task_context after compaction and check_task_alignment before meaningful actions."
}

Starting a new objective in an existing session supersedes the prior active task. A subsequent task or contract revision requires a direct_user_event_id. In ENFORCED mode, task transitions must use the trusted host user-event endpoint below.

Retrieve the active context#

Use either endpoint:

GET /v1/task-guard/tasks/{taskId}
GET /v1/task-guard/tasks/{taskId}/context

Both require task_guard:tasks:read and return the current task, contract version, anchor, host mode, and next_action.

curl "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/context" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Refresh context at the start of a new work cycle, after context compaction or restart, and whenever an alignment check returns CONTEXT_REFRESH_REQUIRED.

Record progress#

Use POST /v1/task-guard/tasks/{taskId}/progress after a meaningful milestone.

Requires task_guard:tasks:write.

{
  "summary": "API route and validation are complete.",
  "completed": ["Implemented the refund approval endpoint"],
  "next_steps": ["Connect the dashboard form", "Run integration tests"],
  "new_dependencies": [],
  "open_questions": [],
  "current_step": "Implement dashboard integration",
  "idempotency_key": "progress-01JY9A"
}

The response returns the new contract_version, current step, task ID, and next action. Check every item in new_dependencies with the alignment endpoint before acting on it.

Pause, resume, or cancel#

These lifecycle endpoints require task_guard:tasks:write and no request body:

POST /v1/task-guard/tasks/{taskId}/pause
POST /v1/task-guard/tasks/{taskId}/resume
POST /v1/task-guard/tasks/{taskId}/cancel

Pausing or cancelling revokes active alignment grants. Resuming returns the task to active. Each response contains task_id, status, and updated_at.

Complete the task#

Use POST /v1/task-guard/tasks/{taskId}/complete after the objective and success criteria are satisfied.

Requires task_guard:tasks:write.

{
  "summary": "Refund approvals are implemented and verified end to end.",
  "completion_event_id": "complete-01JY9Z"
}

{
  "ok": true,
  "task_id": "tgt_01JY8S",
  "status": "completed",
  "summary": "Refund approvals are implemented and verified end to end.",
  "completed_at": "2026-07-20T13:42:18.000Z"
}

Trusted host user events#

POST /v1/task-guard/sessions/{sessionId}/user-events starts a subsequent task or revises the active task from a verified direct-user instruction. It accepts the same fields as the start request and additionally requires direct_user_event_id.

This endpoint requires:

task_guard:confirmations:write
an API key marked as a trusted Task Guard confirmation credential
a session_ref matching the referenced Task Guard session

Use this endpoint for task starts and transitions in ENFORCED integrations.