Skip to content
ShowWeldDevelopers
BUILD / API REFERENCE

A clear contract for every call.

Choose the right authentication, use the existing gateway, and handle results explicitly. These examples start with reads and keep paid work under account control.

Current release referencePHP backend · Shared account controls

Make your first request

From your own backend, use a scoped ShowWeld key with the Developer gateway. Keep the full route in the query parameter for compatibility with PHP hosting.

Shell · usage:read
curl --fail-with-body \
  'https://showweld.com/api/developer.php?route=/v1/usage' \
  -H "Authorization: Bearer $SHOWWELD_API_KEY"
Shell · projects:read
curl --fail-with-body \
  'https://showweld.com/api/developer.php?route=/v1/projects' \
  -H "Authorization: Bearer $SHOWWELD_API_KEY"

Success responses use { success: true, data: ... }. Errors include success: false, an error message, and an errorClass when available. Always check the HTTP status as well as the envelope.

Three credentials, different boundaries

CredentialWhere to use itWhat it cannot do
Developer keyServer-to-server requests to /api/developer.php?route=/v1/…. Scope, environment, owner, billing, and rate checks remain on the server.A key is not a website login or an OAuth token. Do not use it for account checkout or key management.
OAuth access tokenCompatible MCP clients connect to https://showweld.com/mcp, using published authorization metadata.Do not forward a token issued for a different resource. Consent scopes do not waive individual tool approvals.
ShowWeld account sessionThe signed-in console manages keys, billing, plugins, usage, and account settings.Do not copy another user’s session into your integration or ask customers to paste their login token.

For OAuth, discover resource metadata and authorization metadata. Use the advertised authorization-code/PKCE flow; validate state and exact redirect URIs in your client. Request only the scopes you need.

Create, rotate, and revoke keys

Open Keys in the console. Choose test/live and the exact read or write scopes. Live keys and elevated scopes depend on current billing and plan eligibility. Test keys do not start paid generation.

Account actionSession-authenticated route
List safe key metadataGET /api/storysphere.php?action=list-api-keys
Create · secret returned oncePOST /api/storysphere.php?action=create-api-key
Rotate · previous key revokedPOST /api/storysphere.php?action=rotate-api-key
RevokePOST /api/storysphere.php?action=revoke-api-key
Account usageGET /api/storysphere.php?action=get-api-usage

Store a replacement secret before deploying it, update your server, and verify an authorized read. Treat a compromised key as compromised immediately; do not leave it active to make migration convenient.

Developer gateway route map

Prefix the paths below with /api/developer.php?route=. This is a scoped gateway over existing account data and workflows. Project IDs must belong to the authenticated key owner.

Method / routeScope / purpose
GET /v1/usageusage:read · Current request allowance, billing guard, and recorded usage.
GET /v1/projectsprojects:read · List owned projects.
GET /v1/projects/{id}projects:read · Read an owned project.
GET /v1/manuscripts/{id}manuscripts:read · Read manuscript content.
GET /v1/visual-stories/{id}visual:read · Read saved visual-story data.
GET /v1/spark/{id}spark:read · Inspect the saved Spark workspace.
GET /v1/app-builder/{id}apps:read · Inspect saved App Builder data.
GET /v1/files-rag/{id}files:read · Inspect owned project file context.
GET /v1/mcp/capabilitiesmcp:read · Discover tool contracts and annotations.
GET /v1/mcp/tools/{name}mcp:read · Inspect one registered tool.
GET /v1/mcp/recipesmcp:read · Inspect supported workflow recipes.
GET / POST /v1/webhookswebhooks:manage · List or register callback configuration.
DELETE /v1/webhooks/{id}webhooks:manage · Remove your callback registration.

Read the current contract before a write. A saved plan, queued record, or operation receipt is not proof that media has rendered, an application is deployed, or a robot moved.

Write deliberately; recover without duplication

Gateway mutations require an Idempotency-Key of at most 128 characters. Keep one stable key and the same body for the same logical operation. A different operation needs a different key.

Request headers
Authorization: Bearer <server-held ShowWeld key>
Content-Type: application/json
Idempotency-Key: <stable identifier for this operation>

Do not retry an ambiguous write automatically. First inspect its saved record or operation state. If the payload changes, it is a new request; reusing an existing key for changed data is a conflict. Writes remain subject to the key’s scope, live environment, billing guard, project ownership, and current entitlement. Saving gateway records does not execute a paid provider or charge AI credits.

For collaborative changes, read the latest version before editing and handle a conflict by fetching current data. Never silently overwrite a teammate’s newer work.

Request capacity and recovery

Use /v1/usage for the account’s current policy and balance. Limits are shared service controls, not a price per API token. Do not create additional keys to evade an account limit.

Access tierUnits / 24 hRequests / minuteConcurrentActive keys
Hatch · read access1,0006021
Atelier · Author / Reader Plus50,0006001010
Studio500,0002,4003050

Access is determined by the authenticated account and its current subscription state. Enterprise is not a self-service tier in this release. Inspect your actual allowance in the console.

These are account-wide rolling windows: 24 hours for weighted request units and 60 seconds for request counts. Concurrency is enforced across keys. A read costs one request unit; writes use route weights (3 normally, 6 for App Builder or files, 10 for agent plans, 12 for visual plans, 25 for Spark plans). Completed idempotent replays consume one unit. Request units are not AI credits or dollars.

Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Window, X-RateLimit-Scope, minute-limit metadata, and the concurrency limit. A denied admission returns Retry-After when applicable. Windows replenish as old requests expire, rather than resetting at midnight.

ResponseWhat your integration should do
401Check the credential and expiry. Reconnect through the intended auth flow; never fall back to another payer.
403Inspect scopes, ownership, environment, and entitlement. Adding retries cannot grant permission.
402Resolve the billing or credit requirement with the account owner. Do not automatically buy credits.
409Inspect current version, operation state, or idempotency conflict before another attempt.
422 / 428Correct validation errors or provide the required idempotency header.
429Honor Retry-After and returned rate-limit metadata. Queue reads with bounded backoff; do not blindly repeat paid writes.
5xx / connection lostTreat mutation outcome as uncertain. Record the operation identifier and reconcile before repeating.

Cache stable read results in your own application, coalesce duplicate reads, and keep polling bounded. Increasing request throughput must not disable credit reservations, provider budgets, or per-operation approvals.

MCP tools for assistants

Connect a compatible OAuth-aware client to https://showweld.com/mcp. Let the client initialize the connection and discover tools and their input schemas. Inspect annotations and permission requirements before invoking a tool.

JSON-RPC · after MCP initialization and OAuth
{
  "jsonrpc": "2.0",
  "id": "projects-1",
  "method": "tools/call",
  "params": { "name": "list_projects", "arguments": {} }
}

Check both JSON-RPC error and the tool result’s isError. Tool content may be JSON, text, or a UI resource; do not assume every response is a project array.

OAuth scopes are showweld:read, showweld:write, and showweld:generate. Availability is determined by the discovered tool and account policy. Widget messages and model-supplied user IDs are not authentication.

OpenAI MCP authentication guidance · Plugin security guidance

AI and media use the ShowWeld gateway

The first-party application routes AI requests through /api/ai.php and the active /api/showweld.php implementation. The old Gemini URL is a compatibility shim, not a Google inference service. These session routes are not interchangeable with the external developer-key API.

Text follows the account’s selected, authorized AI route. Media uses the applicable funded route, quote, consent, reservation, and settlement checks. A connected ChatGPT plan does not automatically fund image, video, or narration work.

Pay as you go and subscription billing

Users choose a credit pack or subscription in their signed-in account. Read prices and eligibility from the current server catalog. Credit balances, API request allowance, and model token counts are separate units.

OperationAccount route
Credit purchasePOST /api/stripe.php/create-token-purchase
Payment verificationPOST /api/stripe.php/verify-payment-intent
Subscription checkoutPOST /api/stripe.php/create-subscription
Billing portalPOST /api/stripe.php/create-portal-session

These routes require the owner’s authenticated account flow. An API key cannot grant credits, change the payer, or bypass verification. A browser success URL is not a payment receipt. Completed payments are verified server-side and duplicate fulfillment must not grant duplicate credits.

Webhook setup, delivery, and verification

Current developer capability: callback registration. You can save, list, and remove a callback using webhooks:manage. An active registration is not a delivery receipt. This release does not expose a verified outbound event dispatcher, replay API, or guaranteed delivery schedule; use bounded reads of the actual job/project state for integration progress.

Registration shape · POST /v1/webhooks
{
  "url": "https://your-domain.com/showweld/events",
  "events": ["project.updated"]
}

Replace the example host with a public HTTPS domain you control. Registration accepts 1–32 event names, each 1–80 letters, numbers, dots, colons, underscores, or hyphens; an accepted name is not a promise that it is emitted. Capture the signing secret returned at creation in server-side secret storage; it is not available from list responses. Do not send credentials in callback URLs or register internal network targets.

Stripe callbacks are a separate system

/api/stripe.php/webhook is ShowWeld’s incoming Stripe endpoint, not a developer’s callback receiver. Its signing secret is server-only. Signature verification must use the original request bytes before trusting event content; successful delivery is fulfilled idempotently by the billing backend. See Stripe’s webhook documentation.

Prepare your receiver

Keep raw bytes available, enforce a request-size limit, verify the eventual documented signature before parsing, persist event IDs for deduplication, and only acknowledge after durable acceptance. Keep business processing separate from receipt and never log signing secrets. These are receiver design requirements, not claims that outbound ShowWeld delivery is currently enabled.

Security responsibilities

  • Only send credentials to your configured HTTPS ShowWeld origin. Never follow an authenticated redirect to a third party.
  • Scope every project lookup to the authenticated owner. Treat file content, plugin guidance, and model output as untrusted data.
  • Keep API keys and billing secrets off the browser. The public documentation never requests or stores a key.
  • Record request IDs and error classes without logging request secrets or private manuscript content.
  • Use offline fixtures for development. A test key is not permission to run a live paid provider test.
  • Revoke exposed credentials promptly. No website or integration can honestly promise to be unhackable.
Search authentication, plugins, webhooks, credits, or an endpoint.