Interactive documentation for the public API.
The X-GenStudio-Signature header may carry MORE THAN ONE v1 value. During the 24-hour secret rotation grace window it carries two — one signed with the new secret, one with the previous. Try each in turn and accept the request if ANY of them matches. Implementations that read a single v1 will reject every delivery during a rotation.
Reject requests whose t differs from your current time by more than 5 minutes. The signed payload is "{t}.{rawBody}" — the timestamp is inside the signature, so it cannot be changed without invalidating it.
X-GenStudio-Signature: t=1785000000,v1=<hex>,v1=<hex>
X-GenStudio-Event: generation.succeeded
X-GenStudio-Delivery: <delivery id>
X-GenStudio-Event-Version: 1POST /api/v1/me/webhook-endpoints/{id}/rotate-secret returns the new secret once. The previous secret keeps working for a grace window so you can deploy without dropping deliveries; the response tells you exactly how long.
Rotating twice within the grace window invalidates the OLDEST secret immediately. The endpoint keeps exactly one previous secret, so a second rotation overwrites it. Finish deploying one rotation before starting the next.
Webhook URLs must use https on port 443. If you self-host on another port, terminate TLS behind a reverse proxy on 443, or use a tunnel such as ngrok or Cloudflare Tunnel — both terminate on 443, so local development works unchanged.
Rotating a secret and re-triggering verification are available in the web app only. Both require re-entering your password, and an API key has no password context. This is a deliberate MVP scope decision, not a missing endpoint.
A single event is delivered at most 9 times, spread over at least 31 hours. Size your de-duplication window accordingly: the same X-GenStudio-Delivery id may arrive more than once during that period.
De-duplicate on X-GenStudio-Delivery, not on the payload. The delivery id is stable across every retry of the same event; the signature is not (each attempt is signed with a fresh timestamp).
Return any 2xx to acknowledge. Anything else — including a slow response body — counts as a failed attempt and is retried. After the last attempt the delivery is marked dead and you can replay it from the delivery log.
anon_trial_unavailable — 503 — Anonymous trial sign-in is temporarily unavailable. Try again later, or sign up for a full account.asset_lost — 410 — This file is no longer available. Your credits were refunded.download_timeout — 504 — We could not retrieve the result in time. Your credits were refunded.endpoint_not_verified — 409 — This webhook endpoint has not been verified yet.forbidden — 403 — Your account is authenticated but not allowed to perform this action.idempotency_key_reuse — 422 — This idempotency key was already used with a different request.insufficient_credits — 402 — You need {required} credits but only have {available}.insufficient_credits_on_fallback — 402 — The alternate model needs {required} credits but only {available} are available. Your credits were refunded.internal_error — 500 — An unexpected internal error occurred.invalid_credentials — 401 — Sign-in failed. Check the address and password — and make sure the address is verified.invalid_params — 422 — Some settings are not valid.invalid_state — 422 — This action is not allowed in the current state.invite_invalid — 422 — That invite code cannot be used. Ask whoever invited you for a new one.job_stalled — 500 — This job never started. Your credits were refunded.job_stuck — 500 — This job stopped making progress. Your credits were refunded.maintenance — 503 — New generations are paused for scheduled maintenance. Jobs already running will finish, and your history stays available. Please try again shortly.not_found — 404 — The requested resource does not exist or is not visible to you.provider_auth_failed — 500 — The service is misconfigured and cannot reach the provider. Your credits were refunded. Please contact support@yaspost.com.rate_limited — 429 — Too many attempts. Try again a little later.reauth_required — 401 — Please re-enter your password to continue.submit_unknown — 500 — We could not confirm whether this job was submitted. Your credits were refunded.subscription_required — 403 — This capability is available to subscribers only. Upgrade to use it.unauthorized — 401 — Your session is no longer valid. Sign in again.upload_too_large — 413 — The file is larger than the {maxBytes} byte limit.upstream_error — 502 — The provider returned an error. Your credits were refunded.upstream_rate_limited — 502 — The provider is busy. Please try again shortly. Your credits were refunded.upstream_rejected — 502 — The provider rejected this generation. Your credits were refunded.upstream_timeout — 504 — The provider took too long. Your credits were refunded.upstream_unavailable — 502 — The provider is temporarily unavailable. Please try again later. Your credits were refunded.verification_failed — 422 — That code did not match. Request a new one.