API documentation

Pages API

Create a page (async)

Starts an AI-powered landing page generation pipeline. Returns immediately with a job ID. Poll GET /v1/accounts/{account_id}/pages/jobs/{jobId} to track progress and retrieve the final page ID. Returns 403 quota_exceeded if limits are reached. Required scope: pages:write.

POST/v1/accounts/{account_id}/pages

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`Idempotency-Key`	header	string	No	Optional deduplication key for POST and PATCH requests. Cached responses are replayed for 24 hours.

Request body

This request body is required.

Page creation payload. Exactly one of product (inline) or product_id (link to an existing product) must be provided.

Field	Type	Required	Notes
`product`	object	Yes
`product.title`	string	Yes
`product.description`	string	Yes
`product.price`	number	Yes
`product.product_type`	string	Yes	Allowed: physical, service
`product.delivery_price`	number	No
`product.images`	array	No	Default: `[]`
`options`	object	No
`options.language`	string	No	Default: `"en"`
`options.marketing_angle`	string	No
`design`	object	No
`design.primary_color`	string	No
`design.secondary_color`	string	No
`design.background_color`	string	No
`design.text_color`	string	No
`design.font_family`	string	No
`checkout_fields`	array	No
`checkout_fields[].field_key`	string	Yes
`checkout_fields[].label`	string	No
`checkout_fields[].field_type`	string	No	Allowed: text, tel, email, date, textarea, select
`checkout_fields[].is_required`	boolean	No	Default: `true`
`checkout_fields[].options`	array	No
`product_id`	string (uuid)	Yes	Derived public id of an existing non-deleted product owned by the authenticated account. Existing checkout fields are preserved; if none exist they are AI-generated.

The example below includes optional fields for context; only fields marked Yes are always required. Conditional requirements are listed in Notes.

Inline product — create product + page in one call

{
  "product": {
    "title": "Atlas Resistance Band Kit",
    "description": "A compact physical fitness product with a Tunisian-ready checkout.",
    "price": 149,
    "product_type": "physical",
    "delivery_price": 8,
    "images": [
      "https://cdn.demarky.ai/products/atlas-band-front.webp",
      "https://cdn.demarky.ai/products/atlas-band-packaging.webp"
    ]
  },
  "options": {
    "language": "en",
    "marketing_angle": "Focus on home workout convenience and portability"
  },
  "design": {
    "primary_color": "#1449d2",
    "secondary_color": "#3B82F6",
    "background_color": "#EFF6FF",
    "text_color": "#1E3A8A",
    "font_family": "Poppins"
  }
}

Existing product — link by product_id

{
  "product_id": "123e4567-e89b-42d3-a456-426614174000",
  "options": {
    "language": "en",
    "marketing_angle": "Focus on home workout convenience and portability"
  }
}

Response

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "poll_url": "/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

cURL example

curl -X POST https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages \
  -H "Authorization: Bearer dmk_at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product": {
    "title": "Atlas Resistance Band Kit",
    "description": "A compact physical fitness product with a Tunisian-ready checkout.",
    "price": 149,
    "product_type": "physical",
    "delivery_price": 8,
    "images": [
      "https://cdn.demarky.ai/products/atlas-band-front.webp",
      "https://cdn.demarky.ai/products/atlas-band-packaging.webp"
    ]
  },
  "options": {
    "language": "en",
    "marketing_angle": "Focus on home workout convenience and portability"
  },
  "design": {
    "primary_color": "#1449d2",
    "secondary_color": "#3B82F6",
    "background_color": "#EFF6FF",
    "text_color": "#1E3A8A",
    "font_family": "Poppins"
  }
}'

Poll page generation job

Returns the current status of an async page generation job. When status is completed, page_id contains the derived public page id. Required scope: pages:read.

GET/v1/accounts/{account_id}/pages/jobs/{jobId}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`jobId`	path	string	Yes	Generation job UUID returned by `POST /v1/accounts/{account_id}/pages`.

Response

Job in progress

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing",
    "step": "generating_images",
    "step_detail": "3 of 5 images completed",
    "page_id": null,
    "builder_url": null,
    "warnings": [],
    "error": null,
    "created_at": "2026-07-06T10:00:00.000Z",
    "updated_at": "2026-07-06T10:01:15.000Z",
    "completed_at": null
  }
}

Job completed

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "step": "done",
    "step_detail": "Page generation complete",
    "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "builder_url": "https://demarky.ai/builder/123e4567-e89b-42d3-a456-426614174000",
    "warnings": [],
    "error": null,
    "created_at": "2026-07-06T10:00:00.000Z",
    "updated_at": "2026-07-06T10:02:30.000Z",
    "completed_at": "2026-07-06T10:02:30.000Z"
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/jobs/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx"

List pages

Lists the authenticated account's pages with cursor pagination, filters, and sort options. Required scope: pages:read.

GET/v1/accounts/{account_id}/pages

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`status`	query	string	No	Filter by page status.
`product_id`	query	string	No	Filter by derived public product id.
`q`	query	string	No	Free-text search against the page slug and product title.
`created_after`	query	string	No
`created_before`	query	string	No
`cursor`	query	string	No	Opaque pagination cursor returned by the previous page.
`per_page`	query	integer	No	Page size between 1 and 100.
`sort`	query	string	No	Sort field and direction.

Response

{
  "data": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "slug": "atlas-resistance-band-kit-a1b2c3",
      "status": "draft",
      "product": {
        "id": "123e4567-e89b-42d3-a456-426614174000",
        "title": "Atlas Resistance Band Kit",
        "price": 149
      },
      "deployed_url": null,
      "created_at": "2026-04-28T09:40:11.000Z",
      "updated_at": "2026-04-28T09:40:11.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

cURL example

curl -X GET "https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages?status=draft" \
  -H "Authorization: Bearer dmk_at_live_xxx"

Get a page

Returns the page, backing product summary, theme, and SEO settings. Required scope: pages:read.

GET/v1/accounts/{account_id}/pages/{id}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.

Response

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "slug": "atlas-resistance-band-kit-a1b2c3",
    "status": "draft",
    "product": {
      "id": "123e4567-e89b-42d3-a456-426614174000",
      "title": "Atlas Resistance Band Kit",
      "price": 149,
      "currency": "TND",
      "product_type": "physical"
    },
    "deployed_url": null,
    "global_theme": {
      "currency": "TND",
      "primaryColor": "#1F7A8C"
    },
    "seo_config": {
      "title": "Atlas Resistance Band Kit",
      "description": "Improve your workouts with a compact resistance band kit."
    },
    "created_at": "2026-04-28T09:40:11.000Z",
    "updated_at": "2026-04-28T09:40:11.000Z"
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx"

Update page metadata

Applies merge-style updates to global_theme and seo_config. Required scope: pages:write.

PATCH/v1/accounts/{account_id}/pages/{id}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.
`Idempotency-Key`	header	string	No	Optional deduplication key for POST and PATCH requests. Cached responses are replayed for 24 hours.

Request body

This request body is required.

Page metadata changes.

Field	Type	Required	Notes
`global_theme`	object	No
`seo_config`	object	No

The example below includes optional fields for context; only fields marked Yes are always required. Conditional requirements are listed in Notes.

{
  "global_theme": {
    "primaryColor": "#0F5B66",
    "accentColor": "#F5C451"
  },
  "seo_config": {
    "title": "Atlas Resistance Band Kit | Demarky"
  }
}

Response

{
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "slug": "atlas-resistance-band-kit-a1b2c3",
    "status": "draft",
    "product": {
      "id": "123e4567-e89b-42d3-a456-426614174000",
      "title": "Atlas Resistance Band Kit",
      "price": 149,
      "currency": "TND",
      "product_type": "physical"
    },
    "deployed_url": null,
    "global_theme": {
      "currency": "TND",
      "primaryColor": "#1F7A8C"
    },
    "seo_config": {
      "title": "Atlas Resistance Band Kit",
      "description": "Improve your workouts with a compact resistance band kit."
    },
    "created_at": "2026-04-28T09:40:11.000Z",
    "updated_at": "2026-04-28T09:40:11.000Z"
  }
}

cURL example

curl -X PATCH https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "global_theme": {
    "primaryColor": "#0F5B66",
    "accentColor": "#F5C451"
  },
  "seo_config": {
    "title": "Atlas Resistance Band Kit | Demarky"
  }
}'

Delete a page

Permanently deletes the page (and its components, routes, and deployment history) and returns no content. Required scope: pages:write.

DELETE/v1/accounts/{account_id}/pages/{id}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.

cURL example

curl -X DELETE https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx"

Deploy a page

Starts a deployment: builds the public landing page output and publishes it to the deployment target. Required scope: pages:deploy.

This endpoint takes no request body and no parameters — the page is deployed exactly as it currently stands. Send it with no body at all, or with an empty {}.

Deployment is asynchronous. A successful call returns 202 Accepted with a deployment_id and a poll_url, and sets the Location response header to the same URL. The page is not live yet at that point — GET the poll_url until status is succeeded or failed. A deployment normally settles within ~5 minutes; poll every 2–5 seconds and give up after that.

Only one deployment can be in flight per page. Starting a second one returns 409 whose details.active_deployment_id and details.poll_url point at the deployment already running.

POST/v1/accounts/{account_id}/pages/{id}/deployments

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.
`Idempotency-Key`	header	string	No	Optional deduplication key for POST and PATCH requests. Cached responses are replayed for 24 hours.

Response

{
  "data": {
    "deployed_url": "https://atlas-resistance-band-kit.demarky.store",
    "deployment_id": "f62fba7d-5af6-4741-b94b-6c362d3317af",
    "deployed_at": "2026-04-28T10:12:55.000Z"
  }
}

cURL example

curl -X POST https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af/deployments \
  -H "Authorization: Bearer dmk_at_live_xxx"

List deployments

Returns the deployment history for a page, newest first. Use this to recover a deployment_id you no longer have, or to inspect why an earlier deployment failed. Required scope: pages:read.

GET/v1/accounts/{account_id}/pages/{id}/deployments

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.
`status`	query	string	No	Filter by deployment status.
`cursor`	query	string	No	Opaque pagination cursor returned by the previous page.
`per_page`	query	integer	No	Page size between 1 and 100.

Response

{
  "data": [
    {
      "id": "f62fba7d-5af6-4741-b94b-6c362d3317af",
      "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "succeeded",
      "deploy_step": null,
      "error_code": null,
      "error_message": null,
      "deployed_url": "https://atlas-resistance-band-kit.demarky.store",
      "deployed_at": "2026-04-28T10:12:55.000Z",
      "created_at": "2026-04-28T10:12:40.000Z",
      "updated_at": "2026-04-28T10:12:55.000Z"
    },
    {
      "id": "3f1c8a90-6d2b-4c77-9a15-0b4e2d5f7c31",
      "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "failed",
      "deploy_step": "rendering",
      "error_code": "worker_terminated",
      "error_message": "Deploy worker was terminated (died at step: rendering)",
      "deployed_url": null,
      "deployed_at": null,
      "created_at": "2026-04-28T09:58:03.000Z",
      "updated_at": "2026-04-28T10:03:11.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af/deployments \
  -H "Authorization: Bearer dmk_at_live_xxx"

Get a deployment

Polls the status of a deployment started by POST /v1/accounts/{account_id}/pages/{id}/deployments. Required scope: pages:read.

status is deploying until the deployment settles, then succeeded (with deployed_url and deployed_at set) or failed (with error_code and error_message set). deploy_step names the stage currently running, or the stage a failed deployment died at.

GET/v1/accounts/{account_id}/pages/{id}/deployments/{deploymentId}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Page identifier.
`deploymentId`	path	string	Yes	Deployment UUID returned by `POST /v1/accounts/{account_id}/pages/{id}/deployments`.

Response

{
  "data": {
    "id": "f62fba7d-5af6-4741-b94b-6c362d3317af",
    "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "succeeded",
    "deploy_step": null,
    "error_code": null,
    "error_message": null,
    "deployed_url": "https://atlas-resistance-band-kit.demarky.store",
    "deployed_at": "2026-04-28T10:12:55.000Z",
    "created_at": "2026-04-28T10:12:40.000Z",
    "updated_at": "2026-04-28T10:12:55.000Z"
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages/f62fba7d-5af6-4741-b94b-6c362d3317af/deployments/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx"