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"])
{
"id": "call_123e4567-e89b-42d3-a456-426614174000",
"status": "queued",
"reused": false,
"environment": "development"
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Create a collection
Collect answers from a known phone number. Send instructions, optional context values in input, and a JSON Schema in output. Use the returned ID to retrieve the result, or provide a webhook_id. Development and Production can both place real calls.
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"])
{
"id": "call_123e4567-e89b-42d3-a456-426614174000",
"status": "queued",
"reused": false,
"environment": "development"
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}input holds context values for the call. output is the JSON Schema defining the answers you want back in data. input is optional and defaults to an empty object. The output is always an object: define properties, list required fields, and set additionalProperties to false. 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"])
Authorizations
Send Authorization: Bearer <THRED_API_KEY>. Development keys begin thr_dev_; Production keys begin thr_prod_. Each key is scoped to a workspace and environment. Keep secrets on your server.
Headers
Optional key for retrying a request without creating another collection. Omit it to create a new collection on each POST. Reuse the same key only with the same request; a different request returns 409. Use 1–200 printable, non-space ASCII characters.
1 - 200^[!-~]{1,200}$Body
The destination, task, input context, and output JSON Schema.
Send UTF-8 JSON, up to 64 KiB. Unknown fields are rejected.
Destination phone number in E.164 format.
^\+[1-9]\d{6,14}$"+14155550123"
What you want to find out. Thred manages conversation, navigation, and assistance. Must contain non-whitespace text.
1 - 8000The JSON Schema defining the answers returned in data. The output root is always an object, so no top-level type is needed. Define properties and required fields, and set additionalProperties to false.
Show child attributes
Show child attributes
{
"properties": {
"is_open": { "type": "boolean" },
"closes_at": { "type": "string" }
},
"required": ["is_open", "closes_at"],
"additionalProperties": false
}
Known context values for the call, such as a date, product name, or reference number. Must be a JSON object; optional and defaults to an empty object. Up to 16,000 bytes of JSON. Maximum depth: 32; maximum values: 8,192.
{ "date": "today" }
Maximum job duration. Your workspace and environment may have a lower limit.
30 <= x <= 1800Enabled caller number ID belonging to the same workspace and environment. Omit to use the environment default.
1 - 160Enabled webhook endpoint ID from your dashboard, in the same workspace and environment. Omit to poll for results.
1 - 160Optional routing hints. IVR navigation is automatic. Custom routes, actions, and navigation policy overrides are not accepted.
Show child attributes
Show child attributes
An intro followed by optional detail messages for screeners. If omitted, Thred prepares a sequence from the task and input before dialing.
1 - 8 elementsShow child attributes
Show child attributes
Your tracking fields, up to 4,000 bytes of JSON. Maximum depth: 32; maximum values: 8,192.
Recording is currently disabled. Leave false or omit; true returns 503.
Response
New collection accepted, or an existing idempotent request returned.
The collection ID, using the call_ prefix. Use it to retrieve or cancel the collection.
"call_123e4567-e89b-42d3-a456-426614174000"
Final: completed, incomplete, failed, canceled. Continue polling for all other statuses.
queued, dialing, in_progress, processing, awaiting_review, completed, incomplete, failed, canceled True when the same idempotency key and normalized request already existed. No new collection is created.
false
The API key selects the workspace environment. Development and Production are isolated, but either can place real calls when enabled.
development, production