---
search:
  tags:
    - Content blocks
    - POST
seo:
  description: >-
    Creates multiple content blocks in one request. Scoped to your
    integration's… Reference for the POST /content-blocks/bulk endpoint in the
    Fuxam API v4.
sidebar:
  label: Bulk create content blocks
  badge: POST
title: Bulk create content blocks
type: openapi-operation
---
Creates multiple content blocks in one request. Scoped to your integration's institution via Basic Auth credentials.

**Batch semantics:** Each entry in `contentBlocks` is processed independently. Valid blocks are created even when others fail. The response is always **HTTP 200** with per-item `results` and a `summary` (see **Success (batch / bulk)** in the API overview).

**Request options:**
- `courseId` — layer ID of the target course (required).
- `autoPosition` — when `true`, append after the highest existing position; when `false`, each item needs a valid `position` or that item may fail with `validation_failed`.
- `Idempotency-Key` header (required) — replays return the same batch envelope.

**Common per-item failure codes:** `validation_failed` (missing specs, invalid type fields), `bad_request` (position conflicts).

`POST /content-blocks/bulk`

**Request body** (`application/json`, required)

- `courseId` (string, required) — Layer ID of the course (same as the course's internal layer id). Required.
- `contentBlocks` (BulkCreateContentBlockItem[], required) — Blocks to create, in order. Use \`index\` in the response to correlate each result.
- `autoPosition` (boolean) — When true, append blocks after the current highest position in the course (ignores per-item \`position\`). When false, each item must supply a valid \`position\` or conflicts may fail that item.

Request body example:

```json
{
  "courseId": "layer_abc123",
  "autoPosition": true,
  "contentBlocks": [
    {
      "name": "Introduction",
      "type": "Text",
      "description": "Welcome to the course",
      "specs": {
        "content": "Hello world"
      }
    },
    {
      "name": "Midterm Quiz",
      "type": "Test",
      "specs": {}
    },
    {
      "name": "External resources",
      "type": "Link",
      "specs": {
        "url": "https://example.com/resources"
      }
    }
  ]
}
```

**Responses**

- `200` — Batch processed. Inspect \`data.results\` for per-block outcomes and \`data.summary\` for counts.
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict — duplicate email or membership code (body includes \`existingUserId\` when known), a time-tracking session that is already running (\`activeSession\`), a time-tracking interval that overlaps an existing log (\`conflictingLog\`), idempotency key reused with a different body (\`idempotency\_key\_reused\`), or concurrent request with the same key still in progress (\`idempotency\_key\_in\_progress\`)
- `422` — Unprocessable Entity — validation or business rule error
- `429` — Too Many Requests — 1000 requests per minute per institution. Includes \`X-RateLimit-Limit\`, \`X-RateLimit-Remaining\`, \`X-RateLimit-Reset\` (ISO-8601), and \`Retry-After\` (seconds).
- `500` — Internal Server Error

Response example, 200:

```json
{
  "data": {
    "results": [
      {
        "index": 0,
        "id": "block_intro",
        "status": "succeeded",
        "data": {
          "id": "block_intro",
          "name": "Introduction",
          "position": 5
        }
      },
      {
        "index": 1,
        "status": "failed",
        "error": {
          "code": "validation_failed",
          "detail": "specs.workbenchFileId is required for Test type",
          "field": "contentBlocks.1.specs.workbenchFileId"
        }
      },
      {
        "index": 2,
        "id": "block_link",
        "status": "succeeded",
        "data": {
          "id": "block_link",
          "name": "External resources",
          "position": 6
        }
      }
    ],
    "summary": {
      "total": 3,
      "succeeded": 2,
      "failed": 1
    }
  },
  "meta": {
    "requestId": "req_batch_example",
    "timestamp": "2026-07-07T12:00:00.000Z",
    "version": "v4"
  }
}
```