---
title: "Bulk"
method: POST
path: "/api/v2/bulk"
tags: ["Bulk"]
---

# Bulk

`POST /api/v2/bulk`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/bulk`
- Auth: API key in header `API-Key` and API key in header `API-Pin`

Many writes of mixed types in one request. Each item succeeds or fails on
its own (unless `atomic`); links between items in the batch resolve.

## Headers

- `Idempotency-Key` string
- `X-OW-Agent` string

## Request body

- object
  - `items` object[], required: Up to 1000 writes of any types. An item with an `id` creates or replaces that element; without one, it creates. Items may link to each other in the same batch.
    - `type` string, required: The element type, e.g. character.
    - `element` object, required: The element's fields, as for a create.
  - `atomic` boolean: `true`: if any item fails, nothing is written. The response still lists each item as it would have gone.

## Response `200`

Always 200 once the batch is read: per-item statuses in `items`, and `errors` is true when any item failed. A contributor or guest's item on an element someone else created fails 403 not_author.

- BulkResult
  - `errors` boolean, required: True when any item failed.
  - `items` object[], required: One result per request item, in the same order.
    - `status` integer, required: 201 created, 200 replaced, or the item's error status.
    - `id` string, uuid, nullable, required
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `error` object: Only on a failed item: the same object a standalone error's `error` holds.
      - `type` 'api_error' | 'authentication_error' | 'idempotency_error' | 'invalid_request' | 'not_found' | 'permission_error' | 'rate_limited', required
      - `code` 'already_member' | 'api_error' | 'apply_failed' | 'ask_failed' | 'ask_unavailable' | 'character_hidden' | 'character_taken' | 'file_too_large' | 'files_full' | 'gone' | 'guest_not_supported' | 'id_conflict' | 'idempotency_error' | 'idempotency_in_flight' | 'invalid_credentials' | 'invalid_link' | 'invalid_request' | 'key_revoked' | 'known_of_not_writable' | 'media_unavailable' | 'not_author' | 'not_found' | 'owner_only' | 'payload_too_large' | 'permission_error' | 'pin_required' | 'player_role_fixed' | 'precondition_failed' | 'quota_exceeded' | 'rate_limited' | 'removal_in_flight' | 'resync_required' | 'server_busy' | 'storage_full' | 'too_many_requests' | 'upload_pending' | 'view_as_owner_only' | 'world_full', required: Stable, machine-readable (e.g. invalid_link, id_conflict).
      - `message` string, required
      - `param` string, nullable, required: The offending field or parameter, when there is one.
      - `doc_url` string, required

## Other responses

- `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise).
- `403`: The credential is valid but lacks the scope: a read key on a write route (permission_error).
- `409`: An Idempotency-Key was reused with a different body (idempotency_error), or a request with this Idempotency-Key is still in flight (idempotency_in_flight; retry after Retry-After).
- `422`: Invalid request: unknown or read-only field, bad value, unknown query parameter, over-long text, extensions over the size cap (invalid_request); `param` names the culprit.
- `429`: Too many failed PIN attempts; see the Retry-After header (rate_limited). Or too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds.
- `503`: The server is busy: every request slot stayed full for 10 s (code server_busy, type api_error). Retry after the Retry-After header's seconds.

## Changes

- **2026-10-20** `78df39c4c62e`: 7 warning
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `403`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `409`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - …3 more
- **2026-10-20** `4dd5b1cd0687`: 14 warning
  - added the new `character_taken` enum value to the `error/code` response property for the response status `401`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `403`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `409`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - …10 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/bulk/post.md)

---

[API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/1752622ae8ce?raw)