> ## Documentation Index
> Fetch the complete documentation index at: https://www.thred.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# What you can build

> Turn questions that require a phone call into structured answers.

Use Collect when you already have a source's phone number. Use `instructions` for what to ask, `input` for known context values, and `output` for the JSON Schema of the answers you need. Your application gets structured JSON after Thred collects the answers.

## Information you can collect

| Use case | What to ask |
| - | - |
| Business hours | Confirm opening hours, holiday hours, or the latest pickup time. |
| Product availability | Ask whether a specific item is in stock and what it costs. |
| Appointment information | Ask about availability, accepted appointment types, or what a customer needs to bring. |
| Department questions | Reach the right department or extension and ask about its services. |

## Example: check inventory

Set your API key using the [quickstart](https://www.thred.dev/quickstart.md), then [create a collection](https://www.thred.dev/api-reference/create-collection.md). Replace `to` with the number you want to call. The `input` object supplies the product and currency for these instructions:

```bash cURL theme={null}
curl --fail-with-body https://api.thred.dev/v1/collect \
  --request POST \
  --header "Authorization: Bearer $THRED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+14155550123",
    "instructions": "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
    "input": { "product": "6-foot USB-C charging cable", "currency": "USD" },
    "output": {
      "properties": {
        "in_stock": {
          "type": "boolean",
          "description": "Whether a 6-foot USB-C charging cable is currently in stock."
        },
        "price_usd": {
          "type": ["number", "null"],
          "description": "The quoted price in USD, or null if the cable is unavailable."
        }
      },
      "required": ["in_stock", "price_usd"],
      "additionalProperties": false
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.thred.dev/v1/collect", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THRED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155550123",
    instructions: "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
    input: { product: "6-foot USB-C charging cable", currency: "USD" },
    output: {
      properties: {
        in_stock: {
          type: "boolean",
          description: "Whether a 6-foot USB-C charging cable is currently in stock.",
        },
        price_usd: {
          type: ["number", "null"],
          description: "The quoted price in USD, or null if the cable is unavailable.",
        },
      },
      required: ["in_stock", "price_usd"],
      additionalProperties: false,
    },
  }),
});

if (!response.ok) throw new Error(await response.text());
const collection = await response.json();
console.log(collection.id);
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://api.thred.dev/v1/collect",
    headers={
        "Authorization": f"Bearer {os.environ['THRED_API_KEY']}",
    },
    json={
        "to": "+14155550123",
        "instructions": "Ask whether the product in input is in stock. If it is, ask for its price in the requested currency.",
        "input": { "product": "6-foot USB-C charging cable", "currency": "USD" },
        "output": {
            "properties": {
                "in_stock": {
                    "type": "boolean",
                    "description": "Whether a 6-foot USB-C charging cable is currently in stock.",
                },
                "price_usd": {
                    "type": ["number", "null"],
                    "description": "The quoted price in USD, or null if the cable is unavailable.",
                },
            },
            "required": ["in_stock", "price_usd"],
            "additionalProperties": False,
        },
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["id"])
```

Thred returns the collection's ID immediately. [Retrieve the collection](https://www.thred.dev/api-reference/get-collection.md) to check its status. Once `status` is `completed`, `data` contains the answers in your requested shape. If the result is `incomplete`, check `partial_data` for the answers it collected.

## Shape the answers

Output fields can be strings, numbers, integers, booleans, objects, or arrays. Fields can also allow `null`, as the price does above. Give fields clear descriptions and list the answers you need under `required`.

The output is always an object, so omit its top-level `type`. Define `properties`, list `required` fields, and set `additionalProperties` to `false`. Nested objects still need `type: "object"`, `properties`, and `additionalProperties: false`; arrays need an `items` schema. Thred supports a small JSON Schema subset. The [API reference](https://www.thred.dev/api-reference/create-collection.md) lists the supported fields.

## Add context and routing

| Option | Use it to |
| - | - |
| `input` | Pass a JSON object of context values, such as a product name or reference number. Optional; defaults to `{}`. |
| `navigation` | Specify a contact name, department, extension, or language. |
| `max_duration_seconds` | Set how long the call can run within your workspace's limit. |
| `metadata` | Attach your own identifiers so you can match the result to a record in your app. |
| `webhook_id` | Receive a signed completion event at an endpoint configured in the dashboard. |

Start with the [quickstart](https://www.thred.dev/quickstart.md), then add these options as your workflow needs them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.