StateSet API Docs

Start at the first result you cannot verify. A workspace can exist while its connector is unhealthy; an agent can answer while a workflow has never received an event. Diagnose those boundaries separately. This guide covers the platform onboarding path, Response MCP, and the Workstream trial. For native-library installation or local commerce data, use SDK installation and Your First Operation.

Find your stopping point

Cannot open the workspace

Signed in, but cannot reach the intended organization? Check selection and membership.

MCP will not connect

Check the endpoint, accepted credential type, and resolved secret.

A tool is missing or denied

Check discovery, scopes, and the actual tenant exposed by your connection.

The agent answers incorrectly

Inspect saved settings, processed knowledge, and the failed test.

The trial has no draft

Follow the accepted job through its steps and workflow execution.

The customer got no reply

Separate dry runs, routing, review decisions, and dispatch evidence.

Workspace access

Open Response Setup and confirm the selected organization. If signup did not complete, finish the sign-in, organization, or plan step the app displays. If your organization already exists, resolve membership rather than creating another workspace. For portal provisioning, inspect the existing launch/verification results. Use Open your Response workspace after launch. A partially provisioned service needs its reported issue resolved; another signup is not evidence that the original workspace has been repaired. If the workflow UI reports that the organization is not mapped to the engine, ask the workspace administrator to check the organization-to-brand mapping. The Response organization ID, Workstream brand UUID, and brand slug are not interchangeable.

Recovered when: the intended workspace opens and a read shows the expected organization or brand, without creating duplicate records.

MCP connection

Check the exact remote endpoint:

Response: https://response.stateset.com/api/mcp
Workstream: https://api.workstream.stateset.com/v1/mcp

Use the supported authentication path for that server. A browser session does not automatically supply credentials to an external MCP host, and one service’s API key need not work on another. If configuration contains an environment-variable placeholder, verify your host resolves it.

Observation	Interpretation and next step
`401`	Check key type, revocation/rotation, secret substitution, and deployment support. If an accepted workspace-key setup still fails, the operator may need to check issuer configuration
Response `503` with JSON-RPC `auth_unavailable`	Workspace-key verification is unavailable; have the service operator inspect that dependency. This does not establish that the customer’s key is invalid
HTTP `404`	Check the full endpoint path and deployed service; do not substitute a REST route for MCP
Host cannot launch a process	Check stdio command, installed runtime, and absolute paths; a remote URL is not an executable
Connects but reads the wrong data	Stop writes and correct the tenant or local database connection

The Response workspace-key unavailable path can return Retry-After. Respect it for a later connection/read attempt. Do not apply this advice as a blanket retry rule for business writes. See service error contracts.

Recovered when: discovery succeeds and a read identifies the intended data source. Avoid rotating every credential or disabling authentication to diagnose one failing connection.

Missing tools

Refresh tools/list in the host and inspect the actual input schema. A missing tool can reflect credential scopes, a selected profile, a deployment version, or a transport limitation. Response’s test_agent and evaluation runs require generation/write permission, even though your purpose is testing. Reading an agent successfully does not establish that permission. Some Workstream tools delegate to REST handlers and require HTTP transport rather than local mcp-stdio. Do not invent a tool name or bypass a denial with another tenant ID. Ask the administrator for the permission needed for the specific task, then verify discovery and access again.

Recovered when: the required tool is exposed and authorized for the intended record. See the connection walkthrough.

Agent behavior

Find the existing agent before creating a replacement. Inspect its saved instructions, settings, rules, and sources using the app or the supported Response reads.

A newly imported source must finish processing before you treat it as searchable knowledge.
An imported policy is not live order data. Order questions need the configured lookup.
A test question must exercise the intended agent, not an assumed default agent.
A correction stored as an evaluation does not itself change the agent’s behavior.

Rerun the narrow failing case after an authorized correction. Preserve the response/evaluation ID and the expected answer. run_eval returning passed: null means grading could not run; resolve that before calling the test passed. A capped suite with has_more is incomplete.

Recovered when: the saved change is visible and the relevant test has an observed, reviewed result. Use the first-week evaluation loop.

Workflow trial

Keep the existing brand UUID and accelerator job ID. Use get_onboarding_accelerator_status for the latest job on that brand and get_onboarding_funnel for the next incomplete milestone. Compare the returned job ID with the attempt you are investigating; a latest-status read is not a request for an arbitrary historical job. Inspect every step, including skipped reasons. A job response or a completed report does not mean all dependent operations succeeded.

Step or symptom	What to inspect	Who can resolve it
Discovery/harvest lacks credentials	Whether Gorgias is connected through the supported credential flow	Workspace connector administrator
Provider discovery fails	Provider authorization and refresh errors	Connector administrator
Draft step skips an active brand	Expected behavior; the accelerator does not overwrite the active config	Workflow editor, through explicit draft/evaluate/apply
Webhook registration is skipped	The reported missing provider input, such as Shopify webhook secret	Connector administrator; provide secrets through the connection flow
Activation fails	Readiness details: connector health, config, or billing requirements	Owner of the reported blocker
Backfill skips an inactive brand	The activation failure above it	Workflow administrator
Job remains running or reports stale state	Job timestamp, worker/API availability, and execution evidence	Service operator; inspect before launching another job
Backfill queued but report empty	`list_brand_workflows`, then `get_workflow_run` for relevant runs	Workflow/service operator

Recovered when: a trial report and run evidence show what happened to a replayed ticket. Do not lower evaluation thresholds or switch routing live just to make an onboarding indicator turn green.

Missing replies

Follow the evidence in order:

Event: did a real provider event reach the brand? A replay does not prove webhook delivery.
Run: did it execute, skip, fail, or escalate? Read the actual reason.
Mode: was this a backfill/dry run or shadow operation? Those drafts are not customer sends.
Review: is the reply waiting for a human decision? Inspect the configured review process.
Dispatch: did the provider accept the send, and what evidence identifies the resulting message?

Backfill replay uses dry_run: true and bypasses the human-review waiting step. No approval item for that replay is expected. For real traffic, brand activation and live routing are separate; an active shadow brand still does not establish customer dispatch. Do not send the reply manually until you have reconciled whether the original dispatch succeeded. If it is still uncertain, keep the case visible to its owner rather than creating a second send attempt without evidence.

Recovered when: the run and channel evidence agree on whether a reply was sent, skipped, escalated, or is still pending.

Ask your assistant for a diagnosis

Replace the bracketed fields and omit IDs you do not have. This is a read-only investigation; credentials stay in the configured connection.

Diagnose my StateSet onboarding problem without changing anything.
Workspace/organization: [identifier]
Response agent: [UUID, if relevant]
Workstream brand: [UUID, if relevant]
Accelerator job or workflow run: [ID, if known]
Last successful step: [what I verified]
Expected next result: [what is missing]
Time window and timezone: [window]

Inspect the exposed tool schemas first. Read the relevant workspace, agent,
onboarding status, funnel, or workflow evidence. Report the last confirmed
success, the earliest blocker, and which operator can resolve it.
Distinguish unknown from failed. Do not create an agent/brand, rerun onboarding,
rotate credentials, change config/routing, or send a customer message.
Return the relevant record/request IDs and a proposed next step for review.

Hand off a useful support report

Use Report an API problem, adding the setup step, MCP host and server, tool name, non-secret organization/brand/job IDs, and the last successful read. Include whether any previous write may already have completed. Remove keys, authorization headers, and customer message content before sharing. Report the error code/body as well as HTTP status when available; an MCP tool failure may be represented inside a protocol response. A timestamped host report is context, not a live diagnosis of your request.

Next steps

Return to the agent walkthrough, workflow trial, or MCP management guide at the recovered step.

​Find your stopping point

Cannot open the workspace

MCP will not connect

A tool is missing or denied

The agent answers incorrectly

The trial has no draft

The customer got no reply

​Workspace access

​MCP connection

​Missing tools

​Agent behavior

​Workflow trial

​Missing replies

​Ask your assistant for a diagnosis

​Hand off a useful support report

​Next steps