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

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

Use the [quickstart](https://www.thred.dev/quickstart.md) to set your API key. JavaScript uses Node.js; Python uses Requests.

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

```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"])
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/collect
openapi: 3.0.3
info:
  title: Thred API
  version: 1.0.0
  description: >-
    Thred is the data API for the phone. Use Collect when you know who to ask:
    send a phone number and instructions, add context values in input, and
    define the answers you want with a JSON Schema in output. Use the same base
    URL for Development and Production; your API key selects the environment.
servers:
  - url: https://api.thred.dev
    description: Thred API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify the workspace and environment selected by your API key.
  - name: Collect
    description: Collect structured answers from a known phone number.
  - name: Usage
    description: Read daily operational usage.
  - name: Health
    description: Check public API availability.
paths:
  /v1/collect:
    post:
      tags:
        - Collect
      summary: Create a collection
      description: >-
        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.
      operationId: createCollection
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            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.
          schema:
            type: string
            minLength: 1
            maxLength: 200
            pattern: ^[!-~]{1,200}$
          example: business-hours-001
      requestBody:
        required: true
        description: The destination, task, input context, and output JSON Schema.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCallRequest'
            example:
              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
      responses:
        '202':
          description: New collection accepted, or an existing idempotent request returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedCall'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/TooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    CreateCallRequest:
      type: object
      properties:
        to:
          type: string
          pattern: ^\+[1-9]\d{6,14}$
          example: '+14155550123'
          description: Destination phone number in E.164 format.
        instructions:
          type: string
          minLength: 1
          maxLength: 8000
          description: >-
            What you want to find out. Thred manages conversation, navigation,
            and assistance. Must contain non-whitespace text.
        input:
          type: object
          additionalProperties: true
          default: {}
          description: >-
            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.
          example:
            date: today
        output:
          $ref: '#/components/schemas/OutputSchema'
        max_duration_seconds:
          type: integer
          default: 300
          minimum: 30
          maximum: 1800
          description: >-
            Maximum job duration. Your workspace and environment may have a
            lower limit.
        caller_number_id:
          type: string
          minLength: 1
          maxLength: 160
          description: >-
            Enabled caller number ID belonging to the same workspace and
            environment. Omit to use the environment default.
        webhook_id:
          type: string
          minLength: 1
          maxLength: 160
          description: >-
            Enabled webhook endpoint ID from your dashboard, in the same
            workspace and environment. Omit to poll for results.
        navigation:
          $ref: '#/components/schemas/Navigation'
        screener_sequence:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/ScreenerMessage'
          description: >-
            An intro followed by optional detail messages for screeners. If
            omitted, Thred prepares a sequence from the task and input before
            dialing.
        metadata:
          type: object
          additionalProperties: true
          default: {}
          description: >-
            Your tracking fields, up to 4,000 bytes of JSON. Maximum depth: 32;
            maximum values: 8,192.
        record:
          type: boolean
          default: false
          description: >-
            Recording is currently disabled. Leave false or omit; true returns
            503.
      required:
        - to
        - instructions
        - output
      description: Send UTF-8 JSON, up to 64 KiB. Unknown fields are rejected.
      additionalProperties: false
    AcceptedCall:
      type: object
      properties:
        id:
          type: string
          example: call_123e4567-e89b-42d3-a456-426614174000
          description: >-
            The collection ID, using the call_ prefix. Use it to retrieve or
            cancel the collection.
        status:
          $ref: '#/components/schemas/CallStatus'
        reused:
          type: boolean
          description: >-
            True when the same idempotency key and normalized request already
            existed. No new collection is created.
          example: false
        environment:
          $ref: '#/components/schemas/Environment'
      required:
        - id
        - status
        - reused
        - environment
    OutputSchema:
      type: object
      properties:
        type:
          type: string
          enum:
            - object
          description: >-
            Optional. The output root is always an object; omit this field when
            creating a collection.
          default: object
        description:
          type: string
          maxLength: 2000
          description: Explain what the answer should contain.
        title:
          type: string
          maxLength: 2000
        properties:
          type: object
          description: >-
            Object fields. Names must contain 1–120 characters and cannot be
            __proto__, prototype, or constructor.
          additionalProperties:
            $ref: '#/components/schemas/OutputSchemaNode'
        required:
          type: array
          description: >-
            Unique names declared in properties. Required answers that cannot be
            obtained prevent a completed result.
          uniqueItems: true
          items:
            type: string
        additionalProperties:
          type: boolean
          enum:
            - false
          description: Required and always false for every object schema.
      required:
        - properties
        - additionalProperties
      description: >-
        The 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.
      additionalProperties: false
      example:
        properties:
          is_open:
            type: boolean
          closes_at:
            type: string
        required:
          - is_open
          - closes_at
        additionalProperties: false
    Navigation:
      type: object
      properties:
        contact_name:
          type: string
          minLength: 1
          maxLength: 160
          description: Person to ask for.
        department:
          type: string
          minLength: 1
          maxLength: 160
          description: Department to reach.
        extension:
          type: string
          minLength: 1
          maxLength: 16
          pattern: ^[0-9]+$
          description: >-
            Extension hint, used when an appropriate extension-entry prompt is
            heard.
        language:
          type: string
          minLength: 1
          maxLength: 160
          pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8}){0,3}$
          example: en
          description: Language tag, such as en or fr-CA.
      description: >-
        Optional routing hints. IVR navigation is automatic. Custom routes,
        actions, and navigation policy overrides are not accepted.
      additionalProperties: false
    ScreenerMessage:
      type: object
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 500
          description: Approved spoken copy; must contain non-whitespace text.
        type:
          type: string
          enum:
            - intro
            - detail
          description: The first message must be intro; all later messages must be detail.
      required:
        - message
        - type
      additionalProperties: false
    CallStatus:
      type: string
      enum:
        - queued
        - dialing
        - in_progress
        - processing
        - awaiting_review
        - completed
        - incomplete
        - failed
        - canceled
      description: >-
        Final: completed, incomplete, failed, canceled. Continue polling for all
        other statuses.
    Environment:
      type: string
      enum:
        - development
        - production
      description: >-
        The API key selects the workspace environment. Development and
        Production are isolated, but either can place real calls when enabled.
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      required:
        - error
    OutputSchemaNode:
      type: object
      properties:
        type:
          description: >-
            One supported type, or an array containing one supported non-null
            type and null. An object schema must include properties and
            additionalProperties: false; an array schema must include items.
          oneOf:
            - type: string
              enum:
                - object
                - array
                - string
                - number
                - integer
                - boolean
                - 'null'
            - type: array
              minItems: 1
              maxItems: 2
              uniqueItems: true
              items:
                type: string
                enum:
                  - object
                  - array
                  - string
                  - number
                  - integer
                  - boolean
                  - 'null'
        description:
          type: string
          maxLength: 2000
          description: Explain what the answer should contain.
        title:
          type: string
          maxLength: 2000
        properties:
          type: object
          description: >-
            Object fields. Names must contain 1–120 characters and cannot be
            __proto__, prototype, or constructor.
          additionalProperties:
            type: object
            additionalProperties: true
            description: >-
              A nested schema with the same supported fields. Every node needs
              type; objects need properties and additionalProperties: false;
              arrays need items.
        required:
          type: array
          description: >-
            Unique names declared in properties. Required answers that cannot be
            obtained prevent a completed result.
          uniqueItems: true
          items:
            type: string
        additionalProperties:
          type: boolean
          enum:
            - false
          description: Required and always false for every object schema.
        items:
          type: object
          additionalProperties: true
          description: The schema for each array item, using the same supported fields.
        enum:
          type: array
          minItems: 1
          maxItems: 100
          items:
            oneOf:
              - type: string
                nullable: true
              - type: number
              - type: boolean
          description: >-
            Primitive string, number, boolean, or null values. Each value must
            satisfy the declared type and bounds.
        minItems:
          type: integer
          minimum: 0
          maximum: 10000
        maxItems:
          type: integer
          minimum: 0
          maximum: 10000
        minLength:
          type: integer
          minimum: 0
          maximum: 10000
        maxLength:
          type: integer
          minimum: 0
          maximum: 10000
        minimum:
          type: number
        maximum:
          type: number
      required:
        - type
      description: >-
        Supported JSON Schema fields. Maximum 128 nodes and 8 nesting levels
        below the root. Keywords must match their type; minimum bounds cannot
        exceed maximum bounds.
      additionalProperties: false
    ErrorDetail:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error explanation.
      required:
        - code
        - message
  responses:
    BadRequest:
      description: >-
        Invalid request, schema, destination, duration, caller number, webhook,
        or date range. Inspect error.code and error.message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Missing, malformed, invalid, revoked, or environment-mismatched bearer
        API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: This idempotency key already belongs to a different normalized request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooLarge:
      description: The UTF-8 request body exceeds 64 KiB.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        The workspace or environment concurrent-call, per-minute, or
        maximum-duration limit was exceeded. Codes: capacity_exceeded,
        rate_limited, or limit_exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: >-
        Calling or the backend is unavailable. Codes include
        calling_unavailable, environment_unavailable, not_configured, and
        backend_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Thred API key
      description: >-
        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.

````

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