PATCH /v1/items/{item_id} — Atom Files Developers

← API referenceOrganize · API access unavailable

API REFERENCE / ORGANIZE

`PATCH` /v1/items/{item_id}

Rename or move a file or folder using an expected metadata revision.

Request fields

Location	Field	Type	Required	Description
Header	`Authorization`	string	Yes	Credential scoped to the authorized resource.
Header	`Content-Type`	string (media type)	Yes	application/json.
Path	`item_id`	string	Yes	Stable file or folder ID.
Header	`Idempotency-Key`	string	Yes	Stable retry identity.
Body	`expected_revision`	string	Yes	Revision observed before editing.
Body	`name`	string	No	New name.
Body	`parent_id`	string	No	Authorized destination folder.

Request example

Example request

PATCH /v1/items/file_789
Authorization: Bearer <scoped token>
Idempotency-Key: move-8427
Content-Type: application/json

{
  "expected_revision": "rev_007",
  "name": "invoice-final.pdf",
  "parent_id": "folder_124"
}

HTTP status codes

Status	Meaning
`202 Accepted`	Success response shown below.
`400 Bad Request`	Invalid name or destination.
`401 Unauthorized`	Missing, expired, or invalid credential.
`403 Forbidden`	Credential is valid but lacks the required scope or role.
`404 Not Found`	Item is not visible.
`409 Conflict`	Expected revision changed.
`429 Too Many Requests`	Rate limit reached; honor Retry-After when provided.
`503 Service Unavailable`	Service temporarily unavailable; retry safely.

Response fields

Field	Type	Example
`operation_id`	string	op_458
`item_id`	string	file_789
`status`	string	accepted

Response example

Example response

202 Accepted
Content-Type: application/json

{
  "operation_id": "op_458",
  "item_id": "file_789",
  "status": "accepted"
}

How it works

This endpoint changes metadata or placement, not immutable file bytes. An absent or stale expected revision must never silently overwrite a concurrent edit. Cross-provider moves may be asynchronous.