Unpublish a formMenu

Unpublish a form

POST/v1/forms/{id}/unpublish

Requires an API key with the forms:write scope. About keys and scopes

Works with integration and partner keys, not agent keys.

Safe to retry: a repeat returns the current state, or 409 once it has moved on from it. About idempotency

Sets the form back to draft: its link and embeds stop taking submissions until it is published again. Its submissions and contacts stay. Unpublishing a draft returns it. Agent keys are refused with 403 AGENT_KEY_REFUSED.

Path parameters

idstringrequired

The form's id.

uuid

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Idempotency-Keystringoptional

Makes a retry safe: a repeat with the same key and body within 24 hours gets the first response again, with Idempotency-Replay: true. The same key with another request is 409 IDEMPOTENCY_KEY_REUSED; while the first is still running, 409 IDEMPOTENCY_KEY_IN_USE; after an unsafe first request failed or never returned, 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN. Use a new key, such as a UUID, for each new request.

8–255 characters

Returns

Returns 200 OK with a Form in data. It can also return 409 Conflict; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKThe form, a draft again.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.

idstringrequired

uuid

publicIdstringrequired

The id the public embed and hosted page use.

pattern ^[a-z0-9]{24}$

slugstring | nullrequired

The readable part of the form's link; null uses publicId alone.

namestringrequired

headingstring | nullrequired

What visitors see above the fields; null shows none.

introstring | nullrequired

A line or two under the heading; null shows none.

locationstringrequired

Where the form sits on your site, a label you choose (website-footer, checkout-page). Recorded on each submission, as properties.location on its contact.form_submitted event and on the form.submitted webhook, which is how a segment or journey uses it.

urlstringrequired

The hosted form's link, by its slug when it has one, else its publicId. It serves once the form is published.

uri

statusstringrequired

Whether the form accepts submissions: published once POST /v1/forms/{id}/publish puts it live, draft until then or after unpublishing.

one of draft, published

listIdstring | nullrequired

The list every submitter is added to.

uuid

fieldsobject[]required

The fields, top to bottom.

6 child attributes

keystringrequired

Where the response goes, such as email or attributes.plan.

typestringrequired

The input the visitor sees.

one of email, text, textarea, select, checkbox, date, phone

labelstringrequired

The text shown beside the field.

placeholderstringoptional

Hint text shown inside the empty field.

requiredbooleanrequired

Whether the visitor must fill it in.

optionsobject[]optional

The choices of a select or checkbox field.

2 child attributes

valuestringrequired
labelstringrequired

hiddenFieldsmap<string, object>required

Values saved on each submitter with no field shown: fixed, or taken from the link.

at most 50 keys · keys: pattern ^[\p{L}\p{N}\p{M}_.-]{1,64}$

One of 2 shapes

With value

2 child attributes

source"fixed"required

valuestringrequired

Saved as it is on every submitter.

up to 1,000 characters

With param

2 child attributes

source"link"required

paramstringrequired

The link parameter it takes its value from, such as utm_campaign; left unset when the link has none.

pattern ^[A-Za-z0-9_.-]{1,64}$

shareobject | nullrequired

How the form's link previews, as set; null falls back entirely.

3 child attributes

titlestringoptional
descriptionstringoptional
imageUrlstringoptional: uri

acceptingSubmissionsbooleanrequired

false: closed by hand, whatever its closing time and limit.

closesAtstring | nullrequired

When the form closes, if ever.

date-time

maxSubmissionsinteger | nullrequired

The submissions it closes at, if any.

closedMessagestring | nullrequired

What a closed form shows; null shows the default wording.

submissionCountintegerrequired

Submissions taken so far (honeypot catches aside), counted for the limit.

min 0

allowedOriginsstring[]required

Site origins the embed may load from.

refusedOriginsobject[]required

Origins an embed was refused from lately, newest first, not counting any since added to allowedOrigins; add one there to approve it.

2 child attributes

originstringrequired

The origin that was refused.

lastRefusedAtstringrequired

When it was last refused.

date-time

doubleOptInbooleanrequired

Whether submitters must confirm by email before they are subscribed.

notifyUserIdsstring[]required

Users of this workspace told about each submission.

themeFormThemerequired

12 child attributes

modestringoptional

Light or dark defaults for every colour left unset; light when unset.

one of light, dark

accentColorstringoptional

Colour of the button and focus outlines, as #RRGGBB.

pattern ^#[0-9a-fA-F]{6}$

backgroundColorstring | nulloptional

The page and form background, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

textColorstring | nulloptional

Headings, labels and text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

buttonColorstring | nulloptional

The button's fill; unset, the accent colour, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

buttonTextColorstring | nulloptional

The button's text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

fontFamilystringoptional

The font's id: a generic style (system, sans, serif, mono) or a named font the forms host serves itself. A font emails also offer has the same id there (EmailFont).

one of system, sans, serif, mono, inter, roboto, open-sans, lato, montserrat, poppins, source-sans-3, nunito, raleway, work-sans, dm-sans, manrope, ibm-plex-sans, noto-sans, rubik, karla, merriweather, lora, playfair-display, libre-baskerville, source-serif-4, eb-garamond, ibm-plex-mono, jetbrains-mono

borderRadiusintegeroptional

Corner rounding of inputs and the button, in px, where inputs.borderRadius or button.borderRadius does not set its own.

min 0 · max 24

buttonLabelstringoptional

Text on the submit button.

1–40 characters

inputsobjectoptional

How fields look; each part optional.

9 child attributes

widthstringoptional

fit (unset): a short answer's field is 320px and a long one fills the form; full: every field fills the form; fixed: every field widthPx wide at most.

one of fit, full, fixed

widthPxintegeroptional

With width fixed: the width, in px.

min 200 · max 720

heightintegeroptional

In px.

min 28 · max 64

backgroundColorstring | nulloptional

The field background, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

placeholderColorstring | nulloptional

Placeholder text, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

borderColorstring | nulloptional

The field border, as #RRGGBB; unset or null for the mode's default.

pattern ^#[0-9a-fA-F]{6}$

borderWidthintegeroptional

In px.

min 0 · max 4

borderRadiusintegeroptional

In px; unset, the top-level borderRadius.

min 0 · max 32

spacingintegeroptional

The gap below each field, in px.

min 0 · max 48

buttonobjectoptional

How the submit button looks; each part optional.

5 child attributes

widthstringoptional

Fit its label, or the form width.

one of auto, full

heightintegeroptional

In px.

min 28 · max 64

alignstringoptional

one of start, center, end

fontSizeintegeroptional

In px.

min 12 · max 24

borderRadiusintegeroptional

In px; unset, the top-level borderRadius.

min 0 · max 32

layoutobjectoptional

2 child attributes

pageWidthintegeroptional

The form's widest, in px.

min 360 · max 960

baseFontSizeintegeroptional

Body text size, in px.

min 12 · max 20

displayobjectrequired

One of 2 shapes

Inline

1 child attribute

mode"inline"required

Popup

7 child attributes

mode"popup"required

delayDurationOrZerooptional

How long after the page loads it opens, at most 10 minutes. Defaults to 5 seconds.

2 child attributes

valueintegerrequired: min 0
unitstringrequired: one of seconds, minutes, hours, days

scrollPercentintegeroptional

Opens once the visitor has scrolled this far down the page.

min 1 · max 100

exitIntentbooleanoptional

Opens when the visitor moves to leave the page (desktop only).

urlMatchobjectoptional

Limits which pages the popup opens on.

2 child attributes

containsstring[]optional

Show only on pages whose URL contains one of these.

at most 20 items

excludesstring[]optional

Never show on pages whose URL contains one of these.

at most 20 items

hideForDurationOrZerooptional

How long it stays away once closed, at most 365 days. Defaults to 7 days.

2 child attributes

valueintegerrequired: min 0
unitstringrequired: one of seconds, minutes, hours, days

hideAfterSubmitbooleanoptional

Whether it stays away after a signup. Defaults to true.

captchaobject | nullrequired

Where the CAPTCHA comes from; null while it is off. Secrets never show.

One of 2 shapes

KiroraCaptchaSetting

1 child attribute

mode"kirora"required

OwnCaptchaSetting

2 child attributes

mode"own"required
siteKeystringrequired

consentobjectrequired

2 child attributes

requiredtruerequired: Always true: the visitor must tick the consent box.
labelstringrequired: The consent text shown beside the box.

successobjectrequired

One of 2 shapes

Show a message

2 child attributes

type"message"required
messagestringrequired: Shown in place of the form.

Redirect

2 child attributes

type"redirect"required

redirectUrlstringrequired

An http(s) address the visitor is sent to.

uri

archivedAtstring | nullrequired

When it was archived; an archived form is left out of the list and stops serving.

date-time

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

Headers on `200 OK`

Idempotency-Replaystringoptional

true when this is the stored response to an earlier request with the same key.

one of true

curl -X POST https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/unpublish \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/unpublish', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/unpublish",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
response.raise_for_status()
data = response.json()["data"]

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/unpublish", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/forms/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/unpublish");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "id": "0192f3e1-2b3c-7d4e-9f50-6b7c8d9e0f1a",
    "publicId": "frm7k2m9q4x1c8v3b6n5t0za",
    "slug": "acme-newsletter",
    "name": "Newsletter signup",
    "heading": "Join the Acme Shop newsletter",
    "intro": "New arrivals and offers, once a week.",
    "location": "website-footer",
    "url": "https://forms.kirora.io/f/acme-newsletter",
    "status": "draft",
    "listId": "0192f3a2-1b3c-7e5d-8a21-4f6a7b8c9d0e",
    "fields": [
      {
        "key": "email",
        "type": "email",
        "label": "Email address",
        "placeholder": "[email protected]",
        "required": true
      },
      {
        "key": "firstName",
        "type": "text",
        "label": "First name",
        "required": false
      }
    ],
    "hiddenFields": {
      "signup_campaign": {
        "source": "link",
        "param": "utm_campaign"
      }
    },
    "share": {
      "title": "Get the Acme Shop newsletter"
    },
    "acceptingSubmissions": true,
    "closesAt": null,
    "maxSubmissions": null,
    "closedMessage": null,
    "submissionCount": 1240,
    "allowedOrigins": [
      "https://acme-shop.com"
    ],
    "refusedOrigins": [],
    "doubleOptIn": true,
    "notifyUserIds": [],
    "theme": {
      "accentColor": "#b4461f",
      "fontFamily": "sans",
      "buttonLabel": "Subscribe"
    },
    "display": {
      "mode": "inline"
    },
    "captcha": null,
    "consent": {
      "required": true,
      "label": "I agree to receive emails from Acme Shop and can unsubscribe at any time."
    },
    "success": {
      "type": "message",
      "message": "Thanks. Check your inbox to confirm."
    },
    "archivedAt": null,
    "createdAt": "2026-10-01T09:30:00.000Z",
    "updatedAt": "2026-10-02T14:05:00.000Z"
  }
}

Unpublish a form

Path parameters

Header parameters

Returns

Headers on 200 OK

Headers on `200 OK`