Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Bulk create content blocks

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
Authorization
AuthorizationBasic auth · headerrequired

Basic Auth with clientId as username and clientSecret as password

Header parameters
Idempotency-Keystringrequired

Required. Unique key for idempotent batch create. Reusing the key with the same body returns the original batch response.

Request body
requiredapplication/json
courseIdstringrequired

Layer ID of the course (same as the course's internal layer id). Required.

contentBlocksBulkCreateContentBlockItem[]required

Blocks to create, in order. Use index in the response to correlate each result.

min items 1 · max items 50
Show properties
Array of BulkCreateContentBlockItem
namestringrequired
min length 1 · max length 100
descriptionstring
max length 100000
typestringrequired
Allowed:TextImageVideoTestInteractiveFileLinkHandInCertificateExternalDeliverableSurveySection
statusstring
Allowed:PUBLISHEDCOMING_SOONDRAFTDISABLED
positioninteger
min 0
dueDatestring<date-time>
startDatestring<date-time>
specsobject
expectedLearnTimeMinutesinteger
min 1
isDependentboolean
autoPositionboolean

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.

default: false
Responses
200

Batch processed. Inspect data.results for per-block outcomes and data.summary for counts.

dataBatchResultrequired

Shared v4 batch shape: per-item results with partial-success reporting.

Show properties
resultsBatchItemResult[]required

One entry per input item, in request order.

Show properties
Array of BatchItemResult
indexintegerrequired

Zero-based index of this item in the request array (contentBlocks, updates, or ids).

min 0
idstring

Resource ID when known (block id for update/delete, or created id on success).

statusstringrequired

Whether this individual item was processed successfully.

Allowed:succeededfailed
dataobject

Resource-specific payload when status is succeeded.

errorBatchItemError

Failure details when status is failed.

Show properties
codestringrequired

Machine-readable error code (same vocabulary as RFC 7807 responses).

Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
detailstringrequired

Human-readable explanation for this item failure.

fieldstring

Optional field path when the failure maps to a specific input field.

activeSessionobject

Present when a time-tracking start item conflicts with a running session.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present when a time-tracking interval overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
summaryBatchSummaryrequired

Aggregate counts for the batch operation.

Show properties
totalintegerrequired

Total items in the request.

min 0
succeededintegerrequired

Items processed successfully.

min 0
failedintegerrequired

Items that failed validation or business rules.

min 0
metaResponseMetarequired
Show properties
requestIdstringrequired
timestampstring<date-time>required
versionstringrequired
Allowed:v4
watermarkstring<date-time>

Present on GET /users?updatedSince= pages. Taken at the first page minus a 60s overlap. Bound into pagination.next_cursor. Use it as the next updatedSince after deduping by user id. Delivery is inclusive >= and at-least-once.

400

Bad Request

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
401

Unauthorized

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
403

Forbidden

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
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)

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
422

Unprocessable Entity — validation or business rule error

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
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).

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
500

Internal Server Error

typestringrequired
Allowed:error
codestringrequired
Allowed:bad_requestunauthorizedforbiddenresource_not_foundconflictvalidation_failedidempotency_key_reusedidempotency_key_in_progressservice_unavailableretryablerate_limit_exceededinternal_error
titlestringrequired
statusintegerrequired
detailstringrequired
instancestring
errorsobject[]
Show properties
Array of object
fieldstring
messagestring
existingUserIdstring

Present on 409 email or membership-code conflicts. The user id that already holds the email or code.

activeSessionobject

Present on time-tracking start 409 when a session is already running. Stop this session, then retry start.

Show properties
idstringrequired
startTimestring<date-time>required
conflictingLogobject

Present on time-tracking 409 when the interval being written overlaps an existing log or open session. Start uses [punch, ∞). Stop uses [sessionStart, stop). endTime is null while that session is still open.

Show properties
idstringrequired
startTimestring<date-time>required
endTimestring<date-time> | nullrequired
Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://fuxam.app/api/v4/content-blocks/bulk' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'Idempotency-Key: string' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "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"
      }
    }
  ]
}'
Response
{
  "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"
  }
}

Was this page helpful?