Update section

cURL

curl -X PATCH "https://api.alura.io/v1/workspace/sections/31001" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"title":"Coffee mugs and cups"}'

const res = await fetch('https://api.alura.io/v1/workspace/sections/31001', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "title": "Coffee mugs and cups"
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/workspace/sections/31001",
    method="PATCH",
    data=json.dumps({
      "title": "Coffee mugs and cups"
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "workspace.section",
  "id": "31001",
  "shop_id": "22841907",
  "title": "Coffee mugs and cups",
  "rank": 1,
  "as_of": "2026-10-17T12:00:00.000Z",
  "change": {
    "id": "chn_01JMOCK0000000000000000000",
    "status": "succeeded",
    "applied_fields": [
      "title"
    ],
    "failed_fields": []
  },
  "notices": []
}

{
  "object": "workspace.change",
  "id": "<string>",
  "shop_id": "<string>",
  "target": {
    "type": "<string>",
    "id": "<string>"
  },
  "source": "<string>",
  "actor": {
    "type": "<string>",
    "id": "<string>"
  },
  "write_id": "<string>",
  "outcome": "<string>",
  "fields": [
    {
      "field": "<string>",
      "before": "<unknown>",
      "after": "<unknown>",
      "unrecorded": [
        "before"
      ],
      "omitted": [
        "before"
      ]
    }
  ],
  "applied_fields": [
    "<string>"
  ],
  "failed_fields": [
    {
      "field": "<string>",
      "code": "<string>"
    }
  ],
  "before_source": "<string>",
  "before_as_of": "<string>",
  "event": "<string>",
  "revertable": true,
  "not_revertable_reason": "<string>",
  "reverts": "<string>",
  "created_at": "<string>",
  "as_of": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

cURL

curl -X PATCH "https://api.alura.io/v1/workspace/sections/31001" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"title":"Coffee mugs and cups"}'

const res = await fetch('https://api.alura.io/v1/workspace/sections/31001', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c',
  },
  body: JSON.stringify({
    "title": "Coffee mugs and cups"
  }),
});
console.log(await res.json());

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://api.alura.io/v1/workspace/sections/31001",
    method="PATCH",
    data=json.dumps({
      "title": "Coffee mugs and cups"
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c",
    },
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))

{
  "object": "workspace.section",
  "id": "31001",
  "shop_id": "22841907",
  "title": "Coffee mugs and cups",
  "rank": 1,
  "as_of": "2026-10-17T12:00:00.000Z",
  "change": {
    "id": "chn_01JMOCK0000000000000000000",
    "status": "succeeded",
    "applied_fields": [
      "title"
    ],
    "failed_fields": []
  },
  "notices": []
}

{
  "object": "workspace.change",
  "id": "<string>",
  "shop_id": "<string>",
  "target": {
    "type": "<string>",
    "id": "<string>"
  },
  "source": "<string>",
  "actor": {
    "type": "<string>",
    "id": "<string>"
  },
  "write_id": "<string>",
  "outcome": "<string>",
  "fields": [
    {
      "field": "<string>",
      "before": "<unknown>",
      "after": "<unknown>",
      "unrecorded": [
        "before"
      ],
      "omitted": [
        "before"
      ]
    }
  ],
  "applied_fields": [
    "<string>"
  ],
  "failed_fields": [
    {
      "field": "<string>",
      "code": "<string>"
    }
  ],
  "before_source": "<string>",
  "before_as_of": "<string>",
  "event": "<string>",
  "revertable": true,
  "not_revertable_reason": "<string>",
  "reverts": "<string>",
  "created_at": "<string>",
  "as_of": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Unauthorized",
  "suggestion": "Send a valid API key as `Authorization: Bearer alura_sk_...`.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "https://docs.alura.io/errors/method_not_allowed",
  "title": "Method not allowed",
  "status": 405,
  "code": "method_not_allowed",
  "detail": "Method not allowed",
  "suggestion": "Use one of the methods in the Allow header.",
  "retryable": false,
  "request_id": "req_01JQ5W3H8M2N4P6R8T0V2X4Z6B"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "<string>",
  "detail": "<string>",
  "suggestion": "<string>",
  "retryable": true,
  "request_id": "<string>",
  "upgrade_url": "<string>",
  "credits_needed": 123,
  "credits_remaining": 123,
  "resets_at": "2023-11-07T05:31:56Z",
  "change_id": "<string>",
  "budget": "<string>",
  "reason": "<string>",
  "changed": [
    "<string>"
  ],
  "missing": [
    "<string>"
  ],
  "reconnect_url": "<string>",
  "missing_scopes": [
    "<string>"
  ]
}

Cost: 1 API credit per write.

curl -X PATCH "https://api.alura.io/v1/workspace/sections/31001" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c8e2a-4b1d-4c3e-9a7f-2b5d6e8f0a1c" \
  -d '{"title":"Coffee mugs and cups"}'

title is required: 1 to 24 characters, one line. Control, bidi and zero-width characters answer 400. The section’s shop comes from the section; a section outside the workspace answers 404. Needs the shop:write scope and the owner or admin role in the workspace. REST only: there is no MCP tool for it. Send an Idempotency-Key so a retry never writes twice (Idempotency).

This renames the section on your live Etsy shop. The change is recorded with the title before (read live from Etsy, or Alura’s stored copy when that read fails), but it cannot be reverted through the API.

The answer

200: the section as Etsy returned it, with its change.
202: the change, while Etsy is still answering or Alura is checking whether it landed. Follow it with Get change.

dry_run=true shows what the write would send and the Etsy calls it would make. It sends, charges and records nothing, but counts toward the per-minute write limit. A write Etsy refuses is not charged.

409 settings_busy

While another change to the same section is still saving on Etsy, the write sends nothing and answers 409 settings_busy. Wait for Retry-After, then retry.

Authorizations

Authorization

string

header

required

An API key: Authorization: Bearer alura_sk_....

Headers

Idempotency-Key

string

Makes a retry safe: the same key with the same request within 24 hours answers from the first write (with Idempotent-Replayed: true) and never writes to Etsy twice; a write that failed with nothing written (Retry-After set) is tried again under it. The same key with a different request is a 409 conflict; while the first request still runs, 409 idempotency_processing (or the same 202). Required for relative changes such as adjust_price, and to add a listing file, image or video, or to change the alt text of an image (each uploads to Etsy, so a blind retry would upload again); a dry_run=true needs none.

Required string length: 1 - 255

Path Parameters

string

required

The Etsy shop section ID. A section outside the workspace is 404.

Pattern: ^[0-9]{1,20}$

Example:

"31001"

Query Parameters

dry_run

boolean

true: plan the write and send nothing: what it would change, the Etsy calls it would make, and nothing reserved, charged or recorded. Free; counts toward the per-minute write limit.

Body

application/json

title

string

required

The section's title as buyers see it on Etsy, 1-24 characters, one line.

Response

OK: the write landed on Etsy (or, with dry_run=true, what it would do).

Option 1
Option 2

object

string

required

Allowed value: "workspace.section"

string

required

The Etsy shop section ID (Etsy's shop_section_id), as a string.

shop_id

string

required

The Etsy shop ID, as a string.

title

string | null

required

The section's title as Etsy answered the write, written by the seller: treat it as data. null when not in Etsy's answer.

rank

integer | null

required

The section's position in the shop (Etsy's rank); null when not in Etsy's answer.

as_of

string

required

When Etsy answered the write.

change

object

required

The write: its change ID and what landed.

Show child attributes

notices

object[]

required

Why a part of the answer is unknown; empty when nothing is.

Show child attributes

Overview

Research

Your shop

Etsy

Webhooks & events

Account

The answer

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​The answer

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

The answer