Quickstart

1. Get your API key

Open the dashboard, 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.

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.

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.

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
    }
  }'

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);

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:

{
  "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:

curl --fail-with-body \
  https://api.thred.dev/v1/collect/call_12345678-1234-1234-1234-123456789abc \
  --header "Authorization: Bearer $THRED_API_KEY"

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);

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:

Result excerpt

{
  "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, or see Create a collection for all available fields.

Get started

Collect API

Account and utilities

1. Get your API key

2. Start a collection

3. Get the answer

​1. Get your API key

​2. Start a collection

​3. Get the answer

1. Get your API key

2. Start a collection

3. Get the answer