Skip to content
Reference

Changelog

Dated changes to the Luma Agents /v1 API that you can see as a caller — new fields, new status codes and changed behavior — newest first.

Changes to the /v1 API that you can see as a caller, newest first. Dates are in UTC. Breaking changes are announced here before they ship.

Every response carries an X-API-Version header (currently 2026-04-01). It reports the version that answered; you cannot send it to choose a version.


  • GET /v1/usage responses add period_source, which says where the reported window came from: subscription (your current billing period), calendar_month (the current UTC month) or explicit (the start and end you sent). See Usage and credits.
  • Failed POST /v1/generations requests answer by cause. Some errors now carry an error object with a machine-readable code and a retry flag next to detail. See Error handling.
    • An input refused when the generation is dispatched answers 422 with USER.ARTIFACT.MODERATED (rejected by moderation) or USER.INPUT.INVALID_PROMPT (missing, deleted or failed), instead of 500.
    • A transient failure, such as a timeout, answers a retryable 503 with TRANSIENT.SERVICE.UNAVAILABLE.
    • A 500 with INTERNAL.SYSTEM.DATABASE_ERROR means the generation may still run. Do not resubmit it.
  • Generation responses (POST /v1/generations and GET /v1/generations/{id}) carry a usage object. While usage reporting is off it is null; once it is on, usage.credits_charged is the credits charged for the generation after billing settles.
  • POST /v1/generations accepts expires_at, a deadline after which the generation is deleted. It needs the managed retention add-on and is ignored without it. See Generation deletion.
  • A malformed id in a /v1 URL, such as GET /v1/files/not-a-uuid, answers 404, the same as a well-formed id that does not exist. It used to answer 422.
  • GET /v1/credits no longer returns balance_usd_cents, which was always null. Read balance_credits. See Usage and credits.
  • The API Reference documents DELETE /v1/generations/{id} and GET /v1/deletions/{task_id} for clients with deletion enabled. They are HTTP only; the SDKs and CLI do not wrap them yet.
  • POST /v1/generations refuses a layering request that names uni-1-max with 422 (layering is only available on uni-1). It used to run as uni-1.
  • GET /v1/generations/{id} reports a layering generation as processing once layering starts, instead of queued until it completes.
  • POST /v1/generations answers a retryable 503 when registering the request’s reference images fails briefly, instead of 500.