> ## 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.

# Quickstart

> Ask a business for its hours and get the answer as JSON.

## 1. Get your API key

Open the [dashboard](https://dashboard.thred.ai), select your workspace and environment, then go to **Settings → API keys → Create API key**. Copy the key when it appears and keep it on your server.

```bash theme={null}
export THRED_API_KEY="YOUR_API_KEY"
```

Your key selects Development or Production. Both use `https://api.thred.dev`.

Choose cURL, JavaScript, or Python below. JavaScript runs on your server with Node.js: save a snippet as `example.mjs` and run `node example.mjs`. For Python, install Requests with `python -m pip install requests`. All snippets read the API key set above.

> [!NOTE]
>
> Before calling, check **Settings → Calling** and **Settings → Phone numbers** to confirm calling is enabled and an enabled default caller number is configured. Development calls also dial real phone numbers.

## 2. Start a collection

Replace `to` with the phone number you want to call, including its country code. Put known context values in `input` and define the answers you want as a JSON Schema in `output`. Here, `input.date` tells Thred which day to ask about. `input` is optional and defaults to an empty object. The output is always an object, so no top-level `type` is needed.

```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 business is open on the date in input and what time it closes.",
    "input": { "date": "today" },
    "output": {
      "properties": {
        "is_open": { "type": "boolean" },
        "closes_at": { "type": "string" }
      },
      "required": ["is_open", "closes_at"],
      "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 business is open on the date in input and what time it closes.",
    input: { date: "today" },
    output: {
      properties: {
        is_open: { type: "boolean" },
        closes_at: { type: "string" }
      },
      required: ["is_open", "closes_at"],
      "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 business is open on the date in input and what time it closes.",
        "input": { "date": "today" },
        "output": {
            "properties": {
                "is_open": { "type": "boolean" },
                "closes_at": { "type": "string" }
            },
            "required": ["is_open", "closes_at"],
            "additionalProperties": False
        }
    },
    timeout=30,
)
response.raise_for_status()
collection = response.json()
print(collection["id"])
```

Thred accepts the request and returns `202 Accepted` with the collection's ID. IDs use the `call_` prefix:

```json theme={null}
{
  "id": "call_12345678-1234-1234-1234-123456789abc",
  "status": "queued",
  "reused": false,
  "environment": "development"
}
```

## 3. Get the answer

Replace the example ID with the ID returned by your collection:

```bash cURL theme={null}
curl --fail-with-body \
  https://api.thred.dev/v1/collect/call_12345678-1234-1234-1234-123456789abc \
  --header "Authorization: Bearer $THRED_API_KEY"
```

```javascript JavaScript theme={null}
const collectionId = "call_12345678-1234-1234-1234-123456789abc";
const response = await fetch(`https://api.thred.dev/v1/collect/${collectionId}`, {
  headers: { Authorization: `Bearer ${process.env.THRED_API_KEY}` },
});

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

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

collection_id = "call_12345678-1234-1234-1234-123456789abc"
response = requests.get(
    f"https://api.thred.dev/v1/collect/{collection_id}",
    headers={"Authorization": f"Bearer {os.environ['THRED_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
collection = response.json()
print(collection["status"], collection["data"])
```

Check every few seconds until `status` is `completed`, `incomplete`, `failed`, or `canceled`. While the status is `processing` or `awaiting_review`, the result is still being prepared.

A completed response includes your answers in `data`:

```json Result excerpt theme={null}
{
  "status": "completed",
  "data": {
    "is_open": true,
    "closes_at": "5 PM"
  },
  "partial_data": null,
  "missing_fields": []
}
```

If the collection is `incomplete`, use the answers in `partial_data` and check `missing_fields`. A failed or canceled collection may have no result.

That's the basic flow. Change `instructions`, `input`, and `output` to [build your own use case](https://www.thred.dev/guides/what-you-can-build.md), or see [Create a collection](https://www.thred.dev/api-reference/create-collection.md) for all available fields.


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