---
title: "Update team quest (admin)"
method: PATCH
path: "/api/admin/teams/{teamId}/quests/{questId}"
tags: ["Admin", "Teams"]
---

# Update team quest (admin)

`PATCH /api/admin/teams/{teamId}/quests/{questId}`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/admin/teams/{teamId}/quests/{questId}`
- Auth: HTTP bearer

Gate: canManageTeam (owner, editor, legacy admin, platform admin/superadmin). Viewers and outsiders get 403; anonymous 401. Every body field is optional; scalar-only bodies behave exactly as before. `steps` uses the same item shape as POST create: omitted leaves the quest's steps untouched, `[]` clears them, a list replaces them. Replacement runs in one transaction with the scalar edits under a row lock on the quest (scoped to quest id + team); step ids are always server-generated and `order` defaults to the item's index. If `steps` is supplied (including `[]` or an unchanged list) and ANY user has started the quest (a UserQuestStatus row exists), the request is refused with 409 CONFLICT and nothing is written, because deleting a QuestStep cascades to user step progress. Scalar-only edits stay allowed with progress. Response is `Cache-Control: private, no-store`.

## Path parameters

- `teamId` string, required
- `questId` string, required

## Request body

- object
  - `title` string
  - `description` string
  - `points` integer
  - `iconName` string
  - `category` 'ONBOARDING' | 'SOCIAL' | 'ENGAGEMENT' | 'PURCHASE' | 'DAILY' | 'WEEKLY' | 'SPECIAL_EVENT'
  - `cadence` string, nullable
  - `isRepeatable` boolean
  - `cooldownHours` integer, nullable
  - `order` integer
  - `isActive` boolean
  - `startsAt` string, date-time, nullable
  - `endsAt` string, date-time, nullable
  - `steps` object[]: Omitted = keep current steps; [] = clear; list = replace atomically. 409 CONFLICT once any user has started the quest.
    - `title` string, required: Trimmed; whitespace-only is rejected with 400.
    - `description` string
    - `order` integer: Defaults to the item's index.
    - `points` integer: Defaults to 0.
    - `stepCode` string, nullable

## Response `200`

{ success, data: TeamQuest } — the updated quest with steps ordered by `order` asc.

- object
  - `success` boolean
  - `data` object
    - `id` string, required
    - `title` string, required
    - `description` string
    - `points` integer
    - `iconName` string
    - `category` string
    - `isRepeatable` boolean
    - `cooldownHours` integer, nullable
    - `isActive` boolean
    - `order` integer
    - `cadence` string, nullable
    - `scope` string
    - `teamId` string, nullable
    - `isTemplate` boolean
    - `sourceTemplateId` string, nullable
    - `startsAt` string, date-time, nullable
    - `endsAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `steps` object[], required
      - `id` string, required
      - `title` string, required
      - `description` string, required
      - `order` integer, required
      - `points` integer, required
      - `stepCode` string, nullable, required

## Other responses

- `400`: { success: false, error, code: VALIDATION_ERROR } — malformed body or step (blank title, non-integer order/points). A failed transaction (nothing written) is also 400 with `error` and no `code`, preserving the existing route behavior.
- `401`: { success: false, error, code: UNAUTHORIZED }
- `403`: { success: false, error, code: FORBIDDEN }
- `404`: { success: false, error, code: NOT_FOUND } — quest is not a non-template quest of this team (including when deleted mid-request).
- `409`: { success: false, error, code: CONFLICT } — `steps` supplied but a UserQuestStatus exists for the quest. Nothing was written; retry without `steps` for scalar edits.
- `500`: { success: false, error, code: INTERNAL_ERROR }

## Changes

- **2026-11-18** `6de639c52609`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/admin/teams/:teamId/quests/:questId/patch.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
