Retrieve a signup form Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api-reference.usecommune.dev/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "REST API MCP server": {
    "url": "https://api-reference.usecommune.dev/mcp"
  }
}

Close
GET /forms/{form}

Read one signup form, by id or by the public_id in its embed code. Needs audience: read, on a newsletter the credential reaches. A deleted form answers 404.

Headers

  • Commune-Version string

    The contract version this request is written against. Every version published so far is a release date (YYYY-MM-DD), which is why the examples look like one, but the value is an opaque identifier: match it against the versions this API publishes rather than parsing it, because a future one may not be only a date. An unknown value answers 400 with invalid_version.

    Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships.

    Minimum length is 1.

Path parameters

  • form string Required

    The form's id, or its public_id: the short id in its embed code and its link, k7x2p9 in https://usecommune.com/f/k7x2p9.

Query parameters

  • expand string

    Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.

  • fields string

    Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

Responses

  • 200 application/json

    The form.

    Hide response attributes Show response attributes object
    • object string Required

      Always form.

      Value is form.

    • id string(uuid) Required

      Stable identifier.

    • public_id string Required

      The short id in the form's link and embed code, k7x2p9 in https://usecommune.com/f/k7x2p9. Accepted wherever {form} is, and fixed for the life of the form, because it is in every copy of the code already pasted.

      Format should match the following pattern: ^[a-z0-9]{6,16}$.

    • newsletter object Required

      The newsletter whose list the form signs people up to. A Ref unless newsletter is named in ?expand=.

      One of:
    • name string Required

      What the form is called in Commune: in the list of forms, in automations and in Growth. Readers never see it; they see heading.

      Minimum length is 1, maximum length is 100.

    • heading string Required

      The heading above the form. May be empty.

      Maximum length is 150.

    • description string Required

      A line under the heading. May be empty.

      Maximum length is 500.

    • button_label string Required

      The words on the button.

      Minimum length is 1, maximum length is 40.

    • email_placeholder string Required

      The placeholder in the email field. May be empty.

      Maximum length is 80.

    • name_field object Required

      Whether the form asks for a name as well as the address, and how the field reads. Off on a new form.

      A signup's name is kept with the subscription, only ever filling an empty one, and is written when the reader confirms. It is what the subscriber.display_name merge tag says for somebody without a Commune account; the account's own name wins for somebody with one. Not to be confused with the form's own name, which readers never see.

      Additional properties are NOT allowed.

      Hide name_field attributes Show name_field attributes object
      • mode string Required

        off draws no name field. optional draws one a reader may leave empty. required draws one they must fill in, and a signup without a name answers 422 with code: name_required.

        Values are off, optional, or required.

      • label string Required

        The field's label: what a screen reader announces, the visible label in the plain HTML embed, and what the styled form shows in the field when placeholder is empty. Defaults to First name, and a label that says "first" or "given" asks the browser to fill in a first name rather than a whole one.

        Minimum length is 1, maximum length is 40.

      • placeholder string Required

        The placeholder in the name field. May be empty.

        Maximum length is 80.

    • style object Required

      How the script embed draws the form. Text, fonts and the page behind it come from the creator's own site; this is the shape and the one brand colour. The plain HTML embed has no styles and ignores it.

      Additional properties are NOT allowed.

      Hide style attributes Show style attributes object
      • layout string Required

        stacked puts the button under the email field, one_line beside it.

        Values are stacked or one_line.

      • background string Required

        page draws the form straight on the site's own background, card on a subtle panel of its own.

        Values are page or card.

      • corners string Required

        The corners of the field and the button.

        Values are rounded, pill, or square.

      • button_color string Required

        The button's colour, as a lowercase hex colour. A three digit or uppercase colour is accepted on a write and stored like this.

        Format should match the following pattern: ^#[0-9a-f]{6}$.

    • tag_ids array[string(uuid)] Required

      The newsletter's tags this form gives the people who join through it: on confirming for somebody new, straight away for somebody already on the list. A tag deleted since is skipped when the form applies them.

      Not more than 20 elements.

    • after_signup object Required

      What somebody sees right after submitting the form, before they have confirmed anything.

      Additional properties are NOT allowed.

      Hide after_signup attributes Show after_signup attributes object
      • action string Required

        message replaces the form with message; redirect sends them to url.

        Values are message or redirect.

      • message string Required

        The message shown in place of the form. Kept when action is redirect, so switching back does not lose it.

        Minimum length is 1, maximum length is 500.

      • url string(uri) | null Required

        Where redirect sends them: an http or https page of the creator's. Required when action is redirect, and kept when it is not.

        Maximum length is 2000.

    • after_confirm object Required

      Where somebody goes after clicking the link in the confirmation email.

      Additional properties are NOT allowed.

      Hide after_confirm attributes Show after_confirm attributes object
      • action string Required

        thank_you is Commune's own page, saying they are subscribed and offering a way back to the page the form was on. redirect sends them to url, which is where to hand over a download or say thanks in the creator's own voice.

        Values are thank_you or redirect.

      • url string(uri) | null Required

        Where redirect sends them: an http or https page. Required when action is redirect, and kept when it is not.

        Maximum length is 2000.

    • confirmation_email object Required

      The email a signup gets asking them to confirm, in the creator's words. Every setting is null where it falls back, one setting at a time: a form's own value, else the newsletter's default (GET /newsletters/{newsletter}/form-defaults), else Commune's email, which is "Confirm your subscription to" and the newsletter's name, a line naming the newsletter and the site the form was on, a violet Confirm subscription button on a white card, and "Didn't sign up? Ignore this email and you won't hear from us again." under it.

      The confirm link is always there. It is the button, between body and footnote, and no setting here removes or moves it: the creator writes the words around it.

      Additional properties are NOT allowed.

      Hide confirmation_email attributes Show confirmation_email attributes object
      • subject string | null Required

        The subject line. One line.

        Minimum length is 1, maximum length is 150.

      • body string | null Required

        The text above the button, as plain text. A blank line starts a new paragraph and a single line break stays one. No HTML and no Markdown: what is written is what the reader sees.

        Minimum length is 1, maximum length is 2000.

      • button_label string | null Required

        The words on the confirm button.

        Minimum length is 1, maximum length is 40.

      • footnote string | null Required

        The small print under the button. An empty string means none.

        Maximum length is 500.

      • button_color string | null Required

        The button's colour, as a lowercase hex colour. Its text is black or white, whichever reads better on it.

        Format should match the following pattern: ^#[0-9a-f]{6}$.

      • corners string | null Required

        The corners of the button and of the card.

        Values are rounded, pill, square, or null.

      • background string | null Required

        card sets the text on a white card on a light page; page drops the card and sets it straight on the page.

        Values are card, page, or null.

    • embed object Required

      The three ways to put the form on a site, ready to paste. For a form of your own instead, see Build your own signup form.

      Additional properties are NOT allowed.

      Hide embed attributes Show embed attributes object
      • script string Required

        One script tag. Renders the form where it is pasted, with the settings saved on the form and the page's own font and text colour, and picks up later changes by itself. Works in WordPress, Ghost, Webflow, Framer and plain HTML.

      • html string Required

        A plain form with no JavaScript and no styles, for a site that wants its own CSS on it. Keep the hidden website field: it is how the form tells a bot from a person. When name_field is on it has a name input above the email one, required when the mode is. When consent is on it has a required consent checkbox below the email field, with the form's words and its privacy policy link.

      • url string(uri) Required

        A page with just this form, for a link in bio, show notes or a QR code. Both embeds post their signups here too.

    • subscriber_count integer Required

      How many people joined through this form, counting each person once however many times they signed up. Includes people who were already on the list when they did.

      Minimum value is 0.

    • subscribers_this_week integer Required

      Of those, how many first joined in the last seven days.

      Minimum value is 0.

    • created_at string(date-time) Required

      When the form was created.

    • updated_at string(date-time) Required

      When the form's settings last changed.

  • 400 application/json

    The request was malformed, and the same request will fail the same way until it is changed. param names the parameter or header at fault when there is exactly one, and allowed_values lists what it accepts when that is a finite set. The code is bad_request for every case below except the last.

    • A query parameter: one the operation does not have, a value outside its set, range or format (an unparseable cursor, an unknown expand path or fields name, an identifier that is not a UUID), or a required one left out, such as q on a search or newsletter when the credential reaches more than one.
    • The request body: not JSON, not the shape the operation reads, a property it does not write, or a value of the wrong type, length or format. param is absent here, since the body is not a parameter, and the message names the property.
    • The Idempotency-Key header, on an operation that changes something: missing, or a value this API will not store.
    • An unrecognised Commune-Version, which answers with its own code, invalid_version, because it is never fixed by changing the body.
    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

  • 401 application/json

    No credential was presented, or it is malformed, unknown, revoked or expired, or it is an access token minted for a different audience.

    Every one of these answers identically, down to the wording and the headers, so a refusal never confirms that a string was once real.

    Hide headers attribute Show headers attribute
    • WWW-Authenticate string

      The authentication scheme this API accepts, and where to find out how to get a credential for it. Always Bearer realm="Commune API", resource_metadata="https://api.usecommune.com/.well-known/oauth-protected-resource".

      resource_metadata is the RFC 9728 pointer to this API's protected resource metadata, which names the authorization server an OAuth client should send its user to. A client holding an API key can ignore it. The header carries no error parameter, not even error="invalid_token", because it describes what this API accepts rather than what was wrong with the credential sent, and the reasons above are deliberately indistinguishable.

      There is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

  • 403 application/json

    The credential is valid but is not allowed to do this. Two codes answer with this status, and error.code says which.

    insufficient_scope: it does not hold the permission. The operation needs, say, audience: read on the newsletter addressed, and this credential holds less than that there. allowed_values carries the permission that was needed, and the message says what the credential does hold on that newsletter, because a credential granted the wrong family and a credential belonging to somebody whose standing on the team has narrowed look identical without it. The answer can differ per newsletter: the same credential may be allowed here and refused on the next one it reaches.

    The same code answers an operation that needs the account permission from a credential that does not carry it. That permission is about the person a credential belongs to rather than about any newsletter, so nothing granted on a newsletter adds up to it. It is granted on the credential itself, when a key is minted or when an authorization asks for account:read.

    And it answers a parameter the credential may send, but not with the value it sent: a filter a credential holding only read permissions may not use, or an expand path whose rows need a permission the operation does not. param names the parameter, and allowed_values carries what this credential may send instead, or is absent when it may send nothing there at all.

    forbidden: it may not act here at all. Either the credential does not reach the newsletter addressed, because it was never granted it or because the person it belongs to can no longer act on it, or it reaches no newsletter at all; param is newsletter, and GET /newsletters lists the ones it does reach. Or, on DELETE /api-keys/{key}, the credential named belongs to somebody else. Neither carries allowed_values, because there is no value to send instead.

    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

  • 404 application/json

    No such resource, or the key is not allowed to know that it exists. Commune answers 404 rather than 403 where distinguishing the two would leak the existence of private content.

    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

  • 429 application/json

    Too many requests. Back off and retry after the interval named by the Retry-After response header.

    One of the budgets in RateLimit-Policy ran out, and the RateLimit-* headers on this response say which and when it resets.

    Hide headers attribute Show headers attribute
    • Retry-After integer

      Seconds to wait before retrying.

      Minimum value is 1.

    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

  • 500 application/json

    Something failed inside Commune. The request may be retried.

    Hide response attribute Show response attribute object
    • error object Required

      Additional properties are NOT allowed.

      Hide error attributes Show error attributes object
      • code string Required

        The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

        Two of these share a status with a neighbour and exist because what a caller does next is different. invalid_version is a 400 that is never fixed by changing the request body. not_commune_newsletter is a 422 that is never fixed by changing the request at all: it says the newsletter's articles are published somewhere else and mirrored into Commune afterwards, so Commune cannot write one. Its page at https://usecommune.dev/errors/not_commune_newsletter, like every code's, is its docs_url, and it covers moving a newsletter onto Commune's own publishing, which is the only thing that resolves it.

        Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, not_commune_newsletter, rate_limited, internal_error, or service_unavailable.

      • message string Required

        A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

      • param string

        The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

      • allowed_values array[string]

        Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

        It repeats what message says in prose, so a caller can correct a request from this one response: the array is what a program branches on, the sentence is what a person or a model reads.

        On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

        On an insufficient_scope failure there is usually no parameter at fault and param is absent, and this carries the one permission that was needed, written the way the permission table writes it, such as content: read. The exception is a credential that may call the operation but not with one value of a parameter, such as ?expand=subscriber on listNewsletterInsights without audience: read: then param names the parameter and this carries the values this credential may send instead.

      • request_id string

        Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

      • docs_url string(uri)

        Link to the documentation for this error code: always https://usecommune.dev/errors/ followed by the code, a page on what the code means, what usually causes it and how to fix it.

GET /forms/{form}
curl \
 --request GET 'https://api.usecommune.com/forms/{form}' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Commune-Version: 2026-08-26"
Response examples (200)
{
  "object": "form",
  "id": "5b7e2c10-3d4f-4a5b-8c6d-7e8f9a0b1c2d",
  "public_id": "k7x2p9",
  "newsletter": {
    "object": "newsletter",
    "id": "7d3f1c02-58a1-4a4e-9a0b-2f6d1c9e4411"
  },
  "name": "Checklist download",
  "heading": "Get the launch checklist",
  "description": "Twelve things to check before you hit send, as a one-page PDF.",
  "button_label": "Send me the checklist",
  "email_placeholder": "you@example.com",
  "name_field": {
    "mode": "optional",
    "label": "First name",
    "placeholder": ""
  },
  "consent": {
    "enabled": false,
    "text": "I want to receive this newsletter and agree to the [privacy policy].",
    "privacy_policy_url": null
  },
  "style": {
    "layout": "one_line",
    "background": "card",
    "corners": "pill",
    "button_color": "#1a73e8"
  },
  "tag_ids": [
    "aa11bb22-cc33-4d44-8e55-ff6677889900"
  ],
  "after_signup": {
    "action": "message",
    "message": "Check your inbox and click the link to confirm your subscription.",
    "url": null
  },
  "after_confirm": {
    "action": "redirect",
    "url": "https://example.com/checklist/thanks"
  },
  "confirmation_email": {
    "subject": "Confirm to get the launch checklist",
    "body": null,
    "button_label": "Confirm and send the checklist",
    "footnote": null,
    "button_color": "#1a73e8",
    "corners": "pill",
    "background": null
  },
  "embed": {
    "script": "<script src=\"https://usecommune.com/f/k7x2p9.js\" async></script>",
    "html": "<form action=\"https://usecommune.com/f/k7x2p9\" method=\"post\">\n  <label for=\"commune-name-k7x2p9\">First name</label>\n  <input id=\"commune-name-k7x2p9\" type=\"text\" name=\"name\" autocomplete=\"given-name\">\n  <label for=\"commune-email-k7x2p9\">Email</label>\n  <input id=\"commune-email-k7x2p9\" type=\"email\" name=\"email\" placeholder=\"you@example.com\" required>\n  <!-- Keep this hidden field. It catches spam bots. -->\n  <input type=\"text\" name=\"website\" tabindex=\"-1\" autocomplete=\"off\" aria-hidden=\"true\" style=\"display:none\">\n  <button type=\"submit\">Send me the checklist</button>\n</form>",
    "url": "https://usecommune.com/f/k7x2p9"
  },
  "subscriber_count": 312,
  "subscribers_this_week": 41,
  "created_at": "2026-11-02T09:30:00Z",
  "updated_at": "2026-11-14T16:05:00Z"
}
Response examples (400)
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}
Response examples (401)
# Headers
WWW-Authenticate: string

# Payload
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}
Response examples (403)
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}
Response examples (404)
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}
Response examples (429)
# Headers
Retry-After: 42

# Payload
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}
Response examples (500)
{
  "error": {
    "code": "bad_request",
    "message": "Newsletter not found.",
    "param": "cursor",
    "allowed_values": [
      "subscribed",
      "unsubscribed",
      "bounced",
      "complained",
      "pending"
    ],
    "request_id": "req_01j9c8h1q7m3n4p5r6s7t8u9v0",
    "docs_url": "https://usecommune.dev/errors/not_found"
  }
}