Signup

Start an API signup handoff (7-day free trial, card required)

Public endpoint for agents and AI tools to start a posterly signup with only an email address. By default this creates a posterly account (or reuses an unconfirmed, never-paid one that an earlier signup created) and starts Stripe Checkout for the monthly Starter plan plus the API/MCP add-on. Checkout starts a 7-day free trial: a valid card is required, nothing is charged today, you are charged on day 8 unless you start the paid plan sooner, and API and MCP are limited during the trial (20 writes and 100 reads per hour, 25 posts in total, no batch posting, AI video, webhooks or OAuth clients). An account that already had a trial is charged at checkout instead (billing.trial_period_days is 0). Agent signup is monthly only with the add-on. If the email already belongs to a real posterly account, the endpoint changes nothing, sends no email, creates no Checkout session and returns 200 with status sign_in_required, login_url and, when an OAuth handoff was supplied, oauth_authorize_url. The response is the same for every existing account and reveals no plan or billing state. The response always includes payment (trial terms, merchant and what an agent may do) and a billing block with trial, trial_period_days, card_required and charged_today. Nothing is due today, so payment.amount is null. Do not complete the trial Checkout with a one-time virtual card: it becomes the card on file and the day 8 charge fails. agent_pay (a prepaid PaymentIntent for a one-time Link virtual card, behind ENABLE_AGENT_CARD_PAY) is not available during a trial and is null. Browser Checkout is the path. The response includes poll_url so the AI conversation can report checkout/password/authorization progress. Password setup, social OAuth, and publish approval stay in the browser. No API key is returned from this endpoint. After the card is saved and the trial starts, the verified user lands on the API page and posterly auto-creates the first API key if none exists, showing it once. OAuth clients receive their access token after consent.

post/api/v1/signup

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/signup
  • Auth: none required

Request body

emailstring email required
namestring nullable
tier'starter' | 'pro' | 'power_user' | 'agency'
interval'month' | 'year'

Public API signup does not support weekly billing. With the API add-on, billing is monthly. Without the add-on, monthly or yearly is allowed (the Agency plan is monthly or yearly only).

api_addonboolean

When true, checkout includes the API/MCP add-on, which trials with the plan (limited API and MCP during the trial). No API key is created until the card is saved and access is active.

return_pathstring

Safe same-origin path to open after checkout/login when no OAuth handoff is requested.

sourcestring nullable

Optional caller identifier for analytics, for example chatgpt or posterly-cli.

client_idstring nullable

Optional OAuth public client id for an agent handoff after checkout.

redirect_uristring uri nullable

Required with client_id; must match the registered OAuth client redirect URI.

scopestring nullable
statestring nullable
code_challengestring nullable

PKCE S256 challenge supplied by the OAuth client.

code_challenge_method'S256' nullable
tos_acceptedboolean

Set true only after the user has explicitly confirmed, in this conversation, that they accept the posterly terms at https://www.poster.ly/terms. When agent card pay is available, agent_pay.client_secret is withheld until this is true (here or via a later call to the /pay endpoint).

Example request

{
  "email": "owner@example.com",
  "name": "Example Owner",
  "tier": "starter",
  "api_addon": true,
  "source": "chatgpt"
}

Response

Signup handoff created (status checkout_required), or the email already has an account (status sign_in_required)

status'checkout_required' | 'sign_in_required' | 'active' required

checkout_required: a new signup was started and a card is needed to start the free trial. sign_in_required: the email already belongs to a posterly account, so nothing was started, changed or emailed; ask the user to sign in at login_url. active is retained for older clients and is no longer returned.

payment_requiredboolean required
checkout_urlstring uri nullable

Raw Stripe Checkout URL. Agents should prefer checkout_redirect_url because Stripe URLs can include fragments that are easy to truncate.

checkout_redirect_urlstring uri nullable

posterly-hosted checkout handoff URL. Send this to users so the browser redirects to the full Stripe URL safely.

checkout_session_idstring nullable
poll_urlstring uri nullable

Poll this URL from the AI conversation to learn when the card is saved, password setup, and agent authorization progress.

complete_urlstring uri nullable

Human browser URL for completing the signup after Stripe checkout (the trial has started and the card is saved).

dashboard_urlstring uri required
login_urlstring uri required

Where the user signs in. For sign_in_required this is the next step.

oauth_authorize_urlstring uri nullable

OAuth authorize URL when the request supplied a registered client_id, redirect_uri and PKCE challenge. Present on sign_in_required so the agent connection can continue after sign-in.

status_messagestring

Human-readable explanation of status. Always present on sign_in_required, which also repeats it as message.

messagestring

Same text as status_message. Returned on sign_in_required only.

email_sentboolean required

Always false. For checkout_required, posterly does not email an address that nobody has verified, so no signup email is sent at this step. Give the user checkout_redirect_url in your conversation instead. Once the card is saved and the trial starts, posterly emails a password-setup link to the (now verified) address.

Example response

{
  "status": "checkout_required",
  "payment_required": true,
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "checkout_redirect_url": "https://www.poster.ly/agents/signup/checkout?session_id=cs_live_123",
  "checkout_session_id": "cs_live_123",
  "poll_url": "https://www.poster.ly/api/v1/signup/sessions/cs_live_123",
  "complete_url": "https://www.poster.ly/agents/signup/complete?session_id=cs_live_123",
  "dashboard_url": "https://www.poster.ly/dashboard/api?api_signup=success",
  "login_url": "https://www.poster.ly/login?next=%2Fdashboard%2Fapi%3Fapi_signup%3Dsuccess",
  "oauth_authorize_url": null,
  "payment": {
    "amount": null,
    "currency": "usd",
    "amount_display": null,
    "billing": "monthly_subscription",
    "description": "posterly Starter plan + API access, billed monthly, with a 7-day free trial (card required, charged on day 8)",
    "trial_period_days": 7,
    "charged_today": false,
    "merchant_name": "posterly",
    "merchant_url": "https://www.poster.ly",
    "checkout_redirect_url": "https://www.poster.ly/agents/signup/checkout?session_id=cs_live_123",
    "pay_with": "stripe_hosted_checkout",
    "agent_wallet": {
      "supported": true,
      "how": "This Checkout starts a free trial that requires a valid card. Nothing is charged today. Do not use a one-time virtual card: it becomes the card on file and the day 8 charge fails. Use a reusable card the person approved, or send checkout_redirect_url to the person.",
      "spend_request": {
        "merchant_name": "posterly",
        "merchant_url": "https://www.poster.ly",
        "amount": null,
        "currency": "usd",
        "context": "7-day free trial of posterly Starter plan + API access, charged on day 8"
      }
    }
  },
  "signup_session": {
    "id": "cs_live_123",
    "status": "checkout_pending",
    "checkout_redirect_url": "https://www.poster.ly/agents/signup/checkout?session_id=cs_live_123",
    "poll_url": "https://www.poster.ly/api/v1/signup/sessions/cs_live_123",
    "complete_url": "https://www.poster.ly/agents/signup/complete?session_id=cs_live_123",
    "status_message": "Waiting for the user to complete secure Stripe checkout and save a card. Start a 7-day free trial of posterly with API and MCP access. A card is required. You are charged on day 8, unless you start the paid plan sooner. API and MCP are limited during the trial."
  },
  "email_sent": false,
  "account": {
    "email": "owner@poster.ly",
    "created": true
  },
  "billing": {
    "mode": "base_and_api_addon_checkout",
    "tier": "starter",
    "interval": "month",
    "api_addon": true,
    "trial": true,
    "trial_period_days": 7,
    "card_required": true,
    "charged_today": false
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.