Structured outputs

7 endpoints. Every path below is relative to the API base URL and already includes the /api/v1 prefix — see conventions for authentication, pagination, errors and idempotency.

	Endpoint
GET	`/structured-outputs`	Lists the organization's structured output definitions, optionally filtered to one target surface
POST	`/structured-outputs`	Creates a draft structured output definition after validating its JSON Schema
GET	`/structured-outputs/{structuredOutput}`	Returns one structured output definition with its schema and extraction prompt
PUT	`/structured-outputs/{structuredOutput}`	Updates a structured output definition, re-validating the schema when one is supplied
DELETE	`/structured-outputs/{structuredOutput}`	Deletes a structured output definition and detaches it from every assistant that used it
POST	`/structured-outputs/{structuredOutput}/publish`	Freezes the definition's schema into a new immutable version and returns its id and number
GET	`/structured-outputs/templates`	Returns the built-in starter definitions, each ready to POST back as a new structured output

Endpoints

Lists the organization's structured output definitions, optionally filtered to one target surface

GET/structured-outputs

Requires assistant.read.
Query params: target (call|chat|both), limit (default 25, capped at 100).

Query parameters

Name	Type	Required	Notes
`limit`	integer	—	default `25`

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/structured-outputs?limit=25" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs?limit=25`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs?limit=25');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs?limit=25",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	Paginated set of `StructuredOutputResource`

Errors

Status	When it happens
`403`	The key lacks assistant.read

Example response, generated from the schema:

json

{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "name": "Support Line",
      "key": "string",
      "description": "string",
      "template": "string",
      "target": "string",
      "schema": {},
      "prompt": "string",
      "model": {},
      "status": "string",
      "is_published": true,
      "version": 1,
      "current_version_id": "01JQ0000000000000000000000",
      "enabled": true,
      "metadata": {},
      "created_at": "2026-01-01T12:00:00+00:00",
      "updated_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Creates a draft structured output definition after validating its JSON Schema

POST/structured-outputs

Requires assistant.write.
key is derived from name when omitted and is made unique, so the stored key may differ from what you sent.

Request body

Field	Type	Required	Notes
`name`	string	yes	max 255 chars
`key`	string \| null	—	max 96 chars
`description`	string \| null	—	max 2000 chars
`template`	`summary` · `sentiment` · `success` · `follow_up` · `lead_qualification` · `customer_fields` … \| null	—
`target`	`call` · `chat` · `both` · `null` \| null	—
`schema`	string[]	yes	min 1 items
`prompt`	string \| null	—	max 20000 chars
`model`	string[] \| null	—
`enabled`	boolean \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/structured-outputs" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "schema": [
         "string"
       ],
       "template": "summary",
       "target": "call",
       "enabled": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "schema": [
      "string"
    ],
    "template": "summary",
    "target": "call",
    "enabled": true
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'schema' => [
        'string',
    ],
    'template' => 'summary',
    'target' => 'call',
    'enabled' => true,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "schema": [
        "string"
      ],
      "template": "summary",
      "target": "call",
      "enabled": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`201`	`StructuredOutputResource`

Errors

Status	When it happens
`403`	The key lacks assistant.write
`422`	Validation failed, including per-node JSON Schema errors on `schema`

Example response, generated from the schema:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "template": "string",
    "target": "string",
    "schema": {},
    "prompt": "string",
    "model": {},
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "enabled": true,
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns one structured output definition with its schema and extraction prompt

GET/structured-outputs/{structuredOutput}

Requires assistant.read.

Path parameters

Name	Type	Required	Notes
`structuredOutput`	string	yes	The structured output ID

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/structured-outputs/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`StructuredOutputResource`

Errors

Status	When it happens
`403`	The key lacks assistant.read
`404`	No such definition in this organization

Example response, generated from the schema:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "template": "string",
    "target": "string",
    "schema": {},
    "prompt": "string",
    "model": {},
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "enabled": true,
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Updates a structured output definition, re-validating the schema when one is supplied

PUT/structured-outputs/{structuredOutput}

Requires assistant.write.
PATCH is accepted on the same path, with the same body.
Changing key re-runs uniqueness, so the stored key may be suffixed.

Path parameters

Name	Type	Required	Notes
`structuredOutput`	string	yes	The structured output ID

Request body

Field	Type	Required	Notes
`name`	string	—	max 255 chars
`key`	string \| null	—	max 96 chars
`description`	string \| null	—	max 2000 chars
`template`	`summary` · `sentiment` · `success` · `follow_up` · `lead_qualification` · `customer_fields` … \| null	—
`target`	`call` · `chat` · `both` · `null` \| null	—
`schema`	string[]	—
`prompt`	string \| null	—	max 20000 chars
`model`	string[] \| null	—
`enabled`	boolean \| null	—
`metadata`	string[] \| null	—

cURLJavaScriptPHPPython

bash

curl -X PUT "$CALLAGENT_API_URL/structured-outputs/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "template": "summary",
       "target": "call",
       "enabled": true
     }'

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs/01JQ0000000000000000000000`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "template": "summary",
    "target": "call",
    "enabled": true
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'template' => 'summary',
    'target' => 'call',
    'enabled' => true,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.put(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "template": "summary",
      "target": "call",
      "enabled": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`StructuredOutputResource`

Errors

Status	When it happens
`403`	The key lacks assistant.write
`404`	No such definition in this organization
`422`	Validation failed, including JSON Schema errors on `schema`

Example response, generated from the schema:

json

{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "key": "string",
    "description": "string",
    "template": "string",
    "target": "string",
    "schema": {},
    "prompt": "string",
    "model": {},
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "enabled": true,
    "metadata": {},
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00"
  }
}

Deletes a structured output definition and detaches it from every assistant that used it

DELETE/structured-outputs/{structuredOutput}

Requires assistant.write.
This response is not data-wrapped.
Body is a bare {"deleted": true, "id": "..."}. Side effect: assistants using this definition are silently detached.

Path parameters

Name	Type	Required	Notes
`structuredOutput`	string	yes	The structured output ID

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/structured-outputs/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	Bare JSON object, not `data`-wrapped

Errors

Status	When it happens
`403`	The key lacks assistant.write
`404`	No such definition in this organization

Example response, generated from the schema:

json

{
  "deleted": true,
  "id": null
}

Freezes the definition's schema into a new immutable version and returns its id and number

POST/structured-outputs/{structuredOutput}/publish

Requires assistant.write.
Returns only {version_id, version}, not a full version resource. Optional body field change_summary.

Path parameters

Name	Type	Required	Notes
`structuredOutput`	string	yes	The structured output ID

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/structured-outputs/01JQ0000000000000000000000/publish" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs/01JQ0000000000000000000000/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs/01JQ0000000000000000000000/publish');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs/01JQ0000000000000000000000/publish",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`201`	`data`-wrapped object

Errors

Status	When it happens
`403`	The key lacks assistant.write
`404`	No such definition in this organization
`422`	The schema fails validation

Example response, generated from the schema:

json

{
  "data": {
    "version_id": null,
    "version": 1
  }
}

Returns the built-in starter definitions, each ready to POST back as a new structured output

GET/structured-outputs/templates

No scope is enforced in the handler — any valid key may call it.
The only route in this group with no policy check at all — any authenticated key of any scope can read it.

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/structured-outputs/templates" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/structured-outputs/templates`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/structured-outputs/templates');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/structured-outputs/templates",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped object

Example response, generated from the schema:

json

{
  "data": {
    "summary": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "sentiment": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "success": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "follow_up": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "lead_qualification": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "customer_fields": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "appointment": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "order_data": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    },
    "compliance": {
      "name": "Support Line",
      "description": "string",
      "target": "string",
      "prompt": "string",
      "schema": {}
    }
  }
}

Structured outputs ​

Endpoints ​

Lists the organization's structured output definitions, optionally filtered to one target surface ​

Creates a draft structured output definition after validating its JSON Schema ​

Returns one structured output definition with its schema and extraction prompt ​

Updates a structured output definition, re-validating the schema when one is supplied ​

Deletes a structured output definition and detaches it from every assistant that used it ​

Freezes the definition's schema into a new immutable version and returns its id and number ​

Returns the built-in starter definitions, each ready to POST back as a new structured output ​

Structured outputs

Endpoints

Lists the organization's structured output definitions, optionally filtered to one target surface

Creates a draft structured output definition after validating its JSON Schema

Returns one structured output definition with its schema and extraction prompt

Updates a structured output definition, re-validating the schema when one is supplied

Deletes a structured output definition and detaches it from every assistant that used it

Freezes the definition's schema into a new immutable version and returns its id and number

Returns the built-in starter definitions, each ready to POST back as a new structured output