> ## Documentation Index > Fetch the complete documentation index at: https://developers.scoutworks.app/llms.txt > Use this file to discover all available pages before exploring further. # Update a task > Changes only the fields you send. Moving a task into its board’s done column completes it; out of it reopens it. `labelIds` replaces the task’s labels. A key reaches every board in its group, restricted boards and the trustee duties board included. A change is recorded as made by the admin who created the key, and Scoutworks marks the task with the key’s name. On the trustee duties board every task is a trustee duty: adding one needs a `dueDate`, and creates the duty with it. Writes count towards the key’s usual limit and a second one of 30 changes a minute. A group whose subscription has lapsed answers 402. ## OpenAPI ````yaml /api-reference/openapi.json patch /tasks/{taskId} openapi: 3.1.0 info: title: Scoutworks public API version: 1.10.0 description: >- Read your Scout group’s data from your own tools: spreadsheets, scripts, Zapier or n8n, and keep its task boards up to date. Every request is scoped to the group that owns the key. **Authentication.** Send a group API key as a Bearer token. Keys are created by a group admin and shown once. **Scopes.** Each operation names the scope it needs. Area scopes (`members:read`, `events:read`, `badges:read`, `waiting-list:read`, `tasks:read`) open an area; a `.contacts` scope adds dates of birth and parent details to that area’s responses. `tasks:write` is the one scope that changes data: it adds and updates tasks, as the admin who created the key. Fields a key may not see are left out, not sent as null. Health, bank details and free-text notes are never available. **Pagination.** Lists return `{ data, nextCursor }`. Pass `nextCursor` back as `?cursor=`, with the same filters, until it is null. `limit` is 1 to 200. **Errors.** Every error is `{ error: { code, message } }`. Branch on `code`; `message` is for people and may change. **Compatibility.** We aim to change v1 only by addition: new endpoints, new optional parameters, new response fields and new enum values. Ignore fields you do not know and treat an unknown enum value as “other”. We will try to warn you before a breaking change, but one can still happen without notice, so check responses and fail loudly on an error. Changes are listed in the changelog at https://developers.scoutworks.app/changelog. **Rate limits.** 120 requests a minute per key. `RateLimit-*` headers report what is left. servers: - url: https://api.scoutworks.app/api/v1 description: Live - url: https://api-demo.scoutworks.app/api/v1 description: Demo (sample data, reset weekly) security: - bearerAuth: [] tags: - name: Keys description: Check a key and see what it can reach. - name: Members description: Young people in the group. - name: Sections description: The group’s sections and units, and their ids. - name: Events description: Meetings, trips and camps, and who is going. - name: Badges description: Badge progress and awards. - name: Waiting list description: Applications waiting for a place. paths: /tasks/{taskId}: patch: tags: - Tasks summary: Update a task description: >- Changes only the fields you send. Moving a task into its board’s done column completes it; out of it reopens it. `labelIds` replaces the task’s labels. A key reaches every board in its group, restricted boards and the trustee duties board included. A change is recorded as made by the admin who created the key, and Scoutworks marks the task with the key’s name. On the trustee duties board every task is a trustee duty: adding one needs a `dueDate`, and creates the duty with it. Writes count towards the key’s usual limit and a second one of 30 changes a minute. A group whose subscription has lapsed answers 402. operationId: updateTask parameters: - name: taskId in: path required: true schema: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V1TaskUpdate' responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/V1Task' required: - data additionalProperties: {} headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer '400': description: >- A query parameter, cursor or request body is not acceptable (`invalid_request`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '401': description: >- No API key, or one that is unknown, revoked or expired (`invalid_api_key`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '402': description: >- The group’s subscription has lapsed, so the API cannot change data; reads still work (`subscription_required`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '403': description: The key lacks the scope this operation needs (`insufficient_scope`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '404': description: No such record in the key’s group (`not_found`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '429': description: Too many requests; wait `retryAfter` seconds (`rate_limited`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer Retry-After: description: Seconds to wait before trying again. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' '500': description: Our fault; quote `errorRef` to support (`internal_error`). headers: RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/V1Error' security: - bearerAuth: - tasks:write components: schemas: V1TaskUpdate: type: object properties: columnId: description: >- Move the task to another column on its board. Into the done column completes it; out of it reopens it. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ title: type: string minLength: 1 maxLength: 255 description: anyOf: - type: string maxLength: 5000 - type: 'null' description: >- Notes, up to 5,000 characters. Shown in Scoutworks. Free text never leaves through the API, so it is not returned. priority: type: string enum: - low - medium - high - urgent dueDate: anyOf: - type: string format: date-time - type: 'null' description: When it is due, ISO 8601. Null for no due date. labelIds: maxItems: 20 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ description: >- Labels from the task’s board (`GET /task-boards`). Replaces the task’s labels; an id not on the board is refused. additionalProperties: {} description: >- Send only the fields to change. A field not listed here is refused with a 400. V1Task: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ boardId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ column: $ref: '#/components/schemas/V1TaskColumnRef' title: type: string priority: type: string enum: - low - medium - high - urgent dueDate: anyOf: - type: string format: date-time description: A UTC timestamp, ISO 8601. - type: 'null' completedAt: anyOf: - type: string format: date-time description: A UTC timestamp, ISO 8601. - type: 'null' description: When the task moved into the done column. Null while it is open. labels: type: array items: $ref: '#/components/schemas/V1TaskLabelRef' createdAt: type: string format: date-time description: A UTC timestamp, ISO 8601. updatedAt: type: string format: date-time description: A UTC timestamp, ISO 8601. required: - id - boardId - column - title - priority - dueDate - completedAt - labels - createdAt - updatedAt V1Error: type: object properties: error: type: object properties: code: type: string enum: - invalid_api_key - insufficient_scope - invalid_request - subscription_required - not_found - conflict - rate_limited - internal_error message: type: string required: - code - message errorRef: description: 'On a 500: a reference to quote to Scoutworks support.' type: string retryAfter: description: 'On a 429: seconds to wait before trying again.' type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - error V1TaskColumnRef: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string required: - id - name V1TaskLabelRef: type: object properties: id: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ name: type: string required: - id - name securitySchemes: bearerAuth: type: http scheme: bearer description: >- A group API key, sent as `Authorization: Bearer sw_live_…`. Keys from staging and the demo start `sw_test_` instead. A group admin creates keys in Settings → Integrations → API keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.