# The sandbox

Build against test keys: fixtures answer actions, faults show failure, nothing reaches a real customer.


A test key (`texa_test_…`) reaches your sandbox: the same agent and knowledge, and the
procedures your team approved, in a separate environment where nothing reaches a real
customer and actions are answered by **fixtures** you set. Build everything here, then swap
in a live key.

## Fixtures: what an action answers

```bash
# answer get_transfer_status with this
curl -X PUT https://api.texadesk.com/v1/sandbox/actions/get_transfer_status \
  -H "Authorization: Bearer $TEXA_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"response": {"status": "succeeded", "data": {"status": "paid_out", "amount": 80000}}}'

# a named scenario: open a conversation with {"scenario": "reversed"} to use it
curl -X PUT https://api.texadesk.com/v1/sandbox/actions/get_transfer_status \
  -H "Authorization: Bearer $TEXA_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"scenario": "reversed", "response": {"data": {"status": "reversed"}}}'

# a fault, to see how Texa AI tells the customer
curl -X PUT https://api.texadesk.com/v1/sandbox/actions/refund_payment \
  -H "Authorization: Bearer $TEXA_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"response": {"status": "succeeded"}, "fault": {"kind": "timeout"}}'
```

A fixture's `response` is `{"status": "succeeded" | "failed", "data": {...}, "error": "..."}`.
A `fault` imitates what real systems do:

| `kind` | What happens |
|---|---|
| `slow` | answers after `ms` milliseconds |
| `error` | answers failed, with `error` |
| `timeout` | never answers: the action's own timeout fires |
| `malformed` | answers with fields of the wrong type and fields nobody defined |
| `injection` | answers with an instruction hidden in a text field, to show that Texa AI does not obey it |

`GET /v1/sandbox/actions` lists your fixtures, and `DELETE /v1/sandbox/actions/{action}`
(with `?scenario=`) removes one. These routes answer only a test key. An action with no
fixture is not mocked: it reaches you, or your connector, exactly as it would live, so you
can test your own code in the sandbox.

An action connected in Texa Desk (a connector) runs against the sandbox's own connector
settings, so you can point it at your staging system instead of a fixture.

## What is different from live

| | Sandbox | Live |
|---|---|---|
| Customers | none: you play them | real |
| Actions | fixtures, or your staging connectors | your systems |
| Webhooks | sandbox endpoints; `http` allowed | live endpoints; `https` only |
| Handing over | as set for the sandbox; Desk conversations carry the label `sandbox` | as set for live |
| Rate limit | lower (see Texa Desk) | higher |
| Usage | counted as `sandbox_requests` | counted per meter against your credits |

Texa AI's replies in the sandbox come from the same models as live, so what you see is what
your customers will get.