# POST /v1/projects (/docs/api/reference/projects/create-project)



<Endpoint method="POST" path="/v1/projects" auth="Bearer" scope="projects:write" phase="1" />

Create a project to hold one end-customer's brand context, layers, influencers, social accounts, and generated content. Set `customerExternalId` to your partner-side customer handle so later lookups don't require Layers IDs.

The call is synchronous and idempotent on `id` (if you create one) or on the `Idempotency-Key` header. It provisions the project shell; downstream ingestion (GitHub, website, App Store) is a separate, async step.

<Parameters
  title="Headers"
  rows="[
  { name: 'Idempotency-Key', type: 'string (UUID)', description: 'Same key + same body replays the cached response for 24 hours. Recommended for every POST.' },
]"
/>

<Parameters
  title="Body"
  rows="[
  { name: 'id', type: 'string', description: 'Partner-created project ID. If omitted, the server generates one.' },
  { name: 'name', type: 'string', required: true, description: 'Human-readable project name, 1–128 chars.' },
  { name: 'customerExternalId', type: 'string', description: 'Your internal customer handle. Unique per organization. Looked up via ?customerExternalId=.' },
  { name: 'ownerEmail', type: 'string', description: 'Notification email. Defaults to the API key\'s registered owner.' },
  { name: 'timezone', type: 'string', required: true, description: 'IANA timezone. Controls cron schedule resolution. Use `&#x22;UTC&#x22;` if you have no preference.' },
  { name: 'primaryLanguage', type: 'string', description: 'BCP-47 language tag (e.g. en, pt-BR).', default: 'en' },
  { name: 'metadata', type: 'object', description: 'Opaque JSON, ≤ 8KB. Round-tripped unchanged.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl https://api.layers.com/v1/projects \
      -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..." \
      -H "Idempotency-Key: 4c1a2e92-7b18-4c4b-9b2a-d7a3f8b1c210" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Acme Coffee iOS",
        "customerExternalId": "acme-coffee",
        "timezone": "America/Los_Angeles",
        "primaryLanguage": "en",
        "ownerEmail": "growth@gicgrowth.com"
      }'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const project = await layers.projects.create(
      {
        name: "Acme Coffee iOS",
        customerExternalId: "acme-coffee",
        timezone: "America/Los_Angeles",
        primaryLanguage: "en",
        ownerEmail: "growth@gicgrowth.com",
      },
      { idempotencyKey: crypto.randomUUID() }
    );
    ```
  </Tab>

  <Tab value="Python">
    ```python
    project = layers.projects.create(
        name="Acme Coffee iOS",
        customer_external_id="acme-coffee",
        timezone="America/Los_Angeles",
        primary_language="en",
        owner_email="growth@gicgrowth.com",
        idempotency_key=str(uuid.uuid4()),
    )
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="201" description="Created">
  ```json
  {
    "id": "9cb958b5-11b5-4e30-8675-5d075d52da7c",
    "organizationId": "2481fa5c-a404-44ed-a561-565392499abc",
    "name": "Acme Coffee iOS",
    "status": "active",
    "customerExternalId": "acme-coffee",
    "timezone": "America/Los_Angeles",
    "primaryLanguage": "en",
    "ownerEmail": "growth@gicgrowth.com",
    "brand": null,
    "brandContext": null,
    "ingestState": { "github": null, "website": null, "appstore": null },
    "requiresApproval": false,
    "firstNPostsBlocked": 3,
    "currentBlockedCount": 0,
    "metadata": null,
    "createdAt": "2026-04-18T19:02:11.959888+00:00",
    "updatedAt": "2026-04-18T19:02:11.959888+00:00"
  }
  ```
</Response>

## Errors [#errors]

| Status | Code              | When                                                                                                              |
| ------ | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| 422    | `VALIDATION`      | `name` empty, `timezone` invalid, `metadata` > 8KB.                                                               |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                                                                           |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `projects:write`.                                                                                       |
| 409    | `CONFLICT`        | Same `Idempotency-Key` replayed with a different body, or `customerExternalId` already in use on another project. |
| 429    | `RATE_LIMITED`    | Write budget exhausted.                                                                                           |

## See also [#see-also]

* [`POST /v1/projects/:id/ingest/github`](/docs/api/reference/github/ingest-github) — seed brand context from a repo
* [`POST /v1/projects/:id/ingest/website`](/docs/api/reference/projects/ingest-website) — seed from a landing page
* [`PATCH /v1/projects/:id`](/docs/api/reference/projects/patch-project) — update fields
* [Idempotency](/docs/api/concepts/jobs#idempotency) — replay semantics