PATCH /v1/projects/:id

PATCH/v1/projects/:id

Phase 1stable

Auth: Bearer
Scope: projects:write

Patch one or more user-editable fields. Omitted fields stay unchanged. System-managed fields - id, organizationId, createdAt, ingestState, brandContext.* populated by ingestion - are read-only; passing them returns 400 VALIDATION.

To modify approval behavior, use PATCH /v1/projects/:id/content-review-policy - approval lives on a separate resource so it has its own scope and audit trail.

Changing appDescription to a new non-empty value re-kicks background keyword research — Layers' research agent re-curates the TikTok hashtag bank over the next 4–5 minutes. PATCHes that omit appDescription (or set it to the same value) do not trigger a refresh. To force a manual re-run regardless of the field, call POST /v1/projects/:id/keywords/refresh.

Path

id
stringrequired
Project ID.

Body

name
stringoptional
Internal display name. 3–30 chars.
status
stringoptional
Archiving stops scheduled posts and new content generation; it does not delete data.
One of: active, archived
ownerEmail
stringoptional
Notification email.
timezone
stringoptional
IANA timezone. Takes effect on the next scheduler tick.
primaryLanguage
stringoptional
BCP-47 tag.
customerExternalId
stringoptional
Must remain unique within the organization.
appName
stringoptional
Product name the generator anchors hooks and captions on. 3–30 chars. Required before `GET /v1/projects/:id/content/hooks` returns a bank. Pass `null` to clear.
appDescription
stringoptional
Product pitch the planner uses for hooks and captions. 100–1000 chars. Same precondition for `/content/hooks`. Pass `null` to clear.
tagline
stringoptional
Short one-liner (≤ 80 chars) used in end-cards and overlays.
brandVoice
stringoptional
Caption tone preset.
One of: authentic, witty, professional, warm, casual, educational
targetGender
stringoptional
Audience gender. Used as the default when creating new influencers.
One of: all, female, male
metadata
objectoptional
Replaces the existing object in full - not a deep merge.

Example request

curl -X PATCH https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39 \
  -H "Authorization: Bearer lp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "ownerEmail": "ops@gicgrowth.com"
  }'

const project = await layers.projects.update(
  "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
  { timezone: "America/New_York", ownerEmail: "ops@gicgrowth.com" }
);

project = layers.projects.update(
    "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    timezone="America/New_York",
    owner_email="ops@gicgrowth.com",
)

Response

200OK

{
  "id": "9cb958b5-11b5-4e30-8675-5d075d52da7c",
  "organizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
  "name": "Acme Coffee iOS",
  "status": "active",
  "customerExternalId": "acme-coffee",
  "timezone": "America/New_York",
  "primaryLanguage": "en",
  "ownerEmail": "ops@gicgrowth.com",
  "appName": "Acme Coffee",
  "appDescription": "Daily ritual coffee subscriptions for runners and night-shift workers. Single-origin beans from named farms, roasted weekly, and shipped on a cadence that matches how you actually drink coffee — so the bag never goes stale and you never run out before a hard workout.",
  "tagline": "Coffee that shows up before you run out.",
  "brandVoice": "warm",
  "targetGender": "all",
  "metadata": null,
  "createdAt": "2026-04-18T19:02:11.959888+00:00",
  "updatedAt": "2026-04-18T19:08:44.317953+00:00"
}

The full project record is returned, identical in shape to GET /v1/projects/:id - not a slim diff.

Errors

Status	Code	When
422	`VALIDATION`	`:id` is not a UUID, body has unknown/read-only fields, or `timezone` is invalid.
401	`UNAUTHENTICATED`	Missing or invalid key.
403	`FORBIDDEN_SCOPE`	Key lacks `projects:write`.
404	`NOT_FOUND`	Project does not exist in the key's organization.
409	`CONFLICT`	`customerExternalId` collides with another project in the organization.
429	`RATE_LIMITED`	Write budget exhausted.

Example request

Response

Errors

See also

On this page