Skip to main content
Webentor Studio

Help · API reference

Projects

Projects, builds, deployments, domains and media.

All groups

Get a projectGET /api/v1/projects/{project}

Returns the project with its deploy targets, domains, open drafts, recent builds and deployments, what the live site serves, and whether publishing is blocked. view=summary answers only the project's identity and open drafts, which is much cheaper.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

What comes back

One of:

    • id string, required
    • slug string, required
    • name string, required
    • status string, required
    • state string, required
    • live_branch string, required
    • publish_policy string, required
    • assistant_autonomy "review" | "publish", required: What an assistant’s publish means here (D12).
    • assistant_reads_forms boolean, required: May an assistant read visitors’ form submissions here (D19).
    • assistant_writes_blocks boolean, required: Does a connector client’s sign-in ask for the blocks grant here (AI-001).
    • assistant_guidelines string | null, required: What every assistant reads before its first change here (P6).
    • preview_access "link" | "password", required: Whether preview links ask for a passphrase.
    • stack_version string | null, required
    • template string | null, required
    • created_at string, required: ISO 8601 timestamp.
    • role string, required
    • as_operator true: Present when the caller is here as the platform’s operator, not as a member of the team.
    • moved_to string: Where the project went, when it moved to another deployment; everything here is then read-only.
    • deletion_grace_days number, required
    • deleted_at string: Present only while a deletion is pending.
    • purge_after one of: string | null: Present only while a deletion is pending.

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • managed_url string, required
    • git object, required
      • clone_url string, required
      • locator string, required
    • open_drafts array of object, required

      A list of:

      • id string, required
      • kind "session" | "branch", required
      • title string, required
      • status string, required
      • branch string, required
      • origin string, required
      • created_by string | null, required
      • created_at string, required: ISO 8601 timestamp.
      • updated_at string, required: ISO 8601 timestamp.
      • head_commit string, required
      • base_commit string, required
      • preview_url string | null, required: The line’s stable preview address; null until somebody asks for one.
      • preview_visibility "members" | "public", required
      • preview_public_until one of: string | null, required

        one of: string | null

      • expires_at one of: string | null, required: When the line is tidied away: an idle session, or an assistant’s line whose token died. Null for a branch.

        one of: string | null

      • publish_at one of: string | null, required

        one of: string | null

      • merged_into string | null, required: Where a merged line went: live (published) or the id of the line it was folded into. Null while open.
    • first_steps object: The caller’s own first steps here; sent only while the project is new.
      • assistant_connected boolean, required
      • assistant_dismissed boolean, required
    • publish_blocked string | null, required: Why a publish is refused right now, or null.
    • forms one of: object | null, required: What the live site’s forms do with an entry; null when they could not be read.

      One of:

        • saving number, required
        • notifying number, required
        • quiet array of object, required

          A list of:

          • slug string, required
          • title string | null, required

      2. null

    • stack one of: object | null, required: Where the project stands against this Studio’s Webentor release; null when it could not tell.

      One of:

        • behind boolean, required
        • status "current" | "behind" | "not-on-release" | "custom" | "newer" | "none", required
        • from string | null, required
        • to string | null, required
        • packages array of string, required
        • custom array of string
        • advisories array of object

          A list of:

          • id string, required
          • level "security" | "data", required
          • summary string, required
          • fixed string: The first release with the fix.
          • offered boolean: Whether this Studio’s release carries the fix.
        • newest object
          • version string, required
          • checkedAt string, required
        • contract object
          • project string | null, required
          • studio string | null, required
          • fits boolean | null, required
        • relock boolean, required
        • blockedBy string
        • tree object: What the latest production build installed, when it is off the release.
          • release string, required
          • problems array of string, required
          • buildId string, required

      2. null

    • live_commit string | null, required
    • served one of: object | null, required: What the live site serves; null before anything is published.

      One of:

        • target_id string, required
        • build_id string, required
        • commit string | null, required
        • up_to_date boolean, required

      2. null

    • targets array of object, required

      A list of:

      • id string, required
      • provider string, required
      • name string, required
      • is_default boolean, required
      • config object, required: The target’s non-secret settings.
      • has_credential boolean, required
      • live_build_id string | null, required
      • created_at string, required: ISO 8601 timestamp.
    • divergence array of object, required

      A list of:

      • target_id string, required
      • target_name string, required
      • provider string, required
      • serving_build_id string | null, required
      • up_to_date boolean, required
    • domains array of object, required

      A list of:

      • id string, required
      • account_id string, required
      • project_id string, required
      • hostname string, required
      • verification_status "pending" | "verified" | "failed", required
      • verification_token string, required: The value of the TXT record that proves the domain is yours.
      • tls_status "pending" | "active" | "failed", required
      • is_primary boolean, required
      • created_at string, required: ISO 8601 timestamp.
      • verified_at one of: string | null, required

        one of: string | null

      • last_checked_at one of: string | null, required: The last DNS check, pass or fail; null until the first.

        one of: string | null

    • recent_builds array of object, required

      A list of:

      • id string, required
      • status string, required
      • trigger string, required
      • commit string | null, required
      • draft_id string | null, required
      • preview_url string | null, required
      • preview_open_url string | null, required: The build opened as the caller (signs a member in).
      • bytes number | null, required
      • duration_ms number | null, required
      • error string | null, required
      • failure one of: object | null, required

        one of: object | null

      • warning string | null, required
      • superseded_by string | null, required
      • queued_at string, required: ISO 8601 timestamp.
      • started_at one of: string | null, required

        one of: string | null

      • finished_at one of: string | null, required

        one of: string | null

    • recent_deployments array of object, required

      A list of:

      • id string, required
      • type string, required
      • status string, required
      • url string | null, required
      • is_rollback boolean, required
      • build_id string, required
      • target_id string | null, required: The destination; null once it is removed. A publish writes a row per destination.
      • commit string | null, required
      • duration_ms number | null, required
      • created_at string, required: ISO 8601 timestamp.
      • warnings array of string, required: On a success: what the destination left undone.
      • site_changed one of: "yes" | "unknown" | null, required: On a failure: whether visitors may already see some of it.

        one of: "yes" | "unknown" | null

    • id string, required
    • slug string, required
    • name string, required
    • status string, required
    • state string, required
    • live_branch string, required
    • publish_policy string, required
    • assistant_autonomy "review" | "publish", required: What an assistant’s publish means here (D12).
    • assistant_reads_forms boolean, required: May an assistant read visitors’ form submissions here (D19).
    • assistant_writes_blocks boolean, required: Does a connector client’s sign-in ask for the blocks grant here (AI-001).
    • assistant_guidelines string | null, required: What every assistant reads before its first change here (P6).
    • preview_access "link" | "password", required: Whether preview links ask for a passphrase.
    • stack_version string | null, required
    • template string | null, required
    • created_at string, required: ISO 8601 timestamp.
    • role string, required
    • as_operator true: Present when the caller is here as the platform’s operator, not as a member of the team.
    • moved_to string: Where the project went, when it moved to another deployment; everything here is then read-only.
    • deletion_grace_days number, required
    • deleted_at string: Present only while a deletion is pending.
    • purge_after one of: string | null: Present only while a deletion is pending.

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • managed_url string, required
    • git object, required
      • clone_url string, required
      • locator string, required
    • open_drafts array of object, required

      A list of:

      • id string, required
      • kind "session" | "branch", required
      • title string, required
      • status string, required
      • branch string, required
      • origin string, required
      • created_by string | null, required
      • created_at string, required: ISO 8601 timestamp.
      • updated_at string, required: ISO 8601 timestamp.
      • head_commit string, required
      • base_commit string, required
      • preview_url string | null, required: The line’s stable preview address; null until somebody asks for one.
      • preview_visibility "members" | "public", required
      • preview_public_until one of: string | null, required

        one of: string | null

      • expires_at one of: string | null, required: When the line is tidied away: an idle session, or an assistant’s line whose token died. Null for a branch.

        one of: string | null

      • publish_at one of: string | null, required

        one of: string | null

      • merged_into string | null, required: Where a merged line went: live (published) or the id of the line it was folded into. Null while open.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • default Any other failure, as RFC 9457 problem details.

Update a projectPATCH /api/v1/projects/{project}

Changes project settings: name, publish_policy, build variables (build_env) and the assistant settings. Needs the project-settings permission; changing publish_policy also needs the project-policy permission, and the assistant settings are an owner's. build_env may not use reserved variable names. New assistant_guidelines are also committed to the repository.

A stepped-up session is required for: changing what an assistant may do alone (assistant_autonomy, assistant_reads_forms, assistant_writes_blocks); loosening publish_policy to direct. No access token carries step-up.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • name string, 1 to 80 characters
  • publish_policy "direct" | "review_required": Who may publish: anyone allowed to (direct), or only an approved draft (review_required).
  • assistant_autonomy "review" | "publish": What an assistant’s publish means here: a request a person approves, or a publish. An owner’s, stepped up.
  • assistant_reads_forms boolean: May an assistant read visitors’ form submissions. An owner’s, stepped up.
  • assistant_writes_blocks boolean: Does an assistant’s sign-in ask for the blocks grant here. An owner’s, stepped up.
  • assistant_guidelines one of: string | null: What every assistant reads before its first change here. null clears it.

    One of:

    1. string

    2. null

  • build_env object

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a projectDELETE /api/v1/projects/{project}

Schedules the project for deletion: its sites go offline, an export bundle is queued, and the project is erased after the grace period unless restored. Needs the project-delete permission. confirm must be the project's slug; a project being moved is refused, and so is a moved copy whose domains still lead here unless still_served is true.

A signed-in person who has stepped up (confirmed again with a passkey, a recovery code or an emailed code): a live session alone is refused, and no access token is accepted.

Who may call it: A signed-in person who has stepped up; no access token

Parameters

  • project (path, string)

Body (application/json)

  • confirm string, required: The project’s slug, typed to confirm.
  • still_served boolean: Delete a moved copy although its domains still lead here.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Get a project activityGET /api/v1/projects/{project}/activity

Returns the project's activity feed, newest first. Filter with draft, actor, category and security=1; page with limit (up to 500) and before, passing the next value back. format=ndjson streams every matching row. Needs the project-activity permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • actor (query, string, optional)
  • before (query, string, optional)
  • category (query, string, optional)
  • draft (query, string, optional)
  • format (query, string, optional)
  • limit (query, integer, optional), at most 500, default 100
  • security (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Get project analyticsGET /api/v1/projects/{project}/analytics

Returns the project's visitor analytics overview for range days (7, 30 or 90; 30 when absent or not one of those). Needs the repo-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • range (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Delete project analyticsDELETE /api/v1/projects/{project}/analytics

Erases every analytics row collected for the project; collection itself stays on or off as it was. Needs the project-settings permission. The answer gives the number of rows erased.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Update analytics settingsPOST /api/v1/projects/{project}/analytics/settings

Turns analytics collection on or off for the project (enabled); the change applies from the next page view. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • enabled boolean, required

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Create a project branchePOST /api/v1/projects/{project}/branches

Creates a shared branch line from the live site, or from another line named in from, and answers 201 with it. Needs the draft-create permission. A reserved name, a name that would read as the main line, or one an existing branch already has, is refused.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • name string, required, 1 to 60 characters
  • from string: The line to start from, by id; live or omitted, the live site.

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Get a project build envGET /api/v1/projects/{project}/build-env

Returns the project's build variables as stored, as a data object of names to values. They are not secrets; the build can print them. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List project buildsGET /api/v1/projects/{project}/builds

Lists the project's most recent builds, up to limit (30 by default, at most 200), with no further paging. Addresses of builds on another person's private session are left out. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • limit (query, integer, optional), at most 200, default 30

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • status string, required
    • trigger string, required
    • commit string | null, required
    • draft_id string | null, required
    • preview_url string | null, required
    • preview_open_url string | null, required: The build opened as the caller (signs a member in).
    • bytes number | null, required
    • duration_ms number | null, required
    • error string | null, required
    • failure one of: object | null, required

      One of:

        • kind "syntax" | "dependency" | "resources" | "unknown", required
        • first_error string | null, required

      2. null

    • warning string | null, required
    • superseded_by string | null, required
    • queued_at string, required: ISO 8601 timestamp.
    • started_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • finished_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project buildPOST /api/v1/projects/{project}/builds

Queues a build of ref (the live branch by default) and answers 202 with build_id and status. Needs the project-settings permission. trigger defaults to manual, and a manual build never reaches the live site; only production rebuilds and deploys the live branch, and is refused for a site never published. To put a draft live, use POST /api/v1/projects/{project}/drafts/{draft}/publish.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • ref string, at most 200 characters
  • trigger "manual" | "editor_bundle" | "production", default "manual"

202 Success.

What comes back
  • build_id string, required
  • status string, required
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Returns a preview address for a finished build (url), minting one if the build has none yet (minted). Needs the draft-read permission. Only a published version, or a build of a line the caller can see, qualifies; a manual build is refused, and so is a build whose files were not kept.

A read token may make this request too: it changes nothing a person can see.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • build (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • default Any other failure, as RFC 9457 problem details.

Get a project buildGET /api/v1/projects/{project}/builds/{id}

Returns one build with its status, trigger, commit, timings and any failure, plus its place in the queue while it waits (queue). Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • id (path, string)

200 Success.

What comes back
  • id string, required
  • status string, required
  • trigger string, required
  • commit string | null, required
  • draft_id string | null, required
  • preview_url string | null, required
  • preview_open_url string | null, required: The build opened as the caller (signs a member in).
  • bytes number | null, required
  • duration_ms number | null, required
  • error string | null, required
  • failure one of: object | null, required

    One of:

      • kind "syntax" | "dependency" | "resources" | "unknown", required
      • first_error string | null, required

    2. null

  • warning string | null, required
  • superseded_by string | null, required
  • queued_at string, required: ISO 8601 timestamp.
  • started_at one of: string | null, required

    One of:

    1. string. ISO 8601 timestamp.

    2. null

  • finished_at one of: string | null, required

    One of:

    1. string. ISO 8601 timestamp.

    2. null

  • queue one of: object | null, required: Where a waiting build stands; null once it runs.

    One of:

      • position number, required
      • ahead array of object, required

        A list of:

        • kind "publish" | "preview" | "editor" | "other", required
        • running boolean, required
        • elapsed_ms number, required

    2. null

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Get build logsGET /api/v1/projects/{project}/builds/{id}/logs

Returns the build's log as plain text. When there is no log, because the build has not run yet or its log was tidied away, the answer is still 200 with a sentence saying so. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • id (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List project collaboratorsGET /api/v1/projects/{project}/collaborators

Lists the people with a per-project grant on this project, beyond the team's own members, with their email, name, role and how they got access. Unpaged. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Delete a project collaboratorDELETE /api/v1/projects/{project}/collaborators/{userId}

Takes a person's per-project grant away, so they lose access to this project, and closes their open editor connections on it. Team membership is not touched. Needs the team-members permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • userId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List published content in a collectionGET /api/v1/projects/{project}/content/live/{collection}

Lists the entries of a collection as the live site has them: the live branch, or during a rollback the commit actually deployed (x-webentor-live-source says which). Answers a bare array with no paging. Needs the repo-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • collection (path, string)

200 Success.

What comes back

A list of:

  • slug string, required
  • fields object, required: The entry’s scalar fields (title, description, order, …); _invalid: true for a file that does not parse.
  • counts object, required: How many blocks a page has; empty for an entry that does not parse.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Get a published content entryGET /api/v1/projects/{project}/content/live/{collection}/{slug}

Returns one entry's document as the live site has it: from the live branch, or during a rollback from the commit actually deployed, as x-webentor-live-source says. Needs the repo-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • collection (path, string)
  • slug (path, string): May contain unencoded /: this is a path, not a single segment. Encoded slashes will not match.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List project deploy targetsGET /api/v1/projects/{project}/deploy-targets

Lists the project's deploy targets, without their credentials, and the providers this deployment offers under available. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • provider string, required
    • name string, required
    • is_default boolean, required
    • config object, required: The target’s non-secret settings.
    • has_credential boolean, required
    • live_build_id string | null, required
    • created_at string, required: ISO 8601 timestamp.
  • available array of object, required: The providers a new target may use here.

    A list of:

    • id string, required
    • label string, required
    • needs_credential boolean, required
    • atomic boolean, required
    • unverified boolean, required: Built and conformance-tested, never run against a real account of this vendor.
    • credential_fields array of object, required

      A list of:

      • name string, required
      • label string, required
      • type string, required
      • required boolean, required
      • help string
      • options array of object
      • default string | number | boolean
    • config_fields array of object, required

      A list of:

      • name string, required
      • label string, required
      • type string, required
      • required boolean, required
      • help string
      • options array of object
      • default string | number | boolean
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project deploy targetPOST /api/v1/projects/{project}/deploy-targets

Adds a deploy target for one of the installed providers and answers 201 with it; the credential is stored encrypted and never returned. Needs the project-settings permission. config must pass the provider's validation, a credential the provider requires must be present, name must be unused on the project, and the provider's own read-only check of settings and credential must pass.

A signed-in person who has stepped up (confirmed again with a passkey, a recovery code or an emailed code): a live session alone is refused, and no access token is accepted.

Who may call it: A signed-in person who has stepped up; no access token

Parameters

  • project (path, string)

Body (application/json)

  • provider string, required: One of this deployment’s providers, as GET …/deploy-targets lists them under available.
  • name string, required, 1 to 60 characters
  • config object, default {}: The provider’s settings, as its config_fields describe them.
  • credential object: The provider’s credential fields. Stored encrypted, never returned.
  • is_default boolean

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Update a project deploy targetPATCH /api/v1/projects/{project}/deploy-targets/{id}

Changes a deploy target's name, settings or credential. config is merged onto the stored settings, with null removing a key, and must still pass the provider's validation; credential: null clears the stored credential, and the name must stay unique. Needs the project-settings permission.

A signed-in person who has stepped up (confirmed again with a passkey, a recovery code or an emailed code): a live session alone is refused, and no access token is accepted.

Who may call it: A signed-in person who has stepped up; no access token

Parameters

  • project (path, string)
  • id (path, string)

Body (application/json)

  • name string, 1 to 60 characters
  • config object: Settings to change, merged onto the stored ones; null removes a key.
  • credential one of: object | null: A new credential (rotate), or null to clear the stored one.

    One of:

    1. object

    2. null

  • is_default boolean

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a project deploy targetDELETE /api/v1/projects/{project}/deploy-targets/{id}

Removes a deploy target. The provider is first asked to disconnect, which never takes the site down: whatever is already deployed there stays online. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • id (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Create a deploy target checkPOST /api/v1/projects/{project}/deploy-targets/{id}/check

Runs the provider's read-only check against the target's stored settings and credential, without deploying anything. A failed check is an answer, not an error: ok: false with an error sentence. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • id (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List project deploymentsGET /api/v1/projects/{project}/deployments

Lists the project's recent deployments, up to limit (30 by default, at most 200), with no further paging. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • limit (query, integer, optional), at most 200, default 30

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • account_id string, required
    • project_id string, required
    • build_id string, required
    • deploy_target_id string | null, required: The destination; null once it is removed.
    • type "preview" | "production", required
    • status "pending" | "running" | "succeeded" | "failed" | "superseded", required: superseded: skipped, because the target already served a newer commit.
    • url string | null, required
    • is_rollback boolean, required
    • error string | null, required
    • meta object, required
    • deployed_by string | null, required
    • created_at string, required: ISO 8601 timestamp.
    • deployed_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • commit_sha string | null, required
    • build_ms number | null, required: How long the build took; null when it was not measured.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project deploymentPOST /api/v1/projects/{project}/deployments

Deploys a finished build again, to every production target or to target_ids, and answers 202 with the queued deployments. Needs the deploy-production permission. The build must have succeeded with stored files, must not be an editor bundle, and must be the current live version; to serve an older one, use rollback.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • build_id string (uuid), required, matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: A build that succeeded, of this project.
  • target_ids array of string (uuid), 1 to 20 items: The targets to deploy to; omitted, every production target.

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Resolve divergence from the mirrorPOST /api/v1/projects/{project}/divergence/resolve

Ends the state a rollback leaves behind. keep_rollback: true makes the rollback permanent; false discards the revert draft and republishes the newest version. Needs the deploy-production permission (owners, admins and reviewers under review_required). The project must be diverged, and a revert draft that was already published can only be kept.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • draft_id string (uuid), required, matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: The revert draft the divergence opened.
  • keep_rollback boolean, required: Keep what the live site serves now (true), or publish the draft (false).

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

List project domainsGET /api/v1/projects/{project}/domains

Lists the custom domains connected to the project, each with its hostname, whether it is primary and its verification status, as one unpaged data list. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • account_id string, required
    • project_id string, required
    • hostname string, required
    • verification_status "pending" | "verified" | "failed", required
    • verification_token string, required: The value of the TXT record that proves the domain is yours.
    • tls_status "pending" | "active" | "failed", required
    • is_primary boolean, required
    • created_at string, required: ISO 8601 timestamp.
    • verified_at one of: string | null, required

      One of:

      1. string. ISO 8601 timestamp.

      2. null

    • last_checked_at one of: string | null, required: The last DNS check, pass or fail; null until the first.

      One of:

      1. string. ISO 8601 timestamp.

      2. null

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project domainPOST /api/v1/projects/{project}/domains

Connects a custom domain and answers 201 with the DNS records to create: a TXT record that proves control and a CNAME that points visitors at the site. Needs the project-settings permission. The hostname must be valid and not reserved, and a hostname verified on another project is refused.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • hostname string, required, 1 to 253 characters: The host name, e.g. www.example.com; accents are allowed.
  • is_primary boolean

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a project domainDELETE /api/v1/projects/{project}/domains/{domainId}

Disconnects a custom domain from the project; the site stops answering on that hostname right away, and the removal is recorded. Answers 204. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • domainId (path, string)

204 No content.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Verify a domainPOST /api/v1/projects/{project}/domains/{domainId}/verify

Checks the domain's DNS records now and answers whether it is verified, with a reason when it is not. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • domainId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Download an export archiveGET /api/v1/projects/{project}/downloads/{key}

Downloads the ZIP of a build's site that the zip provider stored, where key is exports/<project>/site-<build>.zip. Any other key is a 404; project export bundles are downloaded from the exports route instead. Needs the project-export permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • key (path, string): May contain unencoded /: this is a path, not a single segment. Encoded slashes will not match.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Export a projectPOST /api/v1/projects/{project}/export

Queues an export bundle of the project (full git history, the built site and media) and answers 202 with export_id and a download_url. Form entries, analytics and build variables are included only for roles allowed to read them. Needs the project-export permission.

A read token may make this request too: it changes nothing a person can see.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • Idempotency-Key (header, string, optional): Optional. A key the caller chooses, at most 160 characters, kept per team. A repeat of the same request (method, path and body) under the same key is answered with the first result and the header Idempotent-Replay: true, and the work is not done twice. The same key with a different request answers 409; so does a repeat sent while the first is still running, with Retry-After: 5.

202 Success. Headers: Idempotent-Replay.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • default Any other failure, as RFC 9457 problem details.

List project exportsGET /api/v1/projects/{project}/exports

Lists the project's recent export bundles and their status, up to limit (10 by default, at most 50), with how long bundles are kept (kept). Needs the project-export permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • limit (query, integer, optional), at most 50, default 10

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Get a project exportGET /api/v1/projects/{project}/exports/{exportId}

Downloads an export bundle as a ZIP. While it is being packed the answer is 202; a failed export answers 422 with the reason, and a removed one 410. A bundle holding data the caller's role may not read is refused. Needs the project-export permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • exportId (path, string)

200 Success.

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 410 No longer available. It existed and has been removed for good; asking again will not bring it back. (code is gone.)
  • 422 Could not be completed. The work was asked for and could not be done; detail says why. (code is unprocessable.)
  • default Any other failure, as RFC 9457 problem details.

Create a form entry importPOST /api/v1/projects/{project}/form-entries/import

Imports form entries from a ZIP with a forms/ folder, as an export writes it, sent as the raw body with content type application/zip. The answer counts what was imported, skipped and erased, and the files. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/zip)

string (binary). A ZIP holding a forms/ folder as an export writes it (forms/<form>.csv and forms/files/…), at most limits.max_blob_bytes of /.well-known/webentor-studio. Entries already here are skipped, so sending an archive twice adds nothing.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 413 Payload too large. (code is payload_too_large.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

List project formsGET /api/v1/projects/{project}/forms

Lists the project's forms that have entries, with each form's entry count and the time of the newest one. Needs the content-write permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List form entriesGET /api/v1/projects/{project}/forms/{formId}/entries

Lists a form's entries, newest first, with the form's field labels (fields). Page with limit (50 by default, at most 500) and before, the id of the last entry you have or a time. Needs the content-write permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • formId (path, string)
  • before (query, string, optional)
  • limit (query, integer, optional), at most 500, default 50

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a form entryDELETE /api/v1/projects/{project}/forms/{formId}/entries/{id}

Deletes one visitor's form entry and the files uploaded with it, and records the deletion in the audit log. This cannot be undone. Answers 204. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • formId (path, string)
  • id (path, string)

204 No content.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Get an entry fileGET /api/v1/projects/{project}/forms/{formId}/entries/{id}/files/{n}

Downloads the nth file (counting from 0, as the entry's files list numbers them) uploaded with a form entry, always as an attachment. Needs the content-write permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • formId (path, string)
  • id (path, string)
  • n (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Export a formGET /api/v1/projects/{project}/forms/{formId}/export

Downloads a form's entries as CSV. Past the export cap the file holds the newest entries, and the x-webentor-entries header says how many of the total it carries. Needs the content-write permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • formId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Get project historyGET /api/v1/projects/{project}/history

Returns the last 100 commits of ref (the live branch by default), newest first, as ref and an unpaged data list. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • ref (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List project importsGET /api/v1/projects/{project}/imports

Lists the project's site imports, newest first, up to limit (10 by default, at most 50), under imports. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • limit (query, integer, optional), at most 50, default 10

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project importPOST /api/v1/projects/{project}/imports

Queues an import of an existing site from url into a draft and answers 202 with the import's record; poll it for progress. Needs the draft-create permission. url must be a public http:// or https:// address, and only one import runs per project at a time.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • url string, required, 4 to 2000 characters: The site to import from: an http:// or https:// address.
  • max_pages integer, 1 to 200: Fetch at most this many pages.
  • on_conflict "replace" | "skip", default "replace": What to do with an entry that already exists.

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Get a project importGET /api/v1/projects/{project}/imports/{importId}

Returns one site import with its status and counts, the draft it wrote into (draft_id), and a per-page report. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • importId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List project mediaGET /api/v1/projects/{project}/media

Lists the media library of the live branch, or of a draft named in draft. Filter with search and mime; page with limit (50 by default, at most 200) and cursor, passing nextCursor back. On the live branch, unpublished counts files the live site does not serve yet. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • cursor (query, string, optional)
  • draft (query, string (uuid), optional)
  • limit (query, integer, optional), at most 200, default 50
  • search (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Upload project mediaPOST /api/v1/projects/{project}/media

Uploads a file (multipart field file, optional path) and answers 201 with the asset and commit; nothing is built. Needs the media-write permission. With draft_id it lands on that draft, which must be open; without it, it goes to the live branch, which is refused under review_required and needs the deploy-production permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (multipart/form-data)

  • file string (binary), required: The file. One over this Studio’s upload limit is refused with 413 payload_too_large.
  • draft_id string (uuid): The draft to add it to. Required when the project’s publish_policy is review_required; without it the file goes onto the live branch, which needs deploy:production, and out with the next publish.
  • path string: The file name to store it under; the uploaded file’s own name when omitted.

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a media assetDELETE /api/v1/projects/{project}/media/{assetId}

Deletes a media asset from a draft named in draft, or from the live branch, which needs the deploy-production permission. Needs the media-write permission. A file still used on pages is refused with 409 unless force=true.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • assetId (path, string)
  • draft (query, string (uuid), optional)
  • force (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Download a media assetGET /api/v1/projects/{project}/media/{assetId}/raw

Returns a media asset's bytes with its content type, read from the live branch or from a draft named in draft. The answer may be cached privately. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • assetId (path, string)
  • draft (query, string (uuid), optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Set project mirrorPUT /api/v1/projects/{project}/mirror

Connects a git remote to mirror the project to and queues a push of the full history; later changes are pushed too. The token is stored encrypted and never returned. Answers 201. Needs the project-settings permission. url must be a public HTTPS address with no credentials in it.

A signed-in person who has stepped up (confirmed again with a passkey, a recovery code or an emailed code): a live session alone is refused, and no access token is accepted.

Who may call it: A signed-in person who has stepped up; no access token

Parameters

  • project (path, string)

Body (application/json)

  • url string (uri), required, at most 2000 characters: An HTTPS remote, e.g. https://github.com/you/site.git, with no credentials in it.
  • username string, 1 to 120 characters: Cosmetic on most hosts; defaults to x-access-token, GitHub’s convention.
  • token string, required, 1 to 4000 characters: A personal access or deploy token. Stored encrypted, never returned.

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete project mirrorDELETE /api/v1/projects/{project}/mirror

Disconnects the repository mirror and deletes its stored token. Everything already pushed to the remote stays there. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Synchronise a mirrorPOST /api/v1/projects/{project}/mirror/sync

Queues a push to the connected mirror now and answers 202. A project with no mirror answers 404. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Set project preview accessPUT /api/v1/projects/{project}/preview-access

Sets how previews are protected: anyone with the link (link) or a passphrase (password). Needs the project-settings permission. password is required with access: password. Changing it takes effect on the next request.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • access "link" | "password", required
  • password string, 8 to 200 characters: The passphrase previews ask for; required with access: password.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Publish a projectPOST /api/v1/projects/{project}/publish

Publishes a site for the first time: queues a production build of the live branch head and answers 202 with build_id and commit. Needs the deploy-production permission, and under review_required an owner, admin or reviewer. A site already published is refused; after that, publish drafts.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • default Any other failure, as RFC 9457 problem details.

Get project publish manifestGET /api/v1/projects/{project}/publish-manifest

Returns where the project publishes compared with what the repository's webentor.cloud.json says, and what writing it would change. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create project publish manifestPOST /api/v1/projects/{project}/publish-manifest

Writes the project's current publish settings into webentor.cloud.json on the live branch as a commit, with no credentials in it. The answer gives the commit, what was withheld, and whether the file was unchanged. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List project redirectsGET /api/v1/projects/{project}/redirects

Lists the project's redirect rules as one unpaged data list, with the most a project may have (limit) and a description of the accepted rule syntax. Needs the draft-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

What comes back
  • data array of object, required

    A list of:

    • id string, required
    • account_id string, required
    • project_id string, required
    • from_path string, required
    • to_path string, required
    • status_code number, required
    • created_by string | null, required
    • created_at string, required: ISO 8601 timestamp.
  • limit number, required: The most redirects a project may have.
  • syntax string, required: What a source and a target may be, in words.
Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project redirectPOST /api/v1/projects/{project}/redirects

Adds redirects as one rule, a redirects list, or pasted text with one rule per line; a rule for a path that already has one replaces it. Answers 201. Needs the project-settings permission. Rules that would complete a redirect loop, or take the project past its redirect limit, are refused.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

One of:

    • from string, required, 1 to 1024 characters
    • to string, required, 1 to 1024 characters
    • status integer, -9007199254740991 to 9007199254740991: 301 by default.
    • redirects array of object, required, 1 to 500 items

      A list of:

      • from string, required, 1 to 1024 characters
      • to string, required, 1 to 1024 characters
      • status integer, -9007199254740991 to 9007199254740991: 301 by default.
    • text string, required, 1 to 200000 characters

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.) Or: Limit reached. A plan limit, not a transient failure; retrying unchanged will not help.
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a project redirectDELETE /api/v1/projects/{project}/redirects/{redirectId}

Removes one redirect rule from the project; the site stops applying it at once, and the removal is recorded. Answers 204. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • redirectId (path, string)

204 No content.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Get project repositoryGET /api/v1/projects/{project}/repository

Returns the project's repository: clone URL, size, backend, whether its hooks are current, the mirror, and its branches marked live, draft or other. view=mirror answers only the mirror. Needs the repo-read permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Roll back a projectPOST /api/v1/projects/{project}/rollback

Serves an earlier published build (build_id) again and answers 202. A revert draft is opened, and publishing is paused until the divergence is resolved. Needs the deploy-production permission (owners, admins and reviewers under review_required). The build must be a published version with its files kept, not an editor bundle.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • build_id string (uuid), required, matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$: An earlier build that was live, to serve again.

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Get a project upgradeGET /api/v1/projects/{project}/upgrade

Returns the upgrade plan for the project's stack: the version it is on (from) and can move to (to), the package pins that would change, release notes and advisories, whether it is current, and how the chassis files compare with the template. Changes nothing. Needs the repo-write permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project upgradePOST /api/v1/projects/{project}/upgrade

Opens an upgrade draft and queues its build, answering 201; it answers 200 when the project is already current or the upgrade is refused. Needs the repo-write permission. Each chassis path must be a chassis file that differs from the template, and customised ones must also be named in confirm.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • Idempotency-Key (header, string, optional): Optional. A key the caller chooses, at most 160 characters, kept per team. A repeat of the same request (method, path and body) under the same key is answered with the first result and the header Idempotent-Replay: true, and the work is not done twice. The same key with a different request answers 409; so does a repeat sent while the first is still running, with Retry-After: 5.

Body (application/json)

  • chassis array of string, at most 12 items: Chassis files to take from the release as well as the pins, by path: editor.config.ts, src/webentor.ts, src/virtual-modules.d.ts, src/content.config.ts, tsconfig.json, pnpm-workspace.yaml, scripts/assert-build.mjs, scripts/format-content.mjs, scripts/format-content.d.mts, .claude/hooks/guard-bash.mjs, .claude/hooks/validate-content.mjs, astro.config.ts.
  • confirm array of string, at most 12 items: The customised files among chassis, named a second time to say their changes may be replaced.

200 Success. Headers: Idempotent-Replay.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 409 Conflict. (code is conflict.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

List project webhooksGET /api/v1/projects/{project}/webhooks

Lists the project’s webhook endpoints: address, events, whether each is on, and since when one has been failing. Never a signing secret. Needs the project-settings permission. The events and their payloads are at GET /api/v1/webhook-events and on /docs/webhooks.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a project webhookPOST /api/v1/projects/{project}/webhooks

Adds an endpoint that is sent the project’s events, signed in the Standard Webhooks scheme. Answers 201 with the signing secret, shown this once; an assistant token gets a link where a person reveals it instead. Needs the project-settings permission. The address must be https and public; an unknown event name is refused.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)

Body (application/json)

  • url string (uri), required, at most 2000 characters: Where deliveries are sent: an https:// address reachable from the public internet.
  • events array of "project.created" | "draft.created" | "draft.submitted" | "draft.approved" | "draft.changes_requested" | "review.comment_added" | "draft.scheduled" | "draft.merged" | "draft.discarded" | "draft.published" | "draft.schedule_failed" | "code.published" | "import.finished" | "build.succeeded" | "build.failed" | "deploy.held" | "deployment.production" | "deployment.failed" | "deployment.rolled_back" | "domain.verified" | "domain.failed" | "export.finished" | "project.deletion_scheduled", at most 64 items, default []: The events this endpoint receives. Empty means every event, including ones added later.

201 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Update a project webhookPATCH /api/v1/projects/{project}/webhooks/{webhookId}

Changes an endpoint’s address or events, or switches it off and on with active. Switching it on forgets the failures that switched it off; what it missed is not sent unless you redeliver it from the log. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)

Body (application/json)

  • url string (uri), at most 2000 characters: A new address, checked as a new endpoint’s is.
  • events array of "project.created" | "draft.created" | "draft.submitted" | "draft.approved" | "draft.changes_requested" | "review.comment_added" | "draft.scheduled" | "draft.merged" | "draft.discarded" | "draft.published" | "draft.schedule_failed" | "code.published" | "import.finished" | "build.succeeded" | "build.failed" | "deploy.held" | "deployment.production" | "deployment.failed" | "deployment.rolled_back" | "domain.verified" | "domain.failed" | "export.finished" | "project.deletion_scheduled", at most 64 items: The events this endpoint receives. Empty means every event, including ones added later.
  • active boolean: false switches the endpoint off; true switches it on again and forgets its earlier failures.

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 422 Validation failed. The body carries an issues array describing each rejected field. (code is validation_failed.)
  • default Any other failure, as RFC 9457 problem details.

Delete a project webhookDELETE /api/v1/projects/{project}/webhooks/{webhookId}

Removes an endpoint, with its delivery log; nothing more is sent to it, including retries that were waiting. Answers 204, and the removal is recorded. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)

204 No content.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

List webhook deliveriesGET /api/v1/projects/{project}/webhooks/{webhookId}/deliveries

The endpoint’s delivery log, newest first: each event sent, its status, attempts, the code the endpoint answered and why it failed. Narrow it with status; page back with before, a delivery id. Kept for 30 days. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)
  • before (query, string (uuid), optional)
  • limit (query, integer, optional), at most 100, default 20
  • status (query, string, optional)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

Create a delivery redeliverPOST /api/v1/projects/{project}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver

Sends a delivery’s event to its endpoint once more, with the same message id, within a few seconds. Answers 202 with the new delivery. Refused while the endpoint is switched off, and for a test event. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)
  • deliveryId (path, string)

202 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • 409 Conflict. (code is conflict.)
  • default Any other failure, as RFC 9457 problem details.

Create a webhook rotate secretPOST /api/v1/projects/{project}/webhooks/{webhookId}/rotate-secret

Gives an endpoint a new signing secret and answers it once. The old secret keeps signing beside the new one for a day, so the receiving end can switch without missing a delivery. Needs the project-settings permission; an assistant token gets a reveal link instead.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • 404 Not found. Also returned when the resource exists but the caller may not see it, so that the two cannot be told apart. (code is not_found.)
  • default Any other failure, as RFC 9457 problem details.

Create a webhook testPOST /api/v1/projects/{project}/webhooks/{webhookId}/test

Sends a webhook.test event to this endpoint now and answers with the delivery: the status code it answered, or why nothing arrived. Works on an endpoint that is switched off, and does not count towards switching one off. Needs the project-settings permission.

Who may call it: A signed-in session, or an access token (write to change anything)

Parameters

  • project (path, string)
  • webhookId (path, string)

200 Success.

Errors it can answer
  • 401 Authentication required. (code is unauthenticated.)
  • 403 Not allowed. (code is forbidden.)
  • default Any other failure, as RFC 9457 problem details.

List webhook eventsGET /api/v1/webhook-events

Every event a webhook endpoint can be sent, in catalogue order, each with its label, a description, the day it first appeared and the JSON Schema of its payload. Public and cacheable: it names no team. The same list is on /docs/webhooks.

Who may call it: Anybody

200 Success.

Errors it can answer
  • default Any other failure, as RFC 9457 problem details.