---
title: "Run up to 20 public GET reads in one request"
method: POST
path: "/api/batch"
tags: ["batch"]
---

# Run up to 20 public GET reads in one request

`POST /api/batch`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/batch`
- Auth: none required

Public, no auth. Submit a bounded list (1..20) of GET sub-requests to the allowlisted PUBLIC read endpoints (`/api/events/upcoming`, `/api/events/get`, `/api/floor10/donations`) and get their results back in order. Each sub-request is dispatched to the SAME handler that serves it directly, so a batched result is identical to calling that endpoint alone. Writes and auth-gated reads are deliberately NOT batchable (they keep their own idempotency + per-token rate accounting). Partial-failure semantics: a rejected sub-request (non-GET, non-allowlisted path, handler error) carries a 4xx/5xx status inside its own result while the batch envelope stays 200; only a malformed batch envelope is a 400 on the whole call.

## Request body

- BatchRequest: A bounded list (1..20) of public GET sub-requests to run in one round-trip.
  - `requests` BatchSubRequest[], required
    - `id` string: Optional caller correlation id; echoed back verbatim on the matching result.
    - `method` 'GET': Only GET sub-requests are batchable.
    - `path` string, required: An allowlisted public /api path, optionally with a query string (e.g. /api/events/upcoming?limit=3). Allowed: /api/events/upcoming, /api/events/get, /api/floor10/donations.

## Response `200`

Per-sub-request results, in the same order as `requests`.

- BatchResponse
  - `ok` boolean, required
  - `count` integer, required: Number of results (equals requests.length).
  - `results` BatchResultItem[], required
    - `id` string: Echoed from the sub-request if one was supplied.
    - `path` string, required: The sub-request path as sent.
    - `status` integer, required: HTTP status the target handler returned (or a 4xx/5xx synthesized for a rejected sub-request).
    - `ok` boolean, required: True iff status is 2xx.
    - `body` object, required: The target endpoint's JSON body (or an { error } object on a rejected sub-request).

## Other responses

- `400`: Malformed batch envelope: bad JSON, wrong shape, empty, or more than 20 sub-requests.
- `413`: Batch body exceeds 16KB.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)