From a02ff8e7fa6219c9eca90e2d4f947c4d9ad57f64 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Wed, 7 Oct 2026 21:34:07 +0800
Subject: [PATCH 1/6] fix(ci): restore structured Feishu review cards (#492)
---
.github/workflows/ci-review.yml | 6 +--
docs/maintainers.md | 2 +-
docs/zh/maintainers.md | 4 +-
scripts/ci_review.py | 96 ++++++++++++++++++++-------------
scripts/ci_review_test.py | 56 +++++++++++++++----
5 files changed, 112 insertions(+), 52 deletions(-)
diff --git a/.github/workflows/ci-review.yml b/.github/workflows/ci-review.yml
index 2f328e429..2bc1069bd 100644
--- a/.github/workflows/ci-review.yml
+++ b/.github/workflows/ci-review.yml
@@ -48,7 +48,7 @@ jobs:
persist-credentials: false
- name: Prepare the report schema
id: schema
- run: python3 scripts/ci_review.py schema >> "$GITHUB_OUTPUT"
+ run: python3 scripts/ci_review.py schema "${{ matrix.kind }}" >> "$GITHUB_OUTPUT"
- name: Review with Claude Code
id: llm
continue-on-error: true
@@ -78,7 +78,7 @@ jobs:
${{ matrix.instructions }}
- 按 JSON schema 返回中文报告。status 为 ok（未发现问题）、issues（发现有证据的问题）或 incomplete（审查失败、范围未检查完整或检查结果尚未完成）。有问题且仍有未检查项时，用 issues 并在 summary 中说明缺项。summary 无问题时简短，有问题时保留依据和建议，遵守 schema 的长度限制。
+ 按 JSON schema 返回中文报告。status 为 ok（未发现问题）、issues（发现有证据的问题）或 incomplete（审查失败、范围未检查完整或检查结果尚未完成）。有问题且仍有未检查项时，用 issues 并在对应字段中说明缺项。按 schema 把各项结论分别填入字段，不要重复标题；changes 用 1–3 条 Markdown 列表，其他字段无问题时一句话，有问题时保留依据和建议，遵守各字段长度限制。
围绕本次 diff 和受影响的文档展开，证据充分后输出结果，避免重复核对同一结论。
只读审查，不修改仓库，不触发新的 CI，不发送消息。两份报告会由后续 job 合并发送。
claude_args: >-
@@ -89,7 +89,7 @@ jobs:
env:
REVIEW_OUTCOME: ${{ steps.llm.outcome }}
REVIEW_RESULT: ${{ steps.llm.outputs.structured_output }}
- run: python3 scripts/ci_review.py collect "$RUNNER_TEMP/review-${{ matrix.kind }}.json"
+ run: python3 scripts/ci_review.py collect "${{ matrix.kind }}" "$RUNNER_TEMP/review-${{ matrix.kind }}.json"
- uses: actions/upload-artifact@v6
if: always()
with:
diff --git a/docs/maintainers.md b/docs/maintainers.md
index 7f3ac6626..a410ad2d1 100644
--- a/docs/maintainers.md
+++ b/docs/maintainers.md
@@ -194,7 +194,7 @@ Use **Actions → core-check → Run workflow** for a manual full check. For a t
The `CI review and Feishu notification` workflow runs after a PR merges into main. A matrix runs **Code review** and **Docs review** in independent LLM contexts with `fail-fast: false`. Both read the merged commit and PR diff. Code review checks implementation, repository rules and existing CI results; it does not start another test run. Docs review checks changed behavior against documentation even when no docs changed. When docs change, it also checks contradictions, duplicated facts, topic ownership under CONTRIBUTING, and English/Chinese agreement. Findings include file and line references, supporting evidence and a minimal correction. Reviews read the repository without editing it.
-Each review returns a structured result (`ok`, `issues` or `incomplete`) and a Chinese summary, retained as an Actions artifact for seven days. **Combined Feishu notification** waits for both jobs and sends one Card 2.0 message containing both results through the existing `FEISHU_WEBHOOK_URL`; `FEISHU_WEBHOOK_SECRET` optionally signs it. Only this notification job receives the webhook secrets. Failed, missing or invalid reports appear as incomplete, alongside any available result from the other review. The notification job runs even when a review fails. Delivery requires Feishu's `code=0` response; a failed or ambiguous request is not automatically retried, avoiding duplicate messages. Each review has a 25-minute execution timeout. Review and delivery failures do not block merges, and closing an unmerged PR does not trigger this workflow. The workflow checks out only the merged commit with notification credentials.
+Each review returns a structured result (`ok`, `issues` or `incomplete`) and Chinese sections, retained as an Actions artifact for seven days. **Combined Feishu notification** waits for both jobs and sends one Card 2.0 message containing both results through the existing `FEISHU_WEBHOOK_URL`; `FEISHU_WEBHOOK_SECRET` optionally signs it. The card uses fixed sections for PR details, behavior changes, code and repository rules, CI results, and documentation review, separated by dividers. Its header shows green for no findings, red for findings, and yellow for an incomplete review without findings. Only this notification job receives the webhook secrets. Failed, missing or invalid reports appear as incomplete, alongside any available result from the other review. The notification job runs even when a review fails. Delivery requires Feishu's `code=0` response; a failed or ambiguous request is not automatically retried, avoiding duplicate messages. Each review has a 25-minute execution timeout. Review and delivery failures do not block merges, and closing an unmerged PR does not trigger this workflow. The workflow checks out only the merged commit with notification credentials.
Browser jobs own separate fixtures and servers; increasing workers against the shared mutable fixture is unsafe. Failed browser jobs retain reports/traces for seven days. Native failure phase summaries are retained for seven days and detailed output stays in the Actions logs; credentials and temporary installation trees are not uploaded. Successful native archives are uploaded only for explicit manual packaging or releases, without recompressing the compressed archive. Release distribution artifacts retain their existing recovery policy; failed publication can reuse the original build as described above.
diff --git a/docs/zh/maintainers.md b/docs/zh/maintainers.md
index 6fb303605..f6b2b17e3 100644
--- a/docs/zh/maintainers.md
+++ b/docs/zh/maintainers.md
@@ -1,7 +1,7 @@
---
title: "构建并发布 OpenAgentCore"
source: docs/maintainers.md
-source_hash: e3435d01696a172a0a0bcd5acecf4167410389f2c249730c9333f5d24027248d
+source_hash: aaadeb3a5e99b8d926e9f78b7fc41c7aba808e0d2af58969119e67954f9d7a58
---
本指南面向负责构建和发布 OpenAgentCore 的维护者。要安装 Core 和 Web，请使用 [安装指南](getting-started/install.md)。安装器代码遵循的规则见 [部署](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md) 和 [节点安装器](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md)；必需检查见 [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#required-checks)。
@@ -198,7 +198,7 @@ Go 模块和工作区输入会选择后端、API（包括容器）、原生和
`CI review and Feishu notification` 工作流在 PR 合入 main 后运行。矩阵中的 **Code review** 和 **Docs review** 使用独立的 LLM 上下文，并设置 `fail-fast: false`。两者读取合并后的提交和 PR 差异。代码审查检查实现、仓库规则和已有 CI 结果，不触发新一轮测试。文档审查会核对行为变化与文档是否一致，即使没有修改文档；修改文档时，还会检查矛盾、重复维护的事实、CONTRIBUTING 规定的主题归属及中英文含义。每项问题包含文件和行号、依据及最小修改建议。审查只读取仓库，不修改文件。
-每项审查返回结构化结果（`ok`、`issues` 或 `incomplete`）及中文摘要，作为 Actions 构建产物保留七天。**Combined Feishu notification** 等待两项审查结束，通过已有的 `FEISHU_WEBHOOK_URL` 发送一张包含两份结果的 Card 2.0 卡片；可选的 `FEISHU_WEBHOOK_SECRET` 用于签名。只有通知 job 能读取 webhook 密钥。审查失败、报告缺失或格式无效时标为未完成，另一项已有的结果照常展示。某项审查失败时，通知 job 仍会运行。只有飞书返回 `code=0` 才确认送达；请求失败或送达状态不明时不自动重试，以免重复发消息。每项审查的执行超时为 25 分钟。审查和发送失败不会阻止合并；关闭未合并的 PR 不触发此流程。持有通知凭据时，工作流只检出合并后的提交。
+每项审查返回结构化结果（`ok`、`issues` 或 `incomplete`）及分项中文结论，作为 Actions 构建产物保留七天。**Combined Feishu notification** 等待两项审查结束，通过已有的 `FEISHU_WEBHOOK_URL` 发送一张包含两份结果的 Card 2.0 卡片；可选的 `FEISHU_WEBHOOK_SECRET` 用于签名。卡片固定分为 PR 信息、行为变化、代码与仓库规则、CI 结果和文档审查，各区之间使用分隔线。未发现问题时标题为绿色，发现问题时为红色，审查未完成且尚未发现问题时为黄色。只有通知 job 能读取 webhook 密钥。审查失败、报告缺失或格式无效时标为未完成，另一项已有的结果照常展示。某项审查失败时，通知 job 仍会运行。只有飞书返回 `code=0` 才确认送达；请求失败或送达状态不明时不自动重试，以免重复发消息。每项审查的执行超时为 25 分钟。审查和发送失败不会阻止合并；关闭未合并的 PR 不触发此流程。持有通知凭据时，工作流只检出合并后的提交。
浏览器作业各自拥有独立的固定数据和服务；对共享可变固定数据增加 worker 数不安全。失败的浏览器作业保留报告与 trace 七天。原生失败阶段摘要保留七天，详细输出留在 Actions 日志中；凭据和临时安装目录不上传。成功的原生归档仅用于显式手动打包或发布时上传，不重新压缩已压缩的归档。发布分发产物保留现有恢复策略；失败发布可以按前述方式复用原构建。
diff --git a/scripts/ci_review.py b/scripts/ci_review.py
index a6b97b887..e7fb16645 100644
--- a/scripts/ci_review.py
+++ b/scripts/ci_review.py
@@ -15,46 +15,50 @@
STATUSES = {"ok": "未发现问题", "issues": "发现问题", "incomplete": "未完成"}
-MAX_SUMMARY = 2000
-SCHEMA = {
- "type": "object",
- "properties": {
- "status": {"type": "string", "enum": list(STATUSES)},
- "summary": {"type": "string", "minLength": 1, "maxLength": MAX_SUMMARY},
- },
- "required": ["status", "summary"],
- "additionalProperties": False,
+MAX_SECTION = 900
+REPORT_FIELDS = {
+ "code": {"changes": "实际行为变化，1–3 条 Markdown 列表", "review": "代码正确性与仓库规则审查结论", "ci": "已有 CI 结果；失败或未完成时给出具体检查项"},
+ "docs": {"consistency": "文档与代码一致性", "organization": "文档矛盾、重复与归属；未改文档时写本次未修改文档"},
}
-def incomplete(reason):
- return {"status": "incomplete", "summary": reason}
+def report_schema(kind):
+ properties = {"status": {"type": "string", "enum": list(STATUSES)}}
+ properties.update({name: {"type": "string", "minLength": 1, "maxLength": MAX_SECTION, "description": description}
+ for name, description in REPORT_FIELDS[kind].items()})
+ return {"type": "object", "properties": properties, "required": list(properties), "additionalProperties": False}
-def parse_report(raw):
+def incomplete(reason, kind):
+ fields = dict.fromkeys(REPORT_FIELDS[kind], "未完成。")
+ fields[next(iter(fields))] = reason
+ return {"status": "incomplete", **fields}
+
+
+def parse_report(raw, kind):
try:
report = json.loads(raw)
except (ValueError, TypeError):
- return incomplete("未收到有效报告，请查看审查日志。")
- if (not isinstance(report, dict) or set(report) != set(SCHEMA["required"])
+ return incomplete("未收到有效报告，请查看审查日志。", kind)
+ if (not isinstance(report, dict) or set(report) != {"status", *REPORT_FIELDS[kind]}
or not isinstance(report["status"], str) or report["status"] not in STATUSES
- or not isinstance(report["summary"], str) or not report["summary"].strip()
- or len(report["summary"]) > MAX_SUMMARY):
- return incomplete("报告格式不完整，请查看审查日志。")
+ or any(not isinstance(report[name], str) or not report[name].strip()
+ or len(report[name]) > MAX_SECTION for name in REPORT_FIELDS[kind])):
+ return incomplete("报告格式不完整，请查看审查日志。", kind)
return report
-def collect(outcome, raw):
+def collect(outcome, raw, kind):
if outcome != "success":
- return incomplete("审查未成功结束，请查看审查日志。")
- return parse_report(raw)
+ return incomplete("审查未成功结束，请查看审查日志。", kind)
+ return parse_report(raw, kind)
def read_report(directory, kind):
try:
- return parse_report((directory / f"review-{kind}.json").read_text())
+ return parse_report((directory / f"review-{kind}.json").read_text(), kind)
except (OSError, UnicodeError):
- return incomplete("审查报告缺失，请查看审查日志。")
+ return incomplete("审查报告缺失，请查看审查日志。", kind)
def markdown_text(value):
@@ -65,26 +69,44 @@ def build_card(event, reports, run_url):
pr = event["pull_request"]
statuses = {report["status"] for report in reports.values()}
color = "red" if "issues" in statuses else "yellow" if "incomplete" in statuses else "green"
- elements = [{"tag": "markdown", "content": (
- f"**{markdown_text(pr['title'][:200])}**\n"
- f"{markdown_text(pr['user']['login'])} · [PR #{pr['number']}]({pr['html_url']})"
- )}]
- for kind, title in (("code", "代码审查与 CI"), ("docs", "文档审查")):
- report = reports[kind]
+ heading = "❌ 审查发现问题" if "issues" in statuses else "⚠️ 审查未完成" if "incomplete" in statuses else "✅ 审查通过"
+ code, docs = reports["code"], reports["docs"]
+
+ def text(value):
# Feishu mentions use HTML-like tags; reports are ordinary Markdown.
- summary = report["summary"].replace("<", "<").replace(">", ">")
- elements.append({"tag": "markdown", "content": f"**{title}：{STATUSES[report['status']]}**\n{summary}"})
+ return value.replace("<", "<").replace(">", ">")
+
+ sections = [
+ ("1. 哪个 PR", f"**github id:** {markdown_text(pr['user']['login'])}\n"
+ f"**标题:** {markdown_text(pr['title'][:200])}\n**链接:** [PR #{pr['number']}]({pr['html_url']})"),
+ ("2. 改了什么", text(code["changes"])),
+ ("3. 代码与仓库规则", text(code["review"])),
+ ("4. CI 结果", text(code["ci"])),
+ (f"5. 文档审查 · {STATUSES[docs['status']]}",
+ f"**文档与代码一致性**\n{text(docs['consistency'])}\n\n"
+ f"**文档矛盾、重复与归属**\n{text(docs['organization'])}"),
+ ]
+ elements = []
+ for title, content in sections:
+ if elements:
+ elements.append({"tag": "hr"})
+ elements.append({"tag": "markdown", "content": f"**{title}**\n\n{content}"})
elements.append({"tag": "markdown", "content": f"[查看审查日志]({run_url})"})
return {
"msg_type": "interactive",
"card": {
"schema": "2.0",
- "header": {"template": color, "title": {"tag": "plain_text", "content": f"CI 审查 · PR #{pr['number']}"}},
+ "header": {"template": color, "title": {"tag": "plain_text", "content": f"{heading} · PR #{pr['number']}"}},
"body": {"elements": elements},
},
}
+def card_markdown(card):
+ return "\n\n".join("---" if element["tag"] == "hr" else element["content"]
+ for element in card["card"]["body"]["elements"]) + "\n"
+
+
def send_card(webhook, secret, card):
if not webhook:
raise ValueError("FEISHU_WEBHOOK_URL is not configured")
@@ -110,14 +132,16 @@ def send_card(webhook, secret, card):
def main():
parser = argparse.ArgumentParser(description=__doc__)
commands = parser.add_subparsers(dest="command", required=True)
- commands.add_parser("schema")
- commands.add_parser("collect").add_argument("output", type=Path)
+ commands.add_parser("schema").add_argument("kind", choices=REPORT_FIELDS)
+ collector = commands.add_parser("collect")
+ collector.add_argument("kind", choices=REPORT_FIELDS)
+ collector.add_argument("output", type=Path)
commands.add_parser("notify").add_argument("directory", type=Path)
args = parser.parse_args()
if args.command == "schema":
- print("schema=" + json.dumps(SCHEMA, separators=(",", ":")))
+ print("schema=" + json.dumps(report_schema(args.kind), separators=(",", ":")))
elif args.command == "collect":
- report = collect(os.environ.get("REVIEW_OUTCOME"), os.environ.get("REVIEW_RESULT", ""))
+ report = collect(os.environ.get("REVIEW_OUTCOME"), os.environ.get("REVIEW_RESULT", ""), args.kind)
args.output.write_text(json.dumps(report, ensure_ascii=False))
else:
event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
@@ -127,7 +151,7 @@ def main():
summary = os.environ.get("GITHUB_STEP_SUMMARY")
if summary:
with open(summary, "a") as output:
- output.write("\n\n".join(element["content"] for element in card["card"]["body"]["elements"]) + "\n")
+ output.write(card_markdown(card))
send_card(os.environ.get("FEISHU_WEBHOOK_URL"), os.environ.get("FEISHU_WEBHOOK_SECRET"), card)
print("代码与文档审查结果已合并发送至飞书群。")
diff --git a/scripts/ci_review_test.py b/scripts/ci_review_test.py
index 05161c0a8..c80fdfd99 100644
--- a/scripts/ci_review_test.py
+++ b/scripts/ci_review_test.py
@@ -16,38 +16,73 @@ class ReviewTests(unittest.TestCase):
run_url = "https://github.com/org/repo/actions/runs/123"
def setUp(self):
- self.ok = {"status": "ok", "summary": "未发现问题"}
+ self.ok = {"status": "ok", "changes": "- 更新安装流程", "review": "未发现问题", "ci": "全部通过 ✅"}
+ self.docs = {"status": "ok", "consistency": "与代码一致", "organization": "无矛盾或重复"}
def card(self, code=None, docs=None):
- return review.build_card(self.event, {"code": code or self.ok, "docs": docs or self.ok}, self.run_url)
+ return review.build_card(self.event, {"code": code or self.ok, "docs": docs or self.docs}, self.run_url)
@patch("ci_review.urllib.request.urlopen")
def test_two_reports_make_one_delivery(self, post):
post.return_value = io.BytesIO(b'{"code":0}')
- card = self.card(docs={"status": "issues", "summary": "docs/install.md:12 与代码不符"})
+ card = self.card(docs={**self.docs, "status": "issues", "consistency": "docs/install.md:12 与代码不符"})
review.send_card("https://example.invalid/webhook", "", card)
post.assert_called_once()
payload = json.loads(post.call_args.args[0].data)
self.assertEqual(payload["card"]["schema"], "2.0")
self.assertEqual(payload["card"]["header"]["template"], "red")
- text = "\n".join(item["content"] for item in payload["card"]["body"]["elements"])
- self.assertIn("代码审查与 CI：未发现问题", text)
- self.assertIn("文档审查：发现问题", text)
+ text = review.card_markdown(payload)
+ self.assertIn("3. 代码与仓库规则", text)
+ self.assertIn("文档审查 · 发现问题", text)
self.assertIn("docs/install.md:12", text)
self.assertIn(self.run_url, text)
self.assertNotIn("sign", payload)
+ def test_fixed_sections_preserve_markdown_and_separators(self):
+ card = self.card()
+ elements = card["card"]["body"]["elements"]
+ self.assertEqual(sum(element["tag"] == "hr" for element in elements), 4)
+ text = review.card_markdown(card)
+ for heading in ("1. 哪个 PR", "2. 改了什么", "3. 代码与仓库规则", "4. CI 结果", "5. 文档审查"):
+ self.assertIn(heading, text)
+ self.assertIn("- 更新安装流程", text)
+ self.assertIn("全部通过 ✅", text)
+ self.assertIn("文档与代码一致性", text)
+ self.assertIn("文档矛盾、重复与归属", text)
+ self.assertIn("---", text)
+ self.assertEqual(card["card"]["header"]["template"], "green")
+ self.assertIn("✅ 审查通过", card["card"]["header"]["title"]["content"])
+
+ def test_pending_ci_does_not_label_the_code_review_incomplete(self):
+ card = self.card(code={**self.ok, "status": "incomplete", "ci": "backend 仍在运行"})
+ text = review.card_markdown(card)
+ self.assertIn("**3. 代码与仓库规则**", text)
+ self.assertIn("未发现问题", text)
+ self.assertIn("backend 仍在运行", text)
+ self.assertEqual(card["card"]["header"]["template"], "yellow")
+
+ def test_each_kind_requires_its_own_sections(self):
+ for kind, report in (("code", self.ok), ("docs", self.docs)):
+ self.assertEqual(review.parse_report(json.dumps(report), kind), report)
+ self.assertEqual(set(review.report_schema(kind)["required"]), set(report))
+ for field in review.REPORT_FIELDS[kind]:
+ for value in (None, " ", "x" * (review.MAX_SECTION + 1)):
+ invalid = {**report, field: value}
+ self.assertEqual(review.parse_report(json.dumps(invalid), kind)["status"], "incomplete")
+ missing = {key: value for key, value in report.items() if key != field}
+ self.assertEqual(review.parse_report(json.dumps(missing), kind)["status"], "incomplete")
+
def test_failed_action_cannot_publish_a_success_report(self):
for outcome in ("failure", "cancelled", "skipped", None):
with self.subTest(outcome=outcome):
- result = review.collect(outcome, json.dumps(self.ok))
+ result = review.collect(outcome, json.dumps(self.ok), "code")
self.assertEqual(result["status"], "incomplete")
self.assertEqual(self.card(code=result)["card"]["header"]["template"], "yellow")
def test_invalid_or_missing_reports_are_incomplete(self):
for raw in ("", "not json", "null", "[]", '{"status":"ok"}', '{"status":[],"summary":"x"}', '{"status":"ok","summary":" "}', json.dumps({"status": "ok", "summary": "x" * 2001})):
with self.subTest(raw=raw[:50]):
- self.assertEqual(review.collect("success", raw)["status"], "incomplete")
+ self.assertEqual(review.collect("success", raw, "code")["status"], "incomplete")
root = Path.home() / ".oac/tests"
root.mkdir(parents=True, exist_ok=True)
with tempfile.TemporaryDirectory(dir=root) as directory:
@@ -85,8 +120,9 @@ def test_optional_signing(self, post, _clock):
@patch("ci_review.urllib.request.urlopen")
def test_bounded_unicode_reports_and_mentions(self, post):
post.return_value = io.BytesIO(b'{"code":0}')
- report = {"status": "issues", "summary": "所有人" + "问" * 1950}
- review.send_card("https://example.invalid/webhook", "", self.card(report, report))
+ reports = {kind: {"status": "issues", **dict.fromkeys(fields, "所有人" + "问" * (review.MAX_SECTION - 20))}
+ for kind, fields in review.REPORT_FIELDS.items()}
+ review.send_card("https://example.invalid/webhook", "", self.card(reports["code"], reports["docs"]))
data = post.call_args.args[0].data
self.assertLess(len(data), 20000)
self.assertNotIn(b"
Date: Wed, 7 Oct 2026 21:48:13 +0800
Subject: [PATCH 2/6] Mirror the native matrix sentence in zh maintainers
(#495)
---
docs/zh/maintainers.md | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/docs/zh/maintainers.md b/docs/zh/maintainers.md
index f6b2b17e3..924c3b19f 100644
--- a/docs/zh/maintainers.md
+++ b/docs/zh/maintainers.md
@@ -184,9 +184,7 @@ gh workflow run core-release --repo MiniMax-AI/OpenAgentCore --ref main \
`.github/actionlint.yaml` 会选择 hygiene 和 lint。已知工作流变更会选择其使用方：CI review 和 actionlint 工作流运行 hygiene 和 lint；原生工作流变更会添加原生检查；API 验收工作流变更会添加启用容器验收的 API 检查；网站工作流变更会添加网站检查。共享 Node 操作会选择使用它的每个作业以及 lint。新工作流或未分类的工作流/操作会选择完整门禁，直至在计划器中声明其使用方。计划器测试和 CI 测量脚本运行 hygiene；更改计划器本身会运行完整门禁。
-Core 安装器在 Linux、macOS 和 Windows 原生 CI 中构建并测试。Compose 冒烟测试分别使用 Linux amd64 和 arm64 原生 runner。
-
-Compose 模板和 Compose 测试发生变更时，会同时选择 `distribution` 固定数据和 `compose` 冒烟作业；Core、Web、共享 Go 软件包和镜像 Dockerfile 的变更也会选择冒烟作业。安装 Docker 后，可在本地运行 `python3 scripts/compose-smoke.py` 重复该测试。该脚本使用唯一的项目、自动分配的回环端口，并将在 `~/.oac/tests/` 下生成构件；退出时移除其容器和数据卷。CI 还会在冒烟步骤失败或中断后执行清理。诊断信息会显示容器状态，但不会打印 HTTP 响应正文或登录密钥。Core、Web 和 ingress 镜像都从当前检出构建；Web 提供占位页面而不是控制台构建。构建时的节点元数据来自 `deploy/compose/smoke-pins.json` 固定的发布版本；初始化容器禁用网络运行。
+Compose 模板和 Compose 测试发生变更时，会同时选择 `distribution` 固定数据和 `compose` 冒烟作业；Core、Web、共享 Go 软件包和镜像 Dockerfile 的变更也会选择冒烟作业。安装 Docker 后，可在本地运行 `python3 scripts/compose-smoke.py` 重复该测试。该脚本使用唯一的项目、自动分配的回环端口，并将在 `~/.oac/tests/` 下生成构件；退出时移除其容器和数据卷。CI 还会在冒烟步骤失败或中断后执行清理。诊断信息会显示容器状态，但不会打印 HTTP 响应正文或登录密钥。Core、Web 和 ingress 镜像都从当前检出构建；Web 提供占位页面而不是控制台构建。构建时的节点元数据来自 `deploy/compose/smoke-pins.json` 固定的发布版本；初始化容器禁用网络运行。冒烟矩阵使用 Linux amd64 和 arm64 原生 runner；原生矩阵在 Linux、macOS 和 Windows 上构建并测试共享的 Core 安装器。
Go 模块和工作区输入会选择后端、API（包括容器）、原生和分发检查。每个 Node 模块都拥有自己的清单和锁文件。网站依赖项会选择网站检查；Web 依赖项会选择 Web 和浏览器检查；示例依赖项会选择示例检查；共享 TypeScript 客户端依赖项会选择 Web、浏览器和示例检查；Claude 适配器依赖项会选择 Harness、原生和分发检查。共享包管理器配置会选择所有 Node 使用方。根 TypeScript 配置会选择 Web 和示例检查；适配器 TypeScript 配置会选择 Harness 和原生检查。每个所选集合都包含 hygiene。混合变更会累加其使用方，并且每个作业都读取同一计划，而不是维护各自的路径列表。例如，仅修改通知的 PR 会跳过数据库、浏览器和原生作业，而同时修改通知和 Core 的 PR 会添加后端和 API 检查。
From 1fcc0661ec1b9aeb7d192edf4881397625e0e5a9 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Wed, 7 Oct 2026 21:50:12 +0800
Subject: [PATCH 3/6] refactor(api): generate public contracts from official
OpenAPI (#490)
* refactor(api): generate public contracts from pinned official OpenAPI
* test(api): validate OpenAPI 3.1 responses and preserve package rejection
* chore(api): remove unused Swagger parser dependency
* fix(api): derive web search union serialization from the official schema
* fix(api): preserve stored search items during public schema migration
---
.github/workflows/api-acceptance.yml | 1 +
AGENTS.md | 2 +-
Makefile | 16 +-
contracts/agents-api/core.openapi.yaml | 117 +-
contracts/agents-api/go-bindings.json | 642 +
contracts/agents-api/index.md | 14 +-
contracts/agents-api/openapi.yaml | 24873 +++-
contracts/agents-api/runtime.openapi.yaml | 4 +
contracts/agents-api/upstream-fields.json | 2301 -
contracts/agents-api/upstream-routes.json | 10 +-
contracts/agents-api/upstream.json | 8 +-
contracts/agents-api/upstream/LICENSE | 21 +
contracts/agents-api/upstream/openapi.json | 107618 +++++++++++++++
contracts/agents-api/v1/agents.go | 82 -
contracts/agents-api/v1/credentials.go | 99 -
contracts/agents-api/v1/environment_events.go | 10 -
contracts/agents-api/v1/environment_files.go | 25 -
.../agents-api/v1/environment_templates.go | 52 -
contracts/agents-api/v1/environments.go | 39 -
contracts/agents-api/v1/events.go | 42 -
contracts/agents-api/v1/function_actions.go | 10 -
contracts/agents-api/v1/function_tools.go | 12 -
contracts/agents-api/v1/inputs.go | 30 -
contracts/agents-api/v1/items.go | 52 -
contracts/agents-api/v1/items_test.go | 35 +
contracts/agents-api/v1/mcp_tools.go | 34 -
contracts/agents-api/v1/official.gen.go | 996 +
contracts/agents-api/v1/required_actions.go | 15 -
contracts/agents-api/v1/session_artifacts.go | 26 -
contracts/agents-api/v1/session_deletion.go | 7 -
.../agents-api/v1/session_environment.go | 17 -
contracts/agents-api/v1/sessions.go | 130 -
contracts/agents-api/v1/skills.go | 55 -
contracts/agents-api/v1/source_files.go | 27 -
contracts/agents-api/v1/subagent_items.go | 78 +-
contracts/agents-api/v1/subagents.go | 28 -
contracts/agents-api/v1/turns.go | 28 -
.../agents-api/v1/upstream_contract_test.go | 319 +-
contracts/agents-api/v1/usage.go | 15 -
contracts/agents-api/v1/vaults.go | 30 -
contracts/agents-api/zh/index.md | 17 +-
docs/development.md | 2 +-
docs/zh/development.md | 4 +-
scripts/ci_plan.py | 2 +-
scripts/extract-agents-api-upstream.py | 193 -
scripts/generate-harness-catalog.test.py | 4 +
scripts/generate-public-api.py | 276 +
scripts/generate-public-api.test.py | 80 +
scripts/name-allowlist.json | 5 -
scripts/openapi-split/main.go | 146 +-
scripts/openapi-split/main_test.go | 24 +-
services/core/README.md | 2 +-
services/core/internal/api/agents.go | 21 -
services/core/internal/api/agents_delete.go | 10 -
services/core/internal/api/agents_list.go | 12 -
services/core/internal/api/agents_update.go | 12 -
.../core/internal/api/contract_routes_test.go | 8 +-
services/core/internal/api/credentials.go | 23 -
.../core/internal/api/credentials_delete.go | 11 -
.../core/internal/api/credentials_list.go | 15 -
.../core/internal/api/credentials_update.go | 13 -
.../core/internal/api/environment_files.go | 14 -
.../internal/api/environment_files_create.go | 12 -
.../internal/api/environment_templates.go | 55 -
services/core/internal/api/environments.go | 10 -
services/core/internal/api/handler.go | 35 -
services/core/internal/api/inputs.go | 12 -
services/core/internal/api/items.go | 13 -
.../core/internal/api/session_artifacts.go | 46 -
.../core/internal/api/session_deletion.go | 10 -
.../core/internal/api/session_metadata.go | 12 -
services/core/internal/api/skills.go | 43 -
services/core/internal/api/skills_list.go | 21 -
services/core/internal/api/skills_transfer.go | 35 -
services/core/internal/api/source_files.go | 18 -
.../core/internal/api/source_files_content.go | 8 -
.../core/internal/api/source_files_list.go | 12 -
.../core/internal/api/source_files_upload.go | 11 -
services/core/internal/api/stream.go | 11 -
services/core/internal/api/subagent_turns.go | 41 -
services/core/internal/api/subagents.go | 38 -
services/core/internal/api/turns.go | 24 -
services/core/internal/api/vaults.go | 21 -
services/core/internal/api/vaults_delete.go | 10 -
services/core/internal/api/vaults_list.go | 14 -
services/core/tests/official_client.py | 39 +-
services/core/tests/official_schema.py | 41 +
services/core/tests/official_schema_test.py | 80 +
services/core/tests/requirements.txt | 1 -
89 files changed, 129546 insertions(+), 9941 deletions(-)
create mode 100644 contracts/agents-api/go-bindings.json
delete mode 100644 contracts/agents-api/upstream-fields.json
create mode 100644 contracts/agents-api/upstream/LICENSE
create mode 100644 contracts/agents-api/upstream/openapi.json
delete mode 100644 contracts/agents-api/v1/environment_events.go
delete mode 100644 contracts/agents-api/v1/environment_files.go
delete mode 100644 contracts/agents-api/v1/environment_templates.go
delete mode 100644 contracts/agents-api/v1/environments.go
delete mode 100644 contracts/agents-api/v1/function_actions.go
delete mode 100644 contracts/agents-api/v1/function_tools.go
delete mode 100644 contracts/agents-api/v1/inputs.go
delete mode 100644 contracts/agents-api/v1/mcp_tools.go
create mode 100644 contracts/agents-api/v1/official.gen.go
delete mode 100644 contracts/agents-api/v1/session_artifacts.go
delete mode 100644 contracts/agents-api/v1/session_deletion.go
delete mode 100644 contracts/agents-api/v1/session_environment.go
delete mode 100644 contracts/agents-api/v1/skills.go
delete mode 100644 contracts/agents-api/v1/source_files.go
delete mode 100644 contracts/agents-api/v1/subagents.go
delete mode 100644 contracts/agents-api/v1/turns.go
delete mode 100644 contracts/agents-api/v1/usage.go
delete mode 100644 contracts/agents-api/v1/vaults.go
delete mode 100644 scripts/extract-agents-api-upstream.py
create mode 100644 scripts/generate-public-api.py
create mode 100644 scripts/generate-public-api.test.py
create mode 100644 services/core/tests/official_schema.py
create mode 100644 services/core/tests/official_schema_test.py
diff --git a/.github/workflows/api-acceptance.yml b/.github/workflows/api-acceptance.yml
index d4437a4c9..ee010ed18 100644
--- a/.github/workflows/api-acceptance.yml
+++ b/.github/workflows/api-acceptance.yml
@@ -62,6 +62,7 @@ jobs:
OAC_TEST_SERVER_BIN: ${{ runner.temp }}/oac-core-build/oac-core
OAC_TEST_OFFICIAL_SDK_PYTHON: python
run: |
+ python services/core/tests/official_schema_test.py
python services/core/tests/official_client.py
go test ./services/core/tests/integration -run '^(TestFunctionStateOfficialClientReadsAndLiveEvents|TestSavedReferenceRetryOfficialClient|TestAgentUpdateOfficialClient|TestAgentDeletionOfficialClient|TestSessionAgentFilterOfficialClient|TestSessionDeletionOfficialClient|TestEnvironmentInitialFailureOfficialClient|TestSelfHostedInitialCreationOfficialClient|TestSelfHostedCancellationOfficialClient)$' -count=1
- uses: ./.github/actions/e2b-provider
diff --git a/AGENTS.md b/AGENTS.md
index 8ec48e767..d6e200722 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@ Do not multiply entities without necessity. The long-term goal is minimal code,
| Boundary | Protocol code | Protocol doc |
| --- | --- | --- |
-| Application–Core (`/v1`) | Types in `contracts/agents-api/v1/` and route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) |
+| Application–Core (`/v1`) | Official schema pinned by `contracts/agents-api/upstream.json` plus Go-owned `x_agents_core` extensions; `make openapi` generates public Go types and `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) |
| Web and operators–Core (`/core/v1`) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core administration API](contracts/agents-api/admin-api.md) |
| Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](contracts/agents-api/machine-api.md) |
| Core–Sandbox Provider | `services/core/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) |
diff --git a/Makefile b/Makefile
index 1958607db..4d91c1ca8 100644
--- a/Makefile
+++ b/Makefile
@@ -32,21 +32,29 @@ sqlc-generate:
SWAG ?= go run github.com/swaggo/swag/cmd/swag@$(SWAG_VERSION)
-.PHONY: openapi
+.PHONY: openapi check-openapi
+OPENAPI_FLAGS ?=
+check-openapi:
+ $(MAKE) openapi OPENAPI_FLAGS=--check
+ python3 scripts/generate-public-api.test.py
+
openapi:
+ python3 scripts/generate-public-api.py $(OPENAPI_FLAGS)
@set -e; root="$${OAC_DEV_HOME:-$$HOME/.oac}/build"; mkdir -p "$$root"; \
output=$$(mktemp -d "$$root/core-openapi.XXXXXX"); trap 'rm -rf "$$output"' EXIT; \
+ python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --swag-roots "$$output/roots.go"; \
$(SWAG) init \
- -g cmd/server/main.go --dir ./services/core,./contracts/agents-api/v1 \
+ -g cmd/server/main.go --dir "./services/core,./contracts/agents-api/v1,$$output" \
--output "$$output" \
--outputTypes yaml --parseInternal; \
python3 scripts/patch-agents-openapi.py "$$output/swagger.yaml"; \
- go run ./scripts/openapi-split "$$output/swagger.yaml" contracts/agents-api/openapi.yaml contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml
+ go run ./scripts/openapi-split $(OPENAPI_FLAGS) "$$output/swagger.yaml" "$$output/extensions.json" contracts/agents-api/core.openapi.yaml contracts/agents-api/runtime.openapi.yaml; \
+ python3 scripts/generate-public-api.py $(OPENAPI_FLAGS) --extensions "$$output/extensions.json"
check-sqlc:
python3 scripts/check-sqlc.py
-check-go:
+check-go: check-openapi
go test ./apps/daemon/... ./internal/... ./contracts/agents-api/... ./scripts/openapi-split -count=1
.PHONY: check-runtime-contract
diff --git a/contracts/agents-api/core.openapi.yaml b/contracts/agents-api/core.openapi.yaml
index 9a74d1381..fb65920bd 100644
--- a/contracts/agents-api/core.openapi.yaml
+++ b/contracts/agents-api/core.openapi.yaml
@@ -1458,6 +1458,10 @@ definitions:
service_tier:
enum:
- auto
+ - default
+ - flex
+ - priority
+ - fast
type: string
text:
$ref: '#/definitions/v1.TextConfig'
@@ -1466,13 +1470,13 @@ definitions:
type: object
type: array
x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.AgentsCore'
- x-nullable: true
+ $ref: '#/definitions/v1.AgentsCore'
required:
- id
+ - instructions
- model
- multi_agent
+ - name
- reasoning
- service_tier
- text
@@ -1481,8 +1485,6 @@ definitions:
v1.AgentDeleted:
properties:
deleted:
- enum:
- - true
type: boolean
id:
type: string
@@ -1546,8 +1548,8 @@ definitions:
x-nullable: true
type:
enum:
- - static_bearer
- mcp_oauth
+ - static_bearer
type: string
required:
- mcp_server_url
@@ -1588,7 +1590,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.EnvironmentInstallation:
@@ -1684,6 +1688,7 @@ definitions:
- created_at
- files
- id
+ - name
- network
- object
- packages
@@ -1726,7 +1731,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.ExecutionHarnessConfigSelection:
@@ -1794,7 +1801,9 @@ definitions:
v1.Item:
properties:
action:
- $ref: '#/definitions/v1.WebSearchAction'
+ allOf:
+ - $ref: '#/definitions/v1.WebSearchAction'
+ x-nullable: true
agent_id:
type: string
arguments: {}
@@ -1808,18 +1817,25 @@ definitions:
type: array
cwd:
type: string
+ x-nullable: true
duration_ms:
type: integer
- error: {}
+ x-nullable: true
+ error:
+ x-nullable: true
exit_code:
type: integer
+ x-nullable: true
id:
type: string
+ x-nullable: true
model:
type: string
+ x-nullable: true
name:
type: string
- output: {}
+ output:
+ x-nullable: true
phase:
enum:
- commentary
@@ -1828,6 +1844,7 @@ definitions:
x-nullable: true
reasoning_effort:
type: string
+ x-nullable: true
recipient_agent_id:
type: string
recipient_agent_ids:
@@ -1847,9 +1864,10 @@ definitions:
enum:
- in_progress
- completed
- - failed
- incomplete
+ - failed
type: string
+ x-nullable: true
summary:
items:
$ref: '#/definitions/v1.SummaryText'
@@ -1859,13 +1877,13 @@ definitions:
type:
enum:
- message
- - command_execution
- - mcp_call
+ - reasoning
- function_call
- function_call_output
- - web_search_call
- - reasoning
- agent_message
+ - mcp_call
+ - web_search_call
+ - command_execution
- create_subagent_call
- send_subagent_input_call
- resume_subagent_call
@@ -1889,8 +1907,8 @@ definitions:
type:
enum:
- input_text
- - output_text
- input_image
+ - output_text
- encrypted_content
type: string
required:
@@ -1916,7 +1934,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.ModelConfigurationInput:
@@ -1997,6 +2017,7 @@ definitions:
x-nullable: true
required:
- enabled
+ - max_concurrent_subagents
type: object
v1.OAuthCredentialRefresh:
properties:
@@ -2014,6 +2035,8 @@ definitions:
$ref: '#/definitions/v1.OAuthEndpointAuth'
required:
- client_id
+ - resource
+ - scope
- token_endpoint
- token_endpoint_auth
type: object
@@ -2038,9 +2061,21 @@ definitions:
v1.Reasoning:
properties:
effort:
+ enum:
+ - none
+ - minimal
+ - low
+ - medium
+ - high
+ - xhigh
+ - max
type: string
x-nullable: true
summary:
+ enum:
+ - concise
+ - detailed
+ - auto
type: string
x-nullable: true
type: object
@@ -2560,15 +2595,15 @@ definitions:
updated_at:
type: integer
x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentCore'
- x-nullable: true
+ $ref: '#/definitions/v1.SavedAgentCore'
required:
- created_at
- id
+ - instructions
- metadata
- model
- multi_agent
+ - name
- object
- reasoning
- service_tier
@@ -2609,7 +2644,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.SavedAgentText:
@@ -2686,12 +2723,14 @@ definitions:
- agent
- created_at
- environment
+ - error
- id
- last_active_at
- metadata
- object
- required_actions
- status
+ - usage
- vault_ids
type: object
v1.SessionArtifact:
@@ -2759,7 +2798,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.SessionCore:
@@ -2811,8 +2852,8 @@ definitions:
type:
enum:
- none
- - self_hosted
- openai_hosted
+ - self_hosted
type: string
workspace_directory:
type: string
@@ -2868,7 +2909,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.Skill:
@@ -2933,7 +2976,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.SkillVersion:
@@ -3001,19 +3046,19 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.SourceFile:
properties:
bytes:
- minimum: 0
type: integer
created_at:
type: integer
expires_at:
type: integer
- x-nullable: true
filename:
type: string
id:
@@ -3024,15 +3069,23 @@ definitions:
type: string
purpose:
enum:
+ - assistants
+ - assistants_output
+ - batch
+ - batch_output
+ - fine-tune
+ - fine-tune-results
+ - vision
- user_data
type: string
status:
enum:
+ - uploaded
- processed
+ - error
type: string
status_details:
type: string
- x-nullable: true
required:
- bytes
- created_at
@@ -3065,19 +3118,17 @@ definitions:
type: array
first_id:
type: string
- x-nullable: true
has_more:
type: boolean
last_id:
type: string
- x-nullable: true
object:
- enum:
- - list
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.SummaryText:
@@ -3179,11 +3230,16 @@ definitions:
x-nullable: true
required:
- agent_id
+ - completed_at
- created_at
+ - error
- id
- object
- session_id
+ - started_at
- status
+ - subagent_id
+ - usage
type: object
v1.TurnError:
properties:
@@ -3232,7 +3288,9 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.Vault:
@@ -3256,6 +3314,7 @@ definitions:
- created_at
- id
- metadata
+ - name
- object
type: object
v1.VaultDeleted:
@@ -3293,19 +3352,24 @@ definitions:
type: string
required:
- data
+ - first_id
- has_more
+ - last_id
- object
type: object
v1.WebSearchAction:
properties:
pattern:
type: string
+ x-nullable: true
queries:
items:
type: string
type: array
+ x-nullable: true
query:
type: string
+ x-nullable: true
type:
enum:
- search
@@ -3315,6 +3379,7 @@ definitions:
type: string
url:
type: string
+ x-nullable: true
required:
- type
type: object
diff --git a/contracts/agents-api/go-bindings.json b/contracts/agents-api/go-bindings.json
new file mode 100644
index 000000000..176a7d1c7
--- /dev/null
+++ b/contracts/agents-api/go-bindings.json
@@ -0,0 +1,642 @@
+{
+ "APIError": {
+ "sources": ["#/components/schemas/Error"],
+ "fields": {
+ "code": {"type": "*string"}
+ },
+ "order": ["message", "type", "code", "param"]
+ },
+ "Agent": {
+ "sources": ["#/components/schemas/SessionAgentResource"],
+ "fields": {
+ "x_agents_core": {"type": "*AgentsCore"},
+ "reasoning": {"type": "Reasoning"},
+ "text": {"type": "TextConfig"}
+ },
+ "order": ["x_agents_core", "id", "instructions", "model", "multi_agent", "name", "reasoning", "service_tier", "text", "tools"]
+ },
+ "AgentContent": {
+ "sources": ["#/components/schemas/AgentContentResource"],
+ "order": ["type", "text", "encrypted_content"]
+ },
+ "AgentDeleted": {
+ "sources": ["#/components/schemas/DeletedAgentResource"],
+ "order": ["id", "object", "deleted"]
+ },
+ "AgentMessageItem": {
+ "sources": ["#/components/schemas/AgentMessageItemResource"],
+ "order": ["id", "turn_id", "type", "sender_agent_id", "recipient_agent_id", "content"]
+ },
+ "CreateAgentRequest": {
+ "sources": ["#/components/schemas/CreateAgentParams"],
+ "fields": {
+ "x_agents_core": {"type": "*SavedAgentCoreInput"},
+ "model": {"type": "*string"},
+ "metadata": {"type": "map[string]*string"},
+ "reasoning": {"type": "*Reasoning"},
+ "text": {"type": "*SavedAgentTextInput"}
+ },
+ "order": ["x_agents_core", "model", "name", "instructions", "metadata", "multi_agent", "reasoning", "service_tier", "text", "tools"]
+ },
+ "CreateCredentialRequest": {
+ "sources": ["#/components/schemas/CreateVaultCredentialParams"],
+ "fields": {
+ "name": {"type": "*string"},
+ "auth": {"type": "*CredentialAuthInput"}
+ },
+ "order": ["name", "auth"]
+ },
+ "CreateEventsRequest": {
+ "sources": ["#/components/schemas/CreateSessionEventsParams"],
+ "order": ["events"]
+ },
+ "CreateSessionRequest": {
+ "sources": ["#/components/schemas/CreateAgentSessionParams"],
+ "fields": {
+ "x_agents_core": {"type": "*SessionExecutionInput"},
+ "environment": {"type": "*Environment"},
+ "input": {"type": "any"},
+ "stream": {"type": "bool"}
+ },
+ "order": ["x_agents_core", "agent", "agent_id", "environment", "input", "metadata", "stream", "vault_ids"]
+ },
+ "CreateSubagentCallItem": {
+ "sources": ["#/components/schemas/CreateSubagentCallItemResource"],
+ "order": ["id", "turn_id", "type", "status", "agent_id", "content", "model", "reasoning_effort"]
+ },
+ "CreateVaultRequest": {
+ "sources": ["#/components/schemas/CreateVaultParams"],
+ "fields": {
+ "metadata": {"type": "map[string]*string"}
+ },
+ "order": ["name", "metadata"]
+ },
+ "Credential": {
+ "sources": ["#/components/schemas/VaultCredentialResource"],
+ "order": ["id", "vault_id", "name", "object", "auth", "created_at", "updated_at"]
+ },
+ "CredentialAuth": {
+ "sources": ["#/components/schemas/VaultCredentialAuthResource"],
+ "fields": {
+ "expires_at": {"omit": false},
+ "refresh": {"type": "*OAuthCredentialRefresh", "omit": false}
+ },
+ "order": ["type", "mcp_server_url", "expires_at", "refresh"]
+ },
+ "CredentialAuthInput": {
+ "sources": ["#/components/schemas/CreateVaultCredentialAuthParam"],
+ "fields": {
+ "mcp_server_url": {"type": "*string"},
+ "refresh": {"type": "*OAuthCredentialRefreshInput"}
+ },
+ "order": ["type", "mcp_server_url", "token", "access_token", "expires_at", "refresh"]
+ },
+ "CredentialAuthReplacement": {
+ "sources": ["#/components/schemas/RotateVaultCredentialAuthParam"],
+ "fields": {
+ "expires_at": {"type": "json.RawMessage"},
+ "refresh": {"type": "*OAuthCredentialRefreshReplacement"}
+ },
+ "order": ["type", "token", "access_token", "expires_at", "refresh"]
+ },
+ "CredentialDeleted": {
+ "sources": ["#/components/schemas/DeletedVaultCredentialResource"],
+ "order": ["id", "deleted", "object"]
+ },
+ "CredentialList": {
+ "sources": ["#/components/schemas/VaultCredentialListResource"],
+ "order": ["object", "data", "has_more", "first_id", "last_id"]
+ },
+ "Environment": {
+ "sources": ["#/components/schemas/EnvironmentParam"],
+ "fields": {
+ "packages": {"type": "*EnvironmentPackages"},
+ "files": {"type": "[]json.RawMessage"},
+ "environment_template_id": {"type": "string"},
+ "workspace_directory": {"type": "string"},
+ "network": {"type": "*EnvironmentNetworkInput"}
+ },
+ "order": ["plugins", "skills", "env", "setup_commands", "packages", "files", "environment_template_id", "type", "workspace_directory", "capability_directories", "network"]
+ },
+ "EnvironmentConnectionAction": {
+ "sources": ["#/components/schemas/SessionRequiredActionResourceEnvironmentConnection"],
+ "order": ["environment_id", "type"]
+ },
+ "EnvironmentFile": {
+ "sources": ["#/components/schemas/EnvironmentFileResource"],
+ "order": ["environment_id", "object", "path", "size_bytes"]
+ },
+ "EnvironmentFileCreateRequest": {
+ "sources": ["#/components/schemas/HostedEnvironmentFileParam"],
+ "fields": {
+ "path": {"type": "*string"}
+ },
+ "order": ["type", "data", "file_id", "path"]
+ },
+ "EnvironmentFileList": {
+ "sources": ["#/components/schemas/EnvironmentFileListResource"],
+ "order": ["object", "data", "next", "has_more"]
+ },
+ "EnvironmentInfo": {
+ "sources": ["#/components/schemas/PublicEnvironmentResource"],
+ "order": ["id", "object", "type", "status", "files", "plugins", "skills"]
+ },
+ "EnvironmentNetwork": {
+ "sources": ["#/components/schemas/NetworkPolicyResource"],
+ "order": ["access", "allowed_domains"]
+ },
+ "EnvironmentNetworkInput": {
+ "sources": ["#/components/schemas/NetworkPolicyParam"],
+ "order": ["access", "allowed_domains"]
+ },
+ "EnvironmentPackages": {
+ "exclude": ["system"],
+ "sources": ["#/components/schemas/EnvironmentPackagesParam"],
+ "fields": {
+ "npm": {"omit": false},
+ "python": {"omit": false}
+ },
+ "order": ["npm", "python"]
+ },
+ "EnvironmentPackagesInput": {
+ "exclude": ["system"],
+ "sources": ["#/components/schemas/EnvironmentPackagesParam"],
+ "order": ["npm", "python"]
+ },
+ "EnvironmentPackagesResponse": {
+ "sources": ["#/components/schemas/EnvironmentPackagesResource"],
+ "order": ["npm", "python", "system"]
+ },
+ "EnvironmentTemplate": {
+ "sources": ["#/components/schemas/EnvironmentTemplateResource"],
+ "order": ["id", "object", "name", "created_at", "updated_at", "capability_directories", "network", "packages", "files", "plugins", "skills"]
+ },
+ "EnvironmentTemplateDeleted": {
+ "sources": ["#/components/schemas/DeletedEnvironmentTemplateResource"],
+ "order": ["id", "object", "deleted"]
+ },
+ "EnvironmentTemplateList": {
+ "sources": ["#/components/schemas/EnvironmentTemplateListResource"],
+ "order": ["object", "data", "has_more", "first_id", "last_id"]
+ },
+ "EnvironmentTemplateRequest": {
+ "sources": ["#/components/schemas/CreateEnvironmentTemplateParams"],
+ "fields": {
+ "network": {"type": "*EnvironmentNetworkInput"},
+ "files": {"type": "[]json.RawMessage"},
+ "packages": {"type": "*EnvironmentPackagesInput"}
+ },
+ "order": ["name", "network", "capability_directories", "env", "files", "packages", "plugins", "skills", "setup_commands"]
+ },
+ "ErrorResponse": {
+ "sources": ["#/components/schemas/ErrorResponse-2"],
+ "fields": {"error": {"type": "APIError"}},
+ "order": ["error"]
+ },
+ "FunctionCallAction": {
+ "sources": ["#/components/schemas/SessionRequiredActionResourceFunctionCall"],
+ "fields": {
+ "arguments": {"type": "any"}
+ },
+ "order": ["arguments", "call_id", "name", "turn_id", "type"]
+ },
+ "FunctionToolInput": {
+ "sources": ["#/components/schemas/AgentToolConfigParamFunction"],
+ "fields": {
+ "name": {"type": "*string"},
+ "description": {"type": "*string"},
+ "parameters": {"type": "json.RawMessage"},
+ "defer_loading": {"type": "json.RawMessage"}
+ },
+ "order": ["type", "name", "description", "parameters", "defer_loading"]
+ },
+ "InlineAgent": {
+ "sources": ["#/components/schemas/SessionAgentConfigParam"],
+ "fields": {
+ "x_agents_core": {"type": "*AgentsCore"},
+ "reasoning": {"type": "*Reasoning"},
+ "text": {"type": "*SavedAgentTextInput"}
+ },
+ "order": ["x_agents_core", "model", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"]
+ },
+ "InputContent": {
+ "sources": ["#/components/schemas/InputContentParam"],
+ "order": ["type", "text", "image_url"]
+ },
+ "InputMessage": {
+ "sources": ["#/components/schemas/InputMessageParam"],
+ "fields": {
+ "type": {"type": "string"}
+ },
+ "order": ["type", "role", "content"]
+ },
+ "InputTokenDetails": {
+ "sources": ["#/components/schemas/InputTokensDetailsResource"],
+ "order": ["cached_tokens"]
+ },
+ "Item": {
+ "sources": ["#/components/schemas/SessionTurnItemResource"],
+ "fields": {
+ "id": {"type": "string"},
+ "status": {"type": "string", "omit": false},
+ "role": {"type": "string"},
+ "phase": {"type": "string"},
+ "content": {"type": "[]ItemContent"},
+ "command": {"type": "string"},
+ "name": {"type": "string"},
+ "call_id": {"type": "string"},
+ "server_label": {"type": "string"},
+ "arguments": {"type": "any"},
+ "output": {"type": "any"},
+ "error": {"type": "any"},
+ "action": {"type": "*WebSearchAction"},
+ "agent_id": {"type": "string"},
+ "sender_agent_id": {"type": "string"},
+ "recipient_agent_id": {"type": "string"}
+ },
+ "order": ["id", "turn_id", "type", "status", "role", "phase", "content", "command", "cwd", "duration_ms", "exit_code", "name", "call_id", "server_label", "arguments", "output", "error", "action", "agent_id", "sender_agent_id", "recipient_agent_id", "recipient_agent_ids", "model", "reasoning_effort", "summary"]
+ },
+ "ItemContent": {
+ "sources": ["#/components/schemas/MessageContentResource", "#/components/schemas/EncryptedContentResource"],
+ "fields": {
+ "image_url": {"type": "string"}
+ },
+ "order": ["type", "text", "image_url", "encrypted_content"]
+ },
+ "ItemList": {
+ "sources": ["#/components/schemas/SessionItemListResource"],
+ "order": ["object", "first_id", "last_id", "data", "has_more"]
+ },
+ "MCPHTTPTransport": {
+ "sources": ["#/components/schemas/PersistedMcpTransportConfigParamHttp"],
+ "fields": {
+ "headers": {"type": "*map[string]string"}
+ },
+ "order": ["type", "server_url", "headers"]
+ },
+ "MCPTool": {
+ "sources": ["#/components/schemas/AgentToolResourceMcp"],
+ "fields": {
+ "transport": {"type": "MCPHTTPTransport"},
+ "allowed_tools": {"type": "*[]string"}
+ },
+ "order": ["type", "server_label", "transport", "allowed_tools", "connection_origin", "credential_id", "request_metadata", "required"]
+ },
+ "MCPToolInput": {
+ "sources": ["#/components/schemas/AgentToolConfigParamMcp"],
+ "fields": {
+ "server_label": {"type": "*string"},
+ "allowed_tools": {"type": "json.RawMessage", "omit": false},
+ "connection_origin": {"omit": false},
+ "credential_id": {"omit": false},
+ "request_metadata": {"type": "json.RawMessage", "omit": false},
+ "required": {"type": "json.RawMessage", "omit": false}
+ },
+ "order": ["type", "server_label", "transport", "allowed_tools", "connection_origin", "credential_id", "request_metadata", "required"]
+ },
+ "MultiAgentConfig": {
+ "sources": ["#/components/schemas/MultiAgentConfigResource"],
+ "fields": {
+ "max_concurrent_subagents": {"type": "*int"}
+ },
+ "order": ["enabled", "max_concurrent_subagents"]
+ },
+ "OAuthCredentialRefresh": {
+ "sources": ["#/components/schemas/McpOauthRefreshResource"],
+ "order": ["client_id", "token_endpoint", "token_endpoint_auth", "resource", "scope"]
+ },
+ "OAuthCredentialRefreshInput": {
+ "sources": ["#/components/schemas/CreateMcpOauthRefreshParam"],
+ "fields": {
+ "client_id": {"type": "*string"},
+ "refresh_token": {"type": "*string"},
+ "token_endpoint": {"type": "*string"},
+ "token_endpoint_auth": {"type": "*OAuthEndpointAuthInput"}
+ },
+ "order": ["client_id", "refresh_token", "token_endpoint", "token_endpoint_auth", "resource", "scope"]
+ },
+ "OAuthCredentialRefreshReplacement": {
+ "sources": ["#/components/schemas/RotateMcpOauthRefreshParam"],
+ "fields": {
+ "scope": {"type": "json.RawMessage"},
+ "token_endpoint_auth": {"type": "*OAuthEndpointAuthReplacement"}
+ },
+ "order": ["refresh_token", "scope", "token_endpoint_auth"]
+ },
+ "OAuthEndpointAuth": {
+ "sources": ["#/components/schemas/McpOauthTokenEndpointAuthResource"],
+ "order": ["type"]
+ },
+ "OAuthEndpointAuthInput": {
+ "sources": ["#/components/schemas/CreateMcpOauthTokenEndpointAuthParam"],
+ "order": ["type", "client_secret"]
+ },
+ "OAuthEndpointAuthReplacement": {
+ "sources": ["#/components/schemas/RotateMcpOauthTokenEndpointAuthParam"],
+ "order": ["type", "client_secret"]
+ },
+ "OutputTokenDetails": {
+ "sources": ["#/components/schemas/OutputTokensDetailsResource"],
+ "order": ["reasoning_tokens"]
+ },
+ "Reasoning": {
+ "sources": ["#/components/schemas/ReasoningParam"],
+ "order": ["effort", "summary"]
+ },
+ "ReasoningItem": {
+ "sources": ["#/components/schemas/ReasoningItemResource"],
+ "order": ["id", "turn_id", "type", "status", "summary"]
+ },
+ "RequiredAction": {
+ "sources": ["#/components/schemas/SessionRequiredActionResource"],
+ "fields": {
+ "arguments": {"type": "any"},
+ "call_id": {"type": "string"},
+ "name": {"type": "string"},
+ "turn_id": {"type": "string"},
+ "environment_id": {"type": "string"}
+ },
+ "order": ["type", "arguments", "call_id", "name", "turn_id", "environment_id"]
+ },
+ "SavedAgent": {
+ "sources": ["#/components/schemas/AgentResource"],
+ "embed": {"SavedAgentConfiguration": ["x_agents_core", "model", "name", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"]},
+ "order": ["id", "object", "metadata", "created_at", "updated_at"]
+ },
+ "SavedAgentConfiguration": {
+ "sources": ["#/components/schemas/AgentResource"],
+ "fields": {
+ "x_agents_core": {"type": "*SavedAgentCore"},
+ "reasoning": {"type": "Reasoning"}
+ },
+ "exclude": ["id", "object", "created_at", "updated_at", "metadata"],
+ "order": ["x_agents_core", "model", "name", "instructions", "multi_agent", "reasoning", "service_tier", "text", "tools"]
+ },
+ "SavedAgentList": {
+ "sources": ["#/components/schemas/AgentListResource"],
+ "order": ["object", "data", "has_more", "first_id", "last_id"]
+ },
+ "SavedAgentText": {
+ "sources": ["#/components/schemas/TextResource"],
+ "order": ["format", "verbosity"]
+ },
+ "SavedAgentTextFormat": {
+ "sources": ["#/components/schemas/TextFormatResource"],
+ "fields": {
+ "schema": {"type": "json.RawMessage"}
+ },
+ "order": ["type", "schema"]
+ },
+ "SavedAgentTextInput": {
+ "sources": ["#/components/schemas/TextParam"],
+ "order": ["format", "verbosity"]
+ },
+ "SendSubagentInputCallItem": {
+ "sources": ["#/components/schemas/SendSubagentInputCallItemResource"],
+ "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_id", "content"]
+ },
+ "Session": {
+ "sources": ["#/components/schemas/SessionResource"],
+ "fields": {
+ "x_agents_core": {"type": "*SessionCore"},
+ "usage": {"type": "*TokenUsage"}
+ },
+ "order": ["x_agents_core", "id", "agent", "created_at", "environment", "error", "last_active_at", "metadata", "object", "required_actions", "status", "usage", "vault_ids"]
+ },
+ "SessionArtifact": {
+ "sources": ["#/components/schemas/SessionArtifactResource"],
+ "order": ["id", "created_at", "environment_id", "object", "path", "session_id", "size_bytes", "turn_id"]
+ },
+ "SessionArtifactDeleted": {
+ "sources": ["#/components/schemas/DeletedSessionArtifactResource"],
+ "order": ["id", "object", "deleted"]
+ },
+ "SessionArtifactList": {
+ "sources": ["#/components/schemas/SessionArtifactListResource"],
+ "order": ["object", "first_id", "last_id", "data", "has_more"]
+ },
+ "SessionDeleted": {
+ "sources": ["#/components/schemas/DeletedSessionResource"],
+ "order": ["id", "deleted", "object"]
+ },
+ "SessionEnvironment": {
+ "sources": ["#/components/schemas/EnvironmentResource"],
+ "fields": {
+ "id": {"type": "string"},
+ "capability_directories": {"type": "*[]string"},
+ "remote_url": {"type": "string"},
+ "workspace_directory": {"type": "string"},
+ "files": {"type": "*[]json.RawMessage"},
+ "plugins": {"type": "*[]json.RawMessage"},
+ "skills": {"type": "*[]json.RawMessage"}
+ },
+ "order": ["type", "id", "capability_directories", "remote_url", "workspace_directory", "network", "packages", "files", "plugins", "skills"]
+ },
+ "SessionEnvironmentState": {
+ "sources": ["#/components/schemas/SessionEnvironmentStateResource"],
+ "fields": {
+ "error": {"type": "*StreamError"}
+ },
+ "order": ["id", "type", "status", "error"]
+ },
+ "SessionEvent": {
+ "sources": ["#/components/schemas/SessionEvent"],
+ "fields": {
+ "subagent": {"type": "*Subagent"},
+ "session_id": {"type": "string"},
+ "turn_id": {"type": "string"},
+ "session": {"type": "*Session"},
+ "turn": {"type": "*Turn"},
+ "item": {"type": "*Item"},
+ "item_id": {"type": "string"},
+ "output_index": {"type": "*int32"},
+ "content_index": {"type": "*int"},
+ "part": {"type": "*ItemContent"},
+ "usage": {"type": "*TokenUsage"}
+ },
+ "order": ["subagent", "type", "event_id", "session_id", "turn_id", "session", "turn", "item", "item_id", "output_index", "content_index", "part", "delta", "text", "error", "environment", "usage"]
+ },
+ "SessionInput": {
+ "sources": ["#/components/schemas/SessionInputParam"],
+ "fields": {
+ "call_id": {"type": "string"},
+ "turn_id": {"type": "string"},
+ "error": {"type": "json.RawMessage"},
+ "output": {"type": "any"}
+ },
+ "order": ["type", "input", "call_id", "turn_id", "success", "error", "output"]
+ },
+ "SessionList": {
+ "sources": ["#/components/schemas/SessionListResource"],
+ "order": ["object", "first_id", "last_id", "data", "has_more"]
+ },
+ "Skill": {
+ "sources": ["#/components/schemas/SkillResource"],
+ "order": ["id", "object", "created_at", "name", "description", "default_version", "latest_version"]
+ },
+ "SkillDeleted": {
+ "sources": ["#/components/schemas/DeletedSkillResource"],
+ "order": ["id", "object", "deleted"]
+ },
+ "SkillList": {
+ "sources": ["#/components/schemas/SkillListResource"],
+ "order": ["object", "data", "first_id", "last_id", "has_more"]
+ },
+ "SkillUpdateRequest": {
+ "sources": ["#/components/schemas/SetDefaultSkillVersionBody"],
+ "order": ["default_version"]
+ },
+ "SkillVersion": {
+ "sources": ["#/components/schemas/SkillVersionResource"],
+ "order": ["id", "object", "created_at", "skill_id", "version", "name", "description"]
+ },
+ "SkillVersionDeleted": {
+ "sources": ["#/components/schemas/DeletedSkillVersionResource"],
+ "order": ["id", "object", "version", "deleted"]
+ },
+ "SkillVersionList": {
+ "sources": ["#/components/schemas/SkillVersionListResource"],
+ "order": ["object", "data", "first_id", "last_id", "has_more"]
+ },
+ "SourceFile": {
+ "sources": ["#/components/schemas/OpenAIFile"],
+ "fields": {
+ "expires_at": {"omit": false},
+ "status_details": {"omit": false}
+ },
+ "order": ["id", "object", "bytes", "created_at", "filename", "purpose", "status", "expires_at", "status_details"]
+ },
+ "SourceFileDeleted": {
+ "sources": ["#/components/schemas/DeleteFileResponse"],
+ "order": ["id", "object", "deleted"]
+ },
+ "SourceFileList": {
+ "sources": ["#/components/schemas/ListFilesResponse"],
+ "fields": {
+ "first_id": {"type": "*string"},
+ "last_id": {"type": "*string"}
+ },
+ "order": ["object", "data", "has_more", "first_id", "last_id"]
+ },
+ "StreamError": {
+ "sources": ["#/components/schemas/SessionErrorResource"],
+ "fields": {
+ "code": {"type": "string"},
+ "param": {"omit": true}
+ },
+ "order": ["code", "type", "message", "param"]
+ },
+ "Subagent": {
+ "sources": ["#/components/schemas/SubagentResource"],
+ "order": ["id", "object", "session_id", "parent_agent_id", "opened_at", "closed_at", "name", "instructions", "status"]
+ },
+ "SubagentControlCallItem": {
+ "sources": ["#/components/schemas/ResumeSubagentCallItemResource", "#/components/schemas/InterruptSubagentCallItemResource", "#/components/schemas/CloseSubagentCallItemResource"],
+ "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_id"]
+ },
+ "SubagentList": {
+ "sources": ["#/paths/~1agents~1sessions~1{session_id}~1subagents/get/responses/200/content/application~1json/schema"],
+ "order": ["object", "first_id", "last_id", "data", "has_more"]
+ },
+ "SummaryText": {
+ "sources": ["#/components/schemas/SummaryTextResource"],
+ "order": ["type", "text"]
+ },
+ "TextConfig": {
+ "sources": ["#/components/schemas/TextResource"],
+ "order": ["format", "verbosity"],
+ "fields": {
+ "format": {"type": "TextFormat"}
+ }
+ },
+ "TextConfigInput": {
+ "sources": ["#/components/schemas/TextParam"],
+ "fields": {
+ "format": {"type": "*TextFormat"}
+ },
+ "order": ["format", "verbosity"]
+ },
+ "TextFormat": {
+ "sources": ["#/components/schemas/TextFormatResource"],
+ "fields": {
+ "schema": {"type": "json.RawMessage"}
+ },
+ "order": ["type", "schema"]
+ },
+ "TokenUsage": {
+ "sources": ["#/components/schemas/TokenUsageResource"],
+ "order": ["input_tokens", "input_tokens_details", "output_tokens", "output_tokens_details", "total_tokens"]
+ },
+ "Turn": {
+ "sources": ["#/components/schemas/TurnResource"],
+ "fields": {
+ "error": {"type": "*TurnError"},
+ "usage": {"type": "*TokenUsage"}
+ },
+ "order": ["id", "agent_id", "subagent_id", "session_id", "object", "status", "created_at", "started_at", "completed_at", "error", "usage"]
+ },
+ "TurnError": {
+ "sources": ["#/components/schemas/SessionTurnErrorResource"],
+ "order": ["code", "message"]
+ },
+ "TurnList": {
+ "sources": ["#/components/schemas/SessionTurnListResource"],
+ "order": ["object", "first_id", "last_id", "data", "has_more"]
+ },
+ "UpdateAgentRequest": {
+ "sources": ["#/components/schemas/UpdateAgentParams"],
+ "fields": {
+ "x_agents_core": {"type": "*SavedAgentCoreInput"},
+ "metadata": {"type": "map[string]*string"},
+ "reasoning": {"type": "*Reasoning"},
+ "text": {"type": "*SavedAgentTextInput"}
+ },
+ "order": ["x_agents_core", "model", "name", "instructions", "metadata", "multi_agent", "reasoning", "service_tier", "text", "tools"]
+ },
+ "UpdateCredentialRequest": {
+ "sources": ["#/components/schemas/RotateVaultCredentialParams"],
+ "fields": {
+ "auth": {"type": "*CredentialAuthReplacement"}
+ },
+ "order": ["auth"]
+ },
+ "UpdateSessionRequest": {
+ "sources": ["#/components/schemas/UpdateAgentSessionParams"],
+ "fields": {
+ "metadata": {"omit": false}
+ },
+ "order": ["metadata"]
+ },
+ "Vault": {
+ "sources": ["#/components/schemas/VaultResource"],
+ "order": ["id", "object", "created_at", "name", "metadata"]
+ },
+ "VaultDeleted": {
+ "sources": ["#/components/schemas/DeletedVaultResource"],
+ "order": ["id", "deleted", "object"]
+ },
+ "VaultList": {
+ "sources": ["#/components/schemas/VaultListResource"],
+ "order": ["object", "data", "has_more", "first_id", "last_id"]
+ },
+ "WaitForSubagentsCallItem": {
+ "sources": ["#/components/schemas/WaitForSubagentsCallItemResource"],
+ "order": ["id", "turn_id", "type", "status", "sender_agent_id", "recipient_agent_ids"]
+ },
+ "WebSearchAction": {
+ "marshal_union": true,
+ "sources": ["#/components/schemas/WebSearchActionResource"],
+ "order": ["type", "query", "queries", "url", "pattern"]
+ },
+ "reasoningResponse": {
+ "sources": ["#/components/schemas/ReasoningResource"],
+ "order": ["effort", "summary"]
+ },
+ "sessionError": {
+ "sources": ["#/components/schemas/SessionErrorResource"],
+ "fields": {
+ "code": {"type": "string"}
+ },
+ "order": ["code", "type", "message", "param"]
+ }
+}
diff --git a/contracts/agents-api/index.md b/contracts/agents-api/index.md
index be6bed469..87dd67793 100644
--- a/contracts/agents-api/index.md
+++ b/contracts/agents-api/index.md
@@ -9,10 +9,18 @@ Core targets the complete OpenAI Agents API as pinned below ([public API rule](h
| File | Contents |
| --- | --- |
| [upstream.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream.json) | The pin: [openai-python](https://github.com/openai/openai-python/tree/d7c41efee1b0802b79f3f88a678ef2052b06e9ce/src/openai/resources/beta/agents) 3.13.0 at commit `d7c41ef`, resources under `beta/agents`, Beta header `agents=v1` |
-| [upstream-routes.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-routes.json), [upstream-fields.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-fields.json) | The 58 method and path pairs and their official fields: 42 operations under `beta/agents`, 5 Files and 11 Skills operations. `scripts/extract-agents-api-upstream.py` extracts them from the pinned SDK; run it with that SDK installed |
-| [openapi.yaml](./openapi.yaml) | Core's public schema, generated by `make openapi` from the route annotations in `services/core/internal/api/` and the wire types in [`v1/`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/contracts/agents-api/v1) |
+| [upstream/openapi.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream/openapi.json) | Unmodified official OpenAPI 3.1 at commit `046a2a0f325bf11f97966f2729219f27281ba71e`, published on 2026-09-10. Its 58 Agents, Vaults, Files and Skills operations match the pinned SDK route set. `upstream.json` records the SHA-256 checksum |
+| [upstream-routes.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/upstream-routes.json) | The normalized method/path inventory generated from the official schema |
+| [openapi.yaml](./openapi.yaml) | The official public contract with Core's `x_agents_core` extension on Agent and Session request/response objects |
+| [go-bindings.json](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/contracts/agents-api/go-bindings.json) | Go names, field representations, encoding order and stored projections; it does not define official field membership, enums or constraints |
-Contract tests hold Core to the pin: the router and `openapi.yaml` serve exactly the pinned routes (`services/core/internal/api/routing_test.go`, `v1/upstream_contract_test.go`), every query parameter and field is official, and Core-only fields sit only inside `x_agents_core` on Agents and Sessions. Swagger 2.0 cannot express string-or-array unions, so `openapi.yaml` leaves Session `input` and function-result `output` unconstrained; the pinned types and Core's validation define them. Operations and fields newer than the pin wait for a protocol upgrade.
+Run `make openapi` to regenerate the public Go types, route inventory and all three OpenAPI documents. `scripts/generate-public-api.py` reads the checked-in, checksum-verified official source without network access. It selects Agents, Vaults, Files and Skills and follows their schema references, preserving union types, nullability, required fields and constraints. Core's extension types in `v1/` remain authored in Go and are added to the public schema during generation. The internal `/core/v1` and `/api/v1` documents come from handler annotations. `make check-openapi` checks freshness and the generator; it also runs through `make check-go`.
+
+The public contract is the official API plus Core extensions. Standard fields are generated into `v1/official.gen.go`; `go-bindings.json` controls their Go representation where existing storage or custom JSON encoding requires it. Selected discriminated unions also generate JSON serializers to retain required nullable fields for each variant. Other union serializers, request admission and state transitions remain implementation code. Contract tests verify that the public schema preserves the official definitions, extensions remain in `x_agents_core`, and all documents match registered routes. Official-client and raw HTTP tests verify behavior. Schema generation does not qualify an unimplemented feature; the gaps below still apply. Upstream upgrades update the OpenAPI and SDK pins together after comparison and compatibility tests.
+
+The official source and existing service have these recorded differences: Agents authentication errors can return a null `code`; empty Files pages return null `first_id` and `last_id`; File resources can return null `expires_at` and `status_details`. The source declares those fields non-null. The official-client response validator allows null only for these named fields and otherwise validates OpenAPI 3.1 response schemas. Files and Skills operations omit error responses in the source, so those error bodies use the upstream shared `ErrorResponse` schema. [Wire semantics](./wire-semantics.md) and raw HTTP tests qualify service behavior; the published schema retains the official definitions.
+
+Go input projections exclude `packages.system` to preserve its explicit rejection, recorded below. Generation does not enable an unsupported operation or change stored setup validation.
Evidence for a status comes from the pinned official SDK and raw HTTP against the running service, as [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#compatibility-evidence) requires.
diff --git a/contracts/agents-api/openapi.yaml b/contracts/agents-api/openapi.yaml
index 64c942b2e..1885da9ed 100644
--- a/contracts/agents-api/openapi.yaml
+++ b/contracts/agents-api/openapi.yaml
@@ -1,5429 +1,19444 @@
-basePath: /v1
-definitions:
- v1.APIError:
- properties:
- code:
- type: string
- x-nullable: true
- message:
- type: string
- param:
- type: string
- x-nullable: true
- type:
- type: string
- required:
- - message
- - type
- type: object
- v1.Agent:
- properties:
- id:
- type: string
- instructions:
- type: string
- x-nullable: true
- model:
- type: string
- multi_agent:
- $ref: '#/definitions/v1.MultiAgentConfig'
- name:
- type: string
- x-nullable: true
- reasoning:
- $ref: '#/definitions/v1.Reasoning'
- service_tier:
- enum:
- - auto
- type: string
- text:
- $ref: '#/definitions/v1.TextConfig'
- tools:
- items:
- type: object
- type: array
- x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.AgentsCore'
- x-nullable: true
- required:
- - id
- - model
- - multi_agent
- - reasoning
- - service_tier
- - text
- - tools
- type: object
- v1.AgentContent:
- properties:
- encrypted_content:
- type: string
- text:
- type: string
- type:
- enum:
- - output_text
- - encrypted_content
- type: string
- required:
- - type
- type: object
- v1.AgentDeleted:
- properties:
- deleted:
- enum:
- - true
- type: boolean
- id:
- type: string
- object:
- enum:
- - agent.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.AgentsCore:
- properties:
- harness:
- enum:
- - claude_sdk
- - codex
- - mcode
- type: string
- harness_config:
- type: object
- type: object
- v1.CreateAgentRequest:
- properties:
- instructions:
- type: string
- x-nullable: true
- metadata:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- model:
- type: string
- multi_agent:
- type: object
- x-nullable: true
- name:
- maxLength: 128
- type: string
- x-nullable: true
- reasoning:
- allOf:
- - $ref: '#/definitions/v1.Reasoning'
- x-nullable: true
- service_tier:
- enum:
- - auto
- - default
- - flex
- - priority
- - fast
- type: string
- x-nullable: true
- text:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentTextInput'
- x-nullable: true
- tools:
- items:
- type: object
- type: array
- x-nullable: true
- x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentCoreInput'
- x-nullable: true
- required:
- - model
- type: object
- v1.CreateCredentialRequest:
- properties:
- auth:
- $ref: '#/definitions/v1.CredentialAuthInput'
- name:
- type: string
- required:
- - auth
- - name
- type: object
- v1.CreateEventsRequest:
- properties:
- events:
- items:
- $ref: '#/definitions/v1.SessionInput'
- type: array
- required:
- - events
- type: object
- v1.CreateSessionRequest:
- properties:
- agent:
- $ref: '#/definitions/v1.InlineAgent'
- agent_id:
- type: string
- environment:
- $ref: '#/definitions/v1.Environment'
- input:
- description: |-
- Input accepts a string or an ordered array of user InputMessage objects.
- Required for none and streamed creation outside self_hosted; otherwise optional.
- x-nullable: true
- metadata:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- stream:
- default: false
- type: boolean
- vault_ids:
- items:
- type: string
- type: array
- x_agents_core:
- $ref: '#/definitions/v1.SessionExecutionInput'
- required:
- - environment
- type: object
- v1.CreateVaultRequest:
- properties:
- metadata:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- name:
- type: string
- type: object
- v1.Credential:
- properties:
- auth:
- $ref: '#/definitions/v1.CredentialAuth'
- created_at:
- type: integer
- id:
- type: string
- name:
- type: string
- object:
- enum:
- - vault.credential
- type: string
- updated_at:
- type: integer
- vault_id:
- type: string
- required:
- - auth
- - created_at
- - id
- - name
- - object
- - updated_at
- - vault_id
- type: object
- v1.CredentialAuth:
- properties:
- expires_at:
- type: string
- x-nullable: true
- mcp_server_url:
- type: string
- refresh:
- allOf:
- - $ref: '#/definitions/v1.OAuthCredentialRefresh'
- x-nullable: true
- type:
- enum:
- - static_bearer
- - mcp_oauth
- type: string
- required:
- - mcp_server_url
- - type
- type: object
- v1.CredentialAuthInput:
- properties:
- access_token:
- minLength: 1
- type: string
- expires_at:
- type: string
- x-nullable: true
- mcp_server_url:
- type: string
- refresh:
- allOf:
- - $ref: '#/definitions/v1.OAuthCredentialRefreshInput'
- x-nullable: true
- token:
- minLength: 1
- type: string
- type:
- enum:
- - static_bearer
- - mcp_oauth
- type: string
- required:
- - mcp_server_url
- - type
- type: object
- v1.CredentialAuthReplacement:
- properties:
- access_token:
- minLength: 1
- type: string
- x-nullable: true
- expires_at:
- type: string
- x-nullable: true
- refresh:
- allOf:
- - $ref: '#/definitions/v1.OAuthCredentialRefreshReplacement'
- x-nullable: true
- token:
- minLength: 1
- type: string
- type:
- enum:
- - static_bearer
- - mcp_oauth
- type: string
- required:
- - type
- type: object
- v1.CredentialDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - vault.credential.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.CredentialList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Credential'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.Environment:
- properties:
- capability_directories:
- items:
- type: string
- type: array
- x-nullable: true
- env:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- environment_template_id:
- type: string
- files:
- items:
- type: object
- type: array
- x-nullable: true
- network:
- allOf:
- - $ref: '#/definitions/v1.EnvironmentNetworkInput'
- x-nullable: true
- packages:
- allOf:
- - $ref: '#/definitions/v1.EnvironmentPackages'
- x-nullable: true
- plugins:
- items:
- type: object
- type: array
- x-nullable: true
- setup_commands:
- items:
- type: object
- type: array
- x-nullable: true
- skills:
- items:
- type: object
- type: array
- x-nullable: true
- type:
- enum:
- - none
- - self_hosted
- - openai_hosted
- type: string
- workspace_directory:
- type: string
- required:
- - type
- type: object
- v1.EnvironmentFile:
- properties:
- environment_id:
- type: string
- object:
- enum:
- - agent.environment.file
- type: string
- path:
- type: string
- size_bytes:
- minimum: 0
- type: integer
- required:
- - environment_id
- - object
- - path
- - size_bytes
- type: object
- v1.EnvironmentFileCreateRequest:
- properties:
- data:
- type: string
- file_id:
- type: string
- path:
- type: string
- type:
- enum:
- - inline
- - file_id
- type: string
- required:
- - path
- - type
- type: object
- v1.EnvironmentFileList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.EnvironmentFile'
- type: array
- has_more:
- type: boolean
- next:
- type: string
- x-nullable: true
- object:
- enum:
- - page
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.EnvironmentInfo:
- properties:
- files:
- items:
- type: object
- type: array
- id:
- type: string
- object:
- enum:
- - agent.environment
- type: string
- plugins:
- items:
- type: object
- type: array
- skills:
- items:
- type: object
- type: array
- status:
- enum:
- - pending
- - connected
- - disconnected
- - expired
- - failed
- type: string
- type:
- enum:
- - openai_hosted
- - self_hosted
- type: string
- required:
- - files
- - id
- - object
- - plugins
- - skills
- - status
- - type
- type: object
- v1.EnvironmentInstallation:
- properties:
- commands:
- additionalProperties:
- type: string
- type: object
- expires_at:
- type: integer
- message:
- type: string
- status:
- enum:
- - available
- - unavailable
- type: string
- version:
- type: string
- type: object
- v1.EnvironmentNetwork:
- properties:
- access:
- enum:
- - enabled
- - disabled
- - restricted
- type: string
- allowed_domains:
- items:
- type: string
- type: array
- required:
- - access
- - allowed_domains
- type: object
- v1.EnvironmentNetworkInput:
- properties:
- access:
- enum:
- - enabled
- - disabled
- - restricted
- type: string
- allowed_domains:
- items:
- type: string
- type: array
- x-nullable: true
- required:
- - access
- type: object
- v1.EnvironmentPackages:
- properties:
- npm:
- items:
- type: string
- type: array
- python:
- items:
- type: string
- type: array
- required:
- - npm
- - python
- type: object
- v1.EnvironmentPackagesInput:
- properties:
- npm:
- items:
- type: string
- type: array
- x-nullable: true
- python:
- items:
- type: string
- type: array
- x-nullable: true
- type: object
- v1.EnvironmentPackagesResponse:
- properties:
- npm:
- items:
- type: string
- type: array
- python:
- items:
- type: string
- type: array
- system:
- items:
- type: string
- type: array
- required:
- - npm
- - python
- - system
- type: object
- v1.EnvironmentTemplate:
- properties:
- capability_directories:
- items:
- type: string
- type: array
- created_at:
- type: integer
- files:
- items:
- type: object
- type: array
- id:
- type: string
- name:
- type: string
- x-nullable: true
- network:
- $ref: '#/definitions/v1.EnvironmentNetwork'
- object:
- enum:
- - agent.environment.template
- type: string
- packages:
- $ref: '#/definitions/v1.EnvironmentPackagesResponse'
- plugins:
- items:
- type: object
- type: array
- skills:
- items:
- type: object
- type: array
- updated_at:
- type: integer
- required:
- - capability_directories
- - created_at
- - files
- - id
- - network
- - object
- - packages
- - plugins
- - skills
- - updated_at
- type: object
- v1.EnvironmentTemplateDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - agent.environment.template.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.EnvironmentTemplateList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.EnvironmentTemplate'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.EnvironmentTemplateRequest:
- properties:
- capability_directories:
- items:
- type: string
- type: array
- x-nullable: true
- env:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- files:
- items:
- type: object
- type: array
- x-nullable: true
- name:
- type: string
- x-nullable: true
- network:
- allOf:
- - $ref: '#/definitions/v1.EnvironmentNetworkInput'
- x-nullable: true
- packages:
- allOf:
- - $ref: '#/definitions/v1.EnvironmentPackagesInput'
- x-nullable: true
- plugins:
- items:
- type: object
- type: array
- x-nullable: true
- setup_commands:
- items:
- type: object
- type: array
- x-nullable: true
- skills:
- items:
- type: object
- type: array
- x-nullable: true
- type: object
- v1.ErrorResponse:
- properties:
- error:
- $ref: '#/definitions/v1.APIError'
- required:
- - error
- type: object
- v1.InlineAgent:
- properties:
- instructions:
- type: string
- x-nullable: true
- model:
- type: string
- multi_agent:
- type: object
- x-nullable: true
- reasoning:
- allOf:
- - $ref: '#/definitions/v1.Reasoning'
- x-nullable: true
- service_tier:
- enum:
- - auto
- - default
- - flex
- - priority
- - fast
- type: string
- x-nullable: true
- text:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentTextInput'
- x-nullable: true
- tools:
- items:
- type: object
- type: array
- x-nullable: true
- x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.AgentsCore'
- x-nullable: true
- type: object
- v1.InputContent:
- properties:
- image_url:
- type: string
- text:
- type: string
- type:
- enum:
- - input_text
- - input_image
- type: string
- required:
- - type
- type: object
- v1.InputMessage:
- properties:
- content:
- items:
- $ref: '#/definitions/v1.InputContent'
- type: array
- role:
- enum:
- - user
- type: string
- type:
- enum:
- - message
- type: string
- required:
- - content
- - role
- type: object
- v1.InputTokenDetails:
- properties:
- cached_tokens:
- type: integer
- required:
- - cached_tokens
- type: object
- v1.Item:
- properties:
- action:
- $ref: '#/definitions/v1.WebSearchAction'
- agent_id:
- type: string
- arguments: {}
- call_id:
- type: string
- command:
- type: string
- content:
- items:
- $ref: '#/definitions/v1.ItemContent'
- type: array
- cwd:
- type: string
- duration_ms:
- type: integer
- error: {}
- exit_code:
- type: integer
- id:
- type: string
- model:
- type: string
- name:
- type: string
- output: {}
- phase:
- enum:
- - commentary
- - final_answer
- type: string
- x-nullable: true
- reasoning_effort:
- type: string
- recipient_agent_id:
- type: string
- recipient_agent_ids:
- items:
- type: string
- type: array
- role:
- enum:
- - user
- - assistant
- type: string
- sender_agent_id:
- type: string
- server_label:
- type: string
- status:
- enum:
- - in_progress
- - completed
- - failed
- - incomplete
- type: string
- summary:
- items:
- $ref: '#/definitions/v1.SummaryText'
- type: array
- turn_id:
- type: string
- type:
- enum:
- - message
- - command_execution
- - mcp_call
- - function_call
- - function_call_output
- - web_search_call
- - reasoning
- - agent_message
- - create_subagent_call
- - send_subagent_input_call
- - resume_subagent_call
- - wait_for_subagents_call
- - interrupt_subagent_call
- - close_subagent_call
- type: string
- required:
- - id
- - turn_id
- - type
- type: object
- v1.ItemContent:
- properties:
- encrypted_content:
- type: string
- image_url:
- type: string
- text:
- type: string
- type:
- enum:
- - input_text
- - output_text
- - input_image
- - encrypted_content
- type: string
- required:
- - type
- type: object
- v1.ItemList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Item'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.ModelProviderInput:
- properties:
- api_key:
- type: string
- base_url:
- type: string
- context_window:
- type: integer
- max_output_tokens:
- type: integer
- protocol:
- enum:
- - anthropic
- - responses
- - chat_completions
- type: string
- required:
- - api_key
- - base_url
- - protocol
- type: object
- v1.ModelProviderView:
- properties:
- api_key_configured:
- type: boolean
- base_url:
- type: string
- context_window:
- type: integer
- max_output_tokens:
- type: integer
- protocol:
- enum:
- - anthropic
- - responses
- - chat_completions
- type: string
- required:
- - api_key_configured
- - base_url
- - protocol
- type: object
- v1.MultiAgentConfig:
- properties:
- enabled:
- type: boolean
- max_concurrent_subagents:
- type: integer
- x-nullable: true
- required:
- - enabled
- type: object
- v1.OAuthCredentialRefresh:
- properties:
- client_id:
- type: string
- resource:
- type: string
- x-nullable: true
- scope:
- type: string
- x-nullable: true
- token_endpoint:
- type: string
- token_endpoint_auth:
- $ref: '#/definitions/v1.OAuthEndpointAuth'
- required:
- - client_id
- - token_endpoint
- - token_endpoint_auth
- type: object
- v1.OAuthCredentialRefreshInput:
- properties:
- client_id:
- type: string
- refresh_token:
- type: string
- resource:
- type: string
- x-nullable: true
- scope:
- type: string
- x-nullable: true
- token_endpoint:
- type: string
- token_endpoint_auth:
- $ref: '#/definitions/v1.OAuthEndpointAuthInput'
- required:
- - client_id
- - refresh_token
- - token_endpoint
- - token_endpoint_auth
- type: object
- v1.OAuthCredentialRefreshReplacement:
- properties:
- refresh_token:
- type: string
- x-nullable: true
- scope:
- type: string
- x-nullable: true
- token_endpoint_auth:
- allOf:
- - $ref: '#/definitions/v1.OAuthEndpointAuthReplacement'
- x-nullable: true
- type: object
- v1.OAuthEndpointAuth:
- properties:
- type:
- enum:
- - none
- - client_secret_basic
- - client_secret_post
- type: string
- required:
- - type
- type: object
- v1.OAuthEndpointAuthInput:
- properties:
- client_secret:
- type: string
- type:
- enum:
- - none
- - client_secret_basic
- - client_secret_post
- type: string
- required:
- - type
- type: object
- v1.OAuthEndpointAuthReplacement:
- properties:
- client_secret:
- type: string
- x-nullable: true
- type:
- enum:
- - client_secret_basic
- - client_secret_post
- type: string
- required:
- - type
- type: object
- v1.OutputTokenDetails:
- properties:
- reasoning_tokens:
- type: integer
- required:
- - reasoning_tokens
- type: object
- v1.Reasoning:
- properties:
- effort:
- type: string
- x-nullable: true
- summary:
- type: string
- x-nullable: true
- type: object
- v1.RequiredAction:
- properties:
- arguments: {}
- call_id:
- type: string
- environment_id:
- type: string
- name:
- type: string
- turn_id:
- type: string
- type:
- enum:
- - function_call
- - environment_connection
- type: string
- required:
- - type
- type: object
- v1.SavedAgent:
- properties:
- created_at:
- type: integer
- id:
- type: string
- instructions:
- type: string
- x-nullable: true
- metadata:
- additionalProperties:
- type: string
- type: object
- model:
- type: string
- multi_agent:
- $ref: '#/definitions/v1.MultiAgentConfig'
- name:
- type: string
- x-nullable: true
- object:
- enum:
- - agent
- type: string
- reasoning:
- $ref: '#/definitions/v1.Reasoning'
- service_tier:
- enum:
- - auto
- - default
- - flex
- - priority
- - fast
- type: string
- text:
- $ref: '#/definitions/v1.SavedAgentText'
- tools:
- items:
- type: object
- type: array
- updated_at:
- type: integer
- x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentCore'
- x-nullable: true
- required:
- - created_at
- - id
- - metadata
- - model
- - multi_agent
- - object
- - reasoning
- - service_tier
- - text
- - tools
- - updated_at
- type: object
- v1.SavedAgentCore:
- properties:
- harness:
- enum:
- - claude_sdk
- - codex
- - mcode
- type: string
- harness_config:
- type: object
- model_provider:
- $ref: '#/definitions/v1.ModelProviderView'
- type: object
- v1.SavedAgentCoreInput:
- properties:
- harness:
- enum:
- - claude_sdk
- - codex
- - mcode
- type: string
- harness_config:
- type: object
- model_provider:
- allOf:
- - $ref: '#/definitions/v1.ModelProviderInput'
- x-nullable: true
- type: object
- v1.SavedAgentList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.SavedAgent'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.SavedAgentText:
- properties:
- format:
- $ref: '#/definitions/v1.SavedAgentTextFormat'
- verbosity:
- enum:
- - low
- - medium
- - high
- type: string
- required:
- - format
- - verbosity
- type: object
- v1.SavedAgentTextFormat:
- properties:
- schema:
- type: object
- type:
- enum:
- - text
- - json_schema
- type: string
- required:
- - type
- type: object
- v1.SavedAgentTextInput:
- properties:
- format:
- type: object
- x-nullable: true
- verbosity:
- enum:
- - low
- - medium
- - high
- type: string
- x-nullable: true
- type: object
- v1.Session:
- properties:
- agent:
- $ref: '#/definitions/v1.Agent'
- created_at:
- type: integer
- environment:
- $ref: '#/definitions/v1.SessionEnvironment'
- error:
- type: string
- x-nullable: true
- id:
- type: string
- last_active_at:
- type: integer
- metadata:
- additionalProperties:
- type: string
- type: object
- object:
- enum:
- - agent.session
- type: string
- required_actions:
- items:
- $ref: '#/definitions/v1.RequiredAction'
- type: array
- status:
- enum:
- - idle
- - in_progress
- - requires_action
- - failed
- type: string
- usage:
- allOf:
- - $ref: '#/definitions/v1.TokenUsage'
- x-nullable: true
- vault_ids:
- items:
- type: string
- type: array
- x_agents_core:
- $ref: '#/definitions/v1.SessionCore'
- required:
- - agent
- - created_at
- - environment
- - id
- - last_active_at
- - metadata
- - object
- - required_actions
- - status
- - vault_ids
- type: object
- v1.SessionArtifact:
- properties:
- created_at:
- type: integer
- environment_id:
- type: string
- id:
- type: string
- object:
- enum:
- - agent.session.artifact
- type: string
- path:
- type: string
- session_id:
- type: string
- size_bytes:
- type: integer
- turn_id:
- type: string
- required:
- - created_at
- - environment_id
- - id
- - object
- - path
- - session_id
- - size_bytes
- - turn_id
- type: object
- v1.SessionArtifactDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - agent.session.artifact.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.SessionArtifactList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.SessionArtifact'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.SessionCore:
- properties:
- installation:
- $ref: '#/definitions/v1.EnvironmentInstallation'
- type: object
- v1.SessionDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - agent.session.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.SessionEnvironment:
- properties:
- capability_directories:
- items:
- type: string
- type: array
- files:
- items:
- type: object
- type: array
- id:
- type: string
- network:
- $ref: '#/definitions/v1.EnvironmentNetwork'
- packages:
- $ref: '#/definitions/v1.EnvironmentPackagesResponse'
- plugins:
- items:
- type: object
- type: array
- remote_url:
- type: string
- skills:
- items:
- type: object
- type: array
- type:
- enum:
- - none
- - self_hosted
- - openai_hosted
- type: string
- workspace_directory:
- type: string
- required:
- - type
- type: object
- v1.SessionEnvironmentState:
- properties:
- error:
- allOf:
- - $ref: '#/definitions/v1.StreamError'
- x-nullable: true
- id:
- type: string
- status:
- enum:
- - pending
- - ready
- - connected
- - disconnected
- - failed
- type: string
- type:
- type: string
- required:
- - id
- - status
- - type
- type: object
- v1.SessionEvent:
- properties:
- content_index:
- type: integer
- delta:
- type: string
- environment:
- $ref: '#/definitions/v1.SessionEnvironmentState'
- error:
- $ref: '#/definitions/v1.StreamError'
- event_id:
- type: string
- item:
- $ref: '#/definitions/v1.Item'
- item_id:
- type: string
- output_index:
- type: integer
- x-nullable: true
- part:
- $ref: '#/definitions/v1.ItemContent'
- session:
- $ref: '#/definitions/v1.Session'
- session_id:
- type: string
- subagent:
- $ref: '#/definitions/v1.Subagent'
- text:
- type: string
- turn:
- $ref: '#/definitions/v1.Turn'
- turn_id:
- type: string
- type:
- type: string
- usage:
- allOf:
- - $ref: '#/definitions/v1.TokenUsage'
- description: |-
- Usage is present only on terminal Turn events, where it mirrors the Turn
- snapshot and is null when unknown. Other events omit it.
- x-nullable: true
- required:
- - event_id
- - type
- type: object
- v1.SessionExecutionInput:
- properties:
- environment:
- description: Environment supplies placement-independent preparation through
- the Core extension.
- type: object
- harness_config:
- type: object
- model_provider:
- $ref: '#/definitions/v1.ModelProviderInput'
- type: object
- v1.SessionInput:
- properties:
- call_id:
- type: string
- error:
- type: string
- x-nullable: true
- input:
- items:
- $ref: '#/definitions/v1.InputMessage'
- type: array
- output:
- x-nullable: true
- success:
- type: boolean
- turn_id:
- type: string
- type:
- enum:
- - agent.session.input.message
- - agent.session.input.cancel
- - agent.session.input.tool_result
- type: string
- required:
- - type
- type: object
- v1.SessionList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Session'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.Skill:
- properties:
- created_at:
- type: integer
- default_version:
- type: string
- description:
- type: string
- id:
- type: string
- latest_version:
- type: string
- name:
- type: string
- object:
- enum:
- - skill
- type: string
- required:
- - created_at
- - default_version
- - description
- - id
- - latest_version
- - name
- - object
- type: object
- v1.SkillDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - skill.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.SkillList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Skill'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.SkillUpdateRequest:
- properties:
- default_version:
- type: string
- required:
- - default_version
- type: object
- v1.SkillVersion:
- properties:
- created_at:
- type: integer
- description:
- type: string
- id:
- type: string
- name:
- type: string
- object:
- enum:
- - skill.version
- type: string
- skill_id:
- type: string
- version:
- type: string
- required:
- - created_at
- - description
- - id
- - name
- - object
- - skill_id
- - version
- type: object
- v1.SkillVersionDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - skill.version.deleted
- type: string
- version:
- type: string
- required:
- - deleted
- - id
- - object
- - version
- type: object
- v1.SkillVersionList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.SkillVersion'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.SourceFile:
- properties:
- bytes:
- minimum: 0
- type: integer
- created_at:
- type: integer
- expires_at:
- type: integer
- x-nullable: true
- filename:
- type: string
- id:
- type: string
- object:
- enum:
- - file
- type: string
- purpose:
- enum:
- - user_data
- type: string
- status:
- enum:
- - processed
- type: string
- status_details:
- type: string
- x-nullable: true
- required:
- - bytes
- - created_at
- - filename
- - id
- - object
- - purpose
- - status
- type: object
- v1.SourceFileDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - file
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.SourceFileList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.SourceFile'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.StreamError:
- properties:
- code:
- type: string
- message:
- type: string
- param:
- description: |-
- Param is the pinned SessionError field. An error SessionEvent always
- carries it, null when unset; Environment state errors and Core's own
- stream_interrupted frame omit it.
- type: string
- x-nullable: true
- type:
- type: string
- type: object
- v1.Subagent:
- properties:
- closed_at:
- type: integer
- x-nullable: true
- id:
- type: string
- instructions:
- items:
- $ref: '#/definitions/v1.AgentContent'
- type: array
- x-nullable: true
- name:
- type: string
- x-nullable: true
- object:
- enum:
- - agent.session.subagent
- type: string
- opened_at:
- type: integer
- parent_agent_id:
- type: string
- session_id:
- type: string
- status:
- enum:
- - active
- - closed
- type: string
- required:
- - id
- - object
- - opened_at
- - parent_agent_id
- - session_id
- - status
- type: object
- v1.SubagentList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Subagent'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.SummaryText:
- properties:
- text:
- type: string
- type:
- enum:
- - summary_text
- type: string
- required:
- - text
- - type
- type: object
- v1.TextConfig:
- properties:
- format:
- $ref: '#/definitions/v1.TextFormat'
- verbosity:
- enum:
- - low
- - medium
- - high
- type: string
- required:
- - format
- - verbosity
- type: object
- v1.TextFormat:
- properties:
- schema:
- type: object
- type:
- enum:
- - text
- - json_schema
- type: string
- required:
- - type
- type: object
- v1.TokenUsage:
- properties:
- input_tokens:
- type: integer
- input_tokens_details:
- $ref: '#/definitions/v1.InputTokenDetails'
- output_tokens:
- type: integer
- output_tokens_details:
- $ref: '#/definitions/v1.OutputTokenDetails'
- total_tokens:
- type: integer
- required:
- - input_tokens
- - input_tokens_details
- - output_tokens
- - output_tokens_details
- - total_tokens
- type: object
- v1.Turn:
- properties:
- agent_id:
- type: string
- completed_at:
- type: integer
- x-nullable: true
- created_at:
- type: integer
- error:
- allOf:
- - $ref: '#/definitions/v1.TurnError'
- x-nullable: true
- id:
- type: string
- object:
- enum:
- - agent.session.turn
- type: string
- session_id:
- type: string
- started_at:
- type: integer
- x-nullable: true
- status:
- enum:
- - queued
- - in_progress
- - waiting
- - completed
- - failed
- - cancelled
- type: string
- subagent_id:
- type: string
- x-nullable: true
- usage:
- allOf:
- - $ref: '#/definitions/v1.TokenUsage'
- x-nullable: true
- required:
- - agent_id
- - created_at
- - id
- - object
- - session_id
- - status
- type: object
- v1.TurnError:
- properties:
- code:
- enum:
- - context_length_exceeded
- - session_budget_exceeded
- - usage_limit_exceeded
- - rate_limit_exceeded
- - server_overloaded
- - cyber_policy
- - connection_failed
- - server_error
- - authentication_error
- - invalid_request
- - resource_not_found
- - sandbox_error
- - executor_version_incompatible
- - active_turn_not_steerable
- - request_timeout
- - internal_error
- type: string
- message:
- type: string
- required:
- - code
- - message
- type: object
- v1.TurnList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Turn'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.UpdateAgentRequest:
- properties:
- instructions:
- type: string
- x-nullable: true
- metadata:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- model:
- type: string
- multi_agent:
- type: object
- x-nullable: true
- name:
- maxLength: 128
- type: string
- x-nullable: true
- reasoning:
- allOf:
- - $ref: '#/definitions/v1.Reasoning'
- x-nullable: true
- service_tier:
- enum:
- - auto
- - default
- - flex
- - priority
- - fast
- type: string
- x-nullable: true
- text:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentTextInput'
- x-nullable: true
- tools:
- items:
- type: object
- type: array
- x-nullable: true
- x_agents_core:
- allOf:
- - $ref: '#/definitions/v1.SavedAgentCoreInput'
- x-nullable: true
- type: object
- v1.UpdateCredentialRequest:
- properties:
- auth:
- $ref: '#/definitions/v1.CredentialAuthReplacement'
- required:
- - auth
- type: object
- v1.UpdateSessionRequest:
- properties:
- metadata:
- additionalProperties:
- type: string
- type: object
- x-nullable: true
- required:
- - metadata
- type: object
- v1.Vault:
- properties:
- created_at:
- type: integer
- id:
- type: string
- metadata:
- additionalProperties:
- type: string
- type: object
- name:
- type: string
- x-nullable: true
- object:
- enum:
- - vault
- type: string
- required:
- - created_at
- - id
- - metadata
- - object
- type: object
- v1.VaultDeleted:
- properties:
- deleted:
- type: boolean
- id:
- type: string
- object:
- enum:
- - vault.deleted
- type: string
- required:
- - deleted
- - id
- - object
- type: object
- v1.VaultList:
- properties:
- data:
- items:
- $ref: '#/definitions/v1.Vault'
- type: array
- first_id:
- type: string
- x-nullable: true
- has_more:
- type: boolean
- last_id:
- type: string
- x-nullable: true
- object:
- enum:
- - list
- type: string
- required:
- - data
- - has_more
- - object
- type: object
- v1.WebSearchAction:
- properties:
- pattern:
- type: string
- queries:
- items:
- type: string
- type: array
- query:
- type: string
- type:
- enum:
- - search
- - open_page
- - find_in_page
- - other
- type: string
- url:
- type: string
- required:
- - type
- type: object
-info:
- contact: {}
- description: Supported single-Agent execution resources from the pinned openai-python
- beta/agents contract. Bearer keys bind an execution principal to one project;
- optional OpenAI-Organization and OpenAI-Project headers must match that binding.
- license:
- name: Apache 2.0
- url: https://www.apache.org/licenses/LICENSE-2.0.html
- title: OpenAgentCore Agents API
- version: "1"
-paths:
- /agents:
- get:
- description: Lists only the authenticated tenant's saved Agents, independently
- of Sessions. Limit 0 is treated as 1 and larger limits as 100, as observed
- on the hosted service. The local default is 20; exact upstream default/cap
- and empty cursor fields remain unverified. An unknown, malformed or foreign
- after cursor returns not found.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Last Agent ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SavedAgentList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List reusable Agents
- tags:
- - Agents
- post:
- consumes:
- - application/json
- description: 'Persists configuration independently of execution. Names over
- 128 characters and metadata outside 16 string pairs with 64-character keys
- and 512-character values return invalid_request_error with the official param;
- U+0000 in stored strings is rejected as a local storage limit. As on every
- Agents API JSON route, a non-JSON Content-Type, invalid UTF-8, malformed JSON,
- a repeated key at any depth or a non-object root returns invalid_request_error
- with a null param and the official message before other checks; an empty or
- null body is {}. Missing, unknown, wrongly typed or unsupported enum members
- of the pinned configuration shapes (tools, text, reasoning, service_tier,
- multi_agent) return invalid_request_error with the JSON path as param; duplicate
- function names, repeated web_search or tool_search and non-object schema root
- types return it with a null param. Supports model/name/instructions/metadata,
- explicit reasoning and service tiers, multi_agent, text/json_schema, function/tool_search/programmatic_tool_calling/web_search
- and HTTP MCP with nullable credential_id, service origin (omitted or null
- on HTTP transport is saved as service) and boolean required defaulting to
- false. Saving credential_id grants no access: Session admission checks attached
- Vault ownership and destination. MCP allowed_tools preserves null versus empty;
- saved HTTP transport includes empty headers. Model-derived reasoning defaults,
- other MCP variants and public retry conformance remain incomplete. web_search
- saves every pinned mode: omitted or null mode is saved as live and omitted
- or null context_size as medium; allowed_domains preserves null versus empty
- and a present location, including {}, includes all four keys with null for
- omitted ones, as observed officially (req_db41d2f6261b4abfb69465eafe719ab5,
- req_165d53b88445490b9146d8272c54134d). Session execution accepts only explicit
- disabled web_search and disabled programmatic_tool_calling through qualified
- Runtime controls; saved enabled forms reject at Session admission. Session
- execution admits only its supported configuration subset.'
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Reusable Agent configuration
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.CreateAgentRequest'
- produces:
- - application/json
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.SavedAgent'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create a reusable Agent
- tags:
- - Agents
- /agents/{agent_id}:
- delete:
- description: Deletes only the authenticated tenant's saved configuration. Existing
- Session snapshots, history and recorded creation retry identities remain independent.
- Missing and repeated deletion locally return404; exact hosted error and in-flight
- creation/deletion semantics remain unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Agent ID
- in: path
- name: agent_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.AgentDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete a reusable Agent
- tags:
- - Agents
- get:
- description: Reads the saved resource owned by the authenticated tenant, independently
- of execution Sessions.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Agent ID
- in: path
- name: agent_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SavedAgent'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve a reusable Agent
- tags:
- - Agents
- post:
- consumes:
- - application/json
- description: Preserves omitted fields and replaces supplied fields using shared
- saved-configuration validation. Null name/instructions clear; null or empty
- metadata clears all pairs. Name, metadata and configuration validation errors
- return invalid_request_error with the official param, using the Agent create
- rules before the Agent lookup. Existing Session snapshots are unchanged. Empty
- updates advance updated_at without changing saved fields. Nested replacement/null
- defaults, model-derived reasoning and exact hosted error behavior remain incompletely
- verified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Agent ID
- in: path
- name: agent_id
- required: true
- type: string
- - description: Supplied reusable Agent fields
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.UpdateAgentRequest'
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SavedAgent'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Update a reusable Agent
- tags:
- - Agents
- /agents/environments/{environment_id}:
- get:
- description: Returns durable connection status and safe installed metadata for
- supported self_hosted and basic openai_hosted profiles. Initial files expose
- frozen safe metadata without content; Plugin/Skill entries expose only safe
- configured installation metadata. Capability-directory discoveries are not
- added to those arrays. Unsupported installation configurations remain implementation
- gaps. This read does not prepare execution, start compute or require an enabled
- execution worker. Session deletion removes the associated Environment from
- public reads; project-shared read authorization is unchanged. Connection status
- does not prove native readiness or process quiescence.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Environment ID
- in: path
- name: environment_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentInfo'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve an execution Environment
- tags:
- - Environments
- /agents/environments/{environment_id}/files:
- get:
- description: Lists direct regular files in one authorized self_hosted or qualified
- local workspace directory. Local paths use the public /workspace root and
- must be in cleaned form. This partial implementation defaults to the workspace
- root and limit 20; recursive scope and these defaults are not verified upstream
- semantics. A missing path, a regular file or a symbolic link returns an empty
- page; links are never followed. Daemons without a local workspace binding
- use the Claude SDK adapter reader, which keeps 404 for a missing path and
- 503 for a regular file or symbolic link. Well-formed unknown query keys are
- ignored; malformed query encoding and a repeated supported key are rejected.
- Sorts by case-sensitive path components, descending by default. Keep the same
- path, order and limit when using page. Each page rereads the complete bounded
- directory; changed file paths/sizes invalidate continuation locally with 400.
- There is no snapshot guarantee. An openai_hosted Environment that has not
- connected yet returns 400. Truncated or uncertain native results fail with
- 503 without returning a partial page. This read never starts a Turn or admits
- model input. Actual transport disconnect/reconnect events remain observable.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Environment ID
- in: path
- name: environment_id
- required: true
- type: string
- - description: Absolute directory in cleaned form inside /workspace
- in: query
- name: path
- type: string
- - description: Maximum file count; local default 20
- in: query
- maximum: 100
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Case-sensitive path-component order; omit for descending, explicit
- empty values are invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- - description: Opaque continuation token; keep path, order and limit unchanged
- in: query
- name: page
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentFileList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List live Environment files
- tags:
- - Environments
- post:
- consumes:
- - application/json
- description: Uploads standard Base64 bytes to a file beneath /workspace in a
- qualified local Environment and returns 201. Accepts inline bytes or a project-owned
- source file_id through the same write path. Unknown body fields are rejected
- with their name as param. Basic public hosted creation requires explicit managed
- Runtime configuration; an openai_hosted Environment that has not connected
- yet returns 400. Inline data is limited to 5 MiB decoded and a file_id copy
- to 50 MiB. Missing parent directories are created with mode 0700 and the file
- with mode 0600. An existing destination is never replaced; a directory, an
- existing file or a path through a symlink or non-directory returns 400. Idle
- writes exclude execution. Missing receipts return unavailable and retain a
- durable mutation gate without automatic replay. Error/timing parity with upstream
- remains unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Environment ID
- in: path
- name: environment_id
- required: true
- type: string
- - description: Inline bytes or source file ID and absolute workspace path
- in: body
- name: request
- required: true
- schema:
- $ref: '#/definitions/v1.EnvironmentFileCreateRequest'
- produces:
- - application/json
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.EnvironmentFile'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "409":
- description: Conflict
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create an Environment file from inline bytes or a source file
- tags:
- - Environments
- /agents/environments/templates:
- get:
- description: Lists tenant-owned safe template metadata in creation order with
- ID tie-breaking. Defaults to limit 20 and descending order; limit 0 is treated
- as 1 and larger limits as 100. Foreign, missing and malformed cursors return
- the same not found error. Concurrent-page and exact hosted error behavior
- remain unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Previous Template ID
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplateList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List Environment Templates
- tags:
- - Environment Templates
- post:
- consumes:
- - application/json
- description: Saves tenant-owned hosted configuration. Supports nullable name,
- enabled/disabled or exact-domain restricted network, initial inline/file_id
- files, confidential env, ordered setup_commands, npm/Python packages inline/referenced
- Skill ZIPs, Plugin ZIPs and workspace-contained capability directories. Omitted/null
- network defaults to enabled. Restricted network requires 1–100 exact ASCII
- hostnames; other host forms and populated unsupported installations are rejected
- before persistence without echoing input. Network policy rejections return
- invalid_request_error with a null param. System dependencies must be preinstalled
- in the sandbox image or template, or on the host machine; packages.system
- is rejected. No compute is allocated. Exact hosted error/retry semantics remain
- unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Reusable configuration
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplateRequest'
- produces:
- - application/json
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplate'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create an Environment Template
- tags:
- - Environment Templates
- /agents/environments/templates/{environment_template_id}:
- delete:
- description: Deletes the tenant-owned reusable configuration without changing
- or deleting existing Sessions and their frozen configuration.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Template ID
- in: path
- name: environment_template_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplateDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete an Environment Template
- tags:
- - Environment Templates
- get:
- description: Returns safe tenant-owned configuration metadata without allocating
- compute. Missing and foreign resources return the same not-found response.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Template ID
- in: path
- name: environment_template_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplate'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve an Environment Template
- tags:
- - Environment Templates
- post:
- consumes:
- - application/json
- description: Supplied fields replace atomically; omitted fields remain unchanged.
- Null name clears and null network resets to the pinned enabled default. Existing
- Session snapshots and creation retries remain unchanged. Initial files replace
- as a list; null/empty clears. File data is encrypted separately and excluded
- from response metadata. Skills replace as a list; null/empty clears. Skill
- archives are encrypted separately and omitted from responses. Plugins and
- capability directories replace as lists; null/empty clears. Plugin archives
- are encrypted and omitted from responses. Capability directories are snapshotted
- after setup. Environment MCP execution requires a qualified native transport
- and runtime network policy. Empty updates advance updated_at without changing
- saved fields or confidential contents. Network policy rejections return invalid_request_error
- with a null param.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Template ID
- in: path
- name: environment_template_id
- required: true
- type: string
- - description: Configuration replacements
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplateRequest'
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.EnvironmentTemplate'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Update an Environment Template
- tags:
- - Environment Templates
- /agents/sessions:
- get:
- description: Cursor and results are scoped to the authenticated execution tenant;
- an unknown, malformed or foreign after cursor returns not found. Optional
- agent_id matches the immutable root Agent ID, including inline Agents and
- historical Sessions whose saved source was updated or deleted. Omission lists
- all Agents. Returns the same Environment and pending-input activity projection
- as Session retrieval, including self_hosted Sessions.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Root Agent ID whose Sessions to return
- in: query
- name: agent_id
- type: string
- - description: Last Session ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List execution Sessions
- tags:
- - Sessions
- post:
- consumes:
- - application/json
- description: 'The optional Core model_provider bundle resolves from the Session
- override, saved Agent defaults, then, for openai_hosted and none, the deployment
- default of the resolved harness; self_hosted never uses the deployment default
- and none accepts only it. openai_hosted and self_hosted Sessions that resolve
- no bundle return 400 model_provider_required with param x_agents_core.model_provider
- before any write. Core encrypts and freezes the resolved bundle; later Agent
- or deployment default edits and same-key retries cannot change it. Keys are
- never returned. Supports inline configuration or a tenant-owned saved agent_id
- with per-Session field replacements. Execution supports model/instructions,
- text verbosity, non-deferred function tools, adapter-qualified multi_agent
- with persisted Subagent reads, implicit reasoning, service tier auto and environment
- type none, subject to the configured engine. Codex additionally supports HTTP
- MCP with service origin (omitted or null on HTTP transport is saved as service),
- native allowed_tools and boolean required defaulting to false. Session vault_ids
- attach only project-owned Vaults; credential_id selects an attached static
- bearer or OAuth credential for the exact HTTPS URL, while null/omission selects
- a unique match or remains anonymous. Session reads, lists and event snapshots
- show that implicitly selected credential ID in a null or omitted credential_id,
- also after the credential is deleted; anonymous selections stay null and the
- stored caller intent is unchanged. After the input requirement and before
- any write, a credential_id without vault_ids, one outside the attached Vaults
- (one message for missing, foreign and unattached IDs) or one for another server_url
- returns 400 invalid_request_error, and several implicit matches return 409
- conflict_error. Missing decryption configuration fails dispatch without anonymous
- fallback. Required initialization uses native startup before the first native
- Turn, including cold resume, and requires a separately advertised capability;
- exact hosted creation timing and error parity remain unverified. Explicit
- environment-origin HTTP MCP is supported on managed and self-hosted workspaces
- through the same Runtime bindings; native OAuth login remains unsupported.
- The self_hosted profile uses a qualified native harness, a clean absolute
- workspace_directory and optional absolute local capability_directories prepared
- by Runtime, with optional non-deferred function tools and HTTP MCP using explicit
- environment origin, optionally authenticated by the attached Vault rules.
- Service-origin HTTP remains restricted to service-side environment:none. Remote
- MCP and remote Bearer authentication each require separately advertised combination
- support; old peers cannot receive unsupported work. Omitted/null capability_directories
- use the empty-list default; self_hosted requires configured execution plus
- executor registry. Claude SDK currently requires medium verbosity and object-root
- function schemas. It supports anonymous or attached static-bearer service-origin
- HTTP MCP on none with boolean required and separately advertised MCP/bearer/required
- runtime support. Required servers must be connected before the first native
- input is released; pending or failed startup rejects execution. The shared
- Vault selection and immutable binding rules apply; unsupported native labels/tool
- names reject before persistence. An attached Vault with no matching credential
- may remain anonymous; missing keys or failed credential lookup/decryption
- never fall back to anonymous execution. Omitted stream defaults to false;
- stream and agent_id cannot be null. Metadata may be null; non-string values
- and limit violations return invalid_request_error with a metadata or metadata.
- param. The inline agent uses the Agent create configuration validation with
- agent.-prefixed params, reported before the input requirement and saved-Agent
- lookup; saved configurations with conflicting tools or schema roots reject
- admission with the same errors, and execution limits keep unsupported_or_invalid_configuration.
- Hosted network policy rejections return invalid_request_error with a null
- param. Initial input accepts a string or ordered user-message array. Codex
- and Claude SDK on none and qualified managed or self_hosted workspace profiles
- also accept inline PNG/JPEG image content; other image combinations and remote
- URLs are unsupported. None initial input atomically starts a Turn; self_hosted
- initial input is reserved while returning its Environment connection target,
- with execution deferred to native readiness and Session failure on initial
- timeout. Initial input is required for none and for streamed creation outside
- self_hosted. Omitted/null input remains valid for non-streaming hosted and
- self_hosted creation. With stream=true, returns live Session events starting
- with the committed creation snapshot and closes right after the first agent.session.idle
- recorded when a Turn ends or an input reservation stops being pending, or
- any agent.session.failed, without sending later events. A creation that admitted
- nothing closes after the snapshot; a settlement that records no event closes
- after events up to the cursor read with a settled Session projection. Required
- actions keep it open; disconnect does not cancel execution. The GET events
- stream remains live-only. New Sessions retain their authenticated creator;
- all creation retries require the same typed subject, including across key
- rotation. Saved-Agent retries and inline requests using Vault attachments
- or credential references retain caller intent independently of later resource
- changes; new hosted inline requests also freeze caller intent before deployment
- defaults resolve; unrelated non-hosted inline retries preserve resolved/default
- equivalences, and their resolved hash leaves out any deployment default. Provider
- keys enter retry hashes only as fingerprints keyed by the credential key.
- Unknown historical creators reject retries; known creators without recorded
- intent retain resolved-snapshot retry rules. These conflict policies are local
- and not verified hosted parity. A same-key stream=true retry of an existing
- creation returns 201 with no events and closes at once; retry with stream=false
- or use the GET events stream to recover. Claude SDK on none, Core-managed
- Docker openai_hosted and self_hosted supports qualified object-root json_schema
- output with medium verbosity, single-Agent execution and ordinary functions.
- Hosted execution reuses native workspace tools and Files/Artifacts; Skills,
- Plugins, capability directories, HTTP MCP, Subagent and tool_search combinations
- remain unqualified, including inherited template contents. Other non-text
- initial input remains unsupported. Basic Codex and Claude SDK openai_hosted
- creation requires an explicitly configured managed provider. The Claude workspace
- profile supports non-deferred function tools with text or successful inline
- PNG/JPEG results alongside native workspace tools; explicit environment-origin
- HTTP MCP uses the common Runtime path. MiniMax accepts public environment-origin
- HTTP MCP only with null or omitted allowed_tools and required=false; even
- an empty non-null allowlist rejects. Idle Sessions provision automatically;
- initial provisioning has no caller connection action. Network defaults to
- enabled; disabled and restricted policies reject before compute allocation
- because the current Runtime cannot enforce them. The x_agents_core.environment
- extension accepts common preparation fields for either hosted or self-hosted
- placement: environment_template_id, files, env, packages, setup_commands,
- skills, plugins and capability_directories. Duplicate fields in environment
- and the extension reject. Confidential env, npm/Python packages and ordered
- setup commands use the same Environment-owned initialization lifecycle; compute
- allocation does not own preparation. Unknown side effects are not replayed
- after disconnect or restart. System dependencies must be preinstalled in the
- sandbox image or template, or on the host machine; packages.system is rejected.
- Initial inline and tenant-owned file_id files freeze encrypted bytes before
- provisioning, then install through the common Core lifecycle before native
- execution or live Files access. With a template reference, omitted/null files,
- env, packages and setup_commands inherit. Non-null files and command lists
- replace; env overlays by key; each package manager inherits on omission/null
- and otherwise replaces its list. Empty lists clear their selected field. Tenant-owned
- environment_template_id references inherit omitted/null network and allow
- only narrowing overrides. Inline hosted network:null retains the enabled default;
- updating a Template with network:null resets its saved policy to enabled.
- Core freezes effective configuration; template updates/deletion do not alter
- Session snapshots or same-intent creation retries. Inline or tenant-owned
- skill_reference Skills share initialization. Templates preserve default/latest/explicit
- selectors; Session creation freezes concrete metadata and encrypted content
- atomically. Skill, Plugin and capability-directory list omission/null inherit;
- a non-null list replaces, including empty-list clearing. Omitted/null Skill
- version selectors resolve the default version. Source deletion/default updates
- cannot change committed Session Skill contents. Deferred function discovery
- uses type-only tool_search and per-function defer_loading in the qualified
- single-agent Claude function profile on none or a managed/user-owned workspace,
- including qualified inline image messages and text results. Explicit web_search
- mode disabled and programmatic_tool_calling enabled false use frozen common
- Runtime controls. Enabled forms, including those saved on an Agent, remain
- unqualified and reject before any write unless the Session replaces tools.
- Omitted programmatic configuration preserves native behavior, a documented
- difference from the official default-on behavior. Other combinations remain
- unqualified; see the operation coverage.'
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Creation retry key, up to 128 bytes
- in: header
- name: Idempotency-Key
- type: string
- - description: Session configuration
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.CreateSessionRequest'
- produces:
- - application/json
- - text/event-stream
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.Session'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "409":
- description: Conflict
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create an execution Session
- tags:
- - Sessions
- /agents/sessions/{session_id}:
- delete:
- description: Removes a durably idle or failed Session and its history from the
- public API. A Session whose root Turn is queued, in progress or waiting (including
- required actions) or whose input reservation is pending returns 409 conflict_error
- and is left unchanged; cancel it and wait until it is idle before deleting.
- Subagent child Turns and pending Environment file writes are not checked and
- do not block deletion. Repeating the deletion of the caller's own deleted
- Session returns the same confirmation; missing and foreign Sessions return
- 404. Internal records and native history are retained pending separate physical
- cleanup; overlapping stream timing remains unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "409":
- description: Conflict
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete an execution Session
- tags:
- - Sessions
- get:
- description: Returns supported none, self_hosted and basic openai_hosted Session
- environments. Self-hosted pending input can require a caller connection before
- a Turn exists. Hosted initial provisioning remains idle until a Turn starts;
- connection observations are not native execution readiness.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Session'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve an execution Session
- tags:
- - Sessions
- post:
- consumes:
- - application/json
- description: The metadata field is required in an update body. Send null or
- {} to clear it, or supply an object to replace all pairs. Up to 16 string
- pairs, with keys at most 64 characters and values at most 512 characters;
- violations and non-string values return invalid_request_error with a metadata
- or metadata. param. U+0000 is rejected as a local storage limit. Malformed,
- missing and foreign Session IDs share the not-found response. Execution configuration
- and activity are unchanged. Returns the same safe Environment and pending-input
- activity projection as Session retrieval.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Session metadata
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.UpdateSessionRequest'
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Session'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Update execution Session metadata
- tags:
- - Sessions
- /agents/sessions/{session_id}/artifacts:
- get:
- description: Lists published outputs independently of Environment availability.
- Sorting uses publication time and ID. A later Turn publishes a path again
- only when it is new, its bytes changed, or no Artifact remains for it. A malformed
- environment_id matches nothing. An after value that is not an Artifact of
- this Session, including a malformed one, returns 400 invalid_request_error
- with the message "after is not a valid artifact ID". The local default page
- size is 20; exact upstream defaults remain unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Producing Environment ID; an unknown or malformed ID returns
- an empty page
- in: query
- name: environment_id
- type: string
- - description: Last immutable artifact ID
- in: query
- name: after
- type: string
- - default: 20
- description: Page size
- in: query
- maximum: 100
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Publication order; omit for descending, explicit empty values
- are invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionArtifactList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List immutable Session artifacts
- tags:
- - Artifacts
- /agents/sessions/{session_id}/artifacts/{artifact_id}:
- delete:
- description: Deletes the published copy without modifying its original workspace
- file. Already admitted content reads may finish; later reads reject.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Artifact ID
- in: path
- name: artifact_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionArtifactDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete a published artifact
- tags:
- - Artifacts
- get:
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Artifact ID
- in: path
- name: artifact_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionArtifact'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve immutable artifact metadata
- tags:
- - Artifacts
- /agents/sessions/{session_id}/artifacts/{artifact_id}/content:
- get:
- description: Streams stored bytes after tenant and Session authorization, including
- after Environment expiration. Exact upstream headers and Range behavior remain
- unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Artifact ID
- in: path
- name: artifact_id
- required: true
- type: string
- produces:
- - application/octet-stream
- responses:
- "200":
- description: OK
- schema:
- type: file
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Download immutable artifact bytes
- tags:
- - Artifacts
- /agents/sessions/{session_id}/events:
- get:
- description: |-
- Live-only events, including command output fragments from capable Codex peers as agent.output.command_execution_output.delta with stable Item/output indexes. Native text conversion and output quotas apply; completion snapshots remain authoritative. Reconnect through Session, Turn and Items reads; missed events are not replayed. A lagging stream closes with an error when its bounded buffer is exceeded. When a hosted Environment fails to provision, the stream sends agent.session.environment.failed, an error event (environment_error/sandbox_error with the safe step and exit-status reason, never command output) and agent.session.failed, then ends. Session activity includes immutable pending-input connection actions before Turn creation; self_hosted environments use the same safe output as Session retrieval.
- Active streams revalidate the original Project key every second before output; revocation, Project archival or authentication unavailability closes the stream. Authentication checks use a five-second timeout.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- produces:
- - text/event-stream
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SessionEvent'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Stream live Session events
- tags:
- - Events
- post:
- consumes:
- - application/json
- description: An empty events array is a resource-authorized no-op; it creates
- no execution retry identity, Turn, Item or input receipt. For environment
- none, atomically accepts text messages, cancellation and function results.
- Messages steer active work or start a queued Turn. Qualified Codex and Claude
- SDK workspace profiles accept text and inline PNG/JPEG messages, independently
- of managed or self_hosted ownership. Under the Session lock, matching retries
- retain their original target; new active messages append to the current Turn,
- while idle messages reserve work and wait up to the original five-minute connection/admission
- deadline. Return 202 only after durable admission, without claiming native
- application; active messages create no Turn or reservation. Cancellation-only
- prepared-environment batches use existing durable cancellation admission and
- return 202 without waiting for native exit; a new cancellation conflicts while
- a pre-Turn reservation is pending. Homogeneous tool_result-only prepared-environment
- batches reuse existing scoped result admission and application receipts without
- creating a Turn or bypassing a pending reservation. Mixed prepared-environment
- batches remain unsupported. HTTP expiry/cancellation use local 409 environment_input_expired/environment_input_cancelled
- errors. New input on a Session whose hosted Environment failed to provision
- returns the observed 409 conflict_error "the hosted environment failed to
- provision"; input already waiting when it fails and expired Environments keep
- the local 409 environment_unavailable. Input the Session cannot accept in
- its current state, such as a result after cancellation or a batch while earlier
- input is pending, and a result that differs from the call's saved result return
- 409 with type and code conflict_error; reusing an Idempotency-Key with a different
- batch returns the local 409 idempotency_conflict. Inside an owned Session,
- a result for an unknown call or for a call of another Turn returns 400 invalid_request_error
- and changes nothing; missing and foreign Sessions return 404. Losing execution
- ownership returns 503. The response write deadline accommodates the admission
- window for either prepared Environment, independently of new-hosted-admission
- and executor URL settings. Disconnecting the waiting HTTP request does not
- cancel retained work or restart its deadline. Retry keys identify the whole
- ordered batch. Function output accepts text or ordered text/image parts subject
- to engine support; Claude SDK accepts text results and, on none and qualified
- workspace profiles, successful inline PNG/JPEG results, preserving ordered
- content; error images and remote references reject before admission. Native
- image resizing may change bytes. Runtime image-result support is checked only
- for image-bearing delivery. Codex and Claude SDK on none and qualified managed
- or self_hosted workspace profiles accept ordered inline PNG/JPEG image messages.
- Other engines remain text-only; remote image URLs are unsupported. Image references
- are retained unchanged without service-side downloads.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Retry key, up to 128 bytes
- in: header
- name: Idempotency-Key
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Ordered input events
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.CreateEventsRequest'
- responses:
- "202":
- description: Accepted
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "409":
- description: Conflict
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Submit Session input events
- tags:
- - Sessions
- /agents/sessions/{session_id}/items:
- get:
- description: Returns supported message and tool Items in first-observation order.
- Native engine fields are projected explicitly; unfinished Items on terminal
- Turns are incomplete. Cursors are Items of the same tenant and Session. Any
- other after value, including a malformed one, returns 400 invalid_request_error
- with the message "Invalid session item ID in `after`".
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Last Item ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.ItemList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List persisted execution Items
- tags:
- - Items
- /agents/sessions/{session_id}/subagents:
- get:
- description: Includes nested and closed Subagents. Cursors are Subagents of
- the same tenant and Session. Any other after value, including a malformed
- one, returns 400 invalid_request_error with the message "Invalid resource
- ID in `after`". A limit outside 1–100 is rejected.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Last Subagent ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size
- in: query
- maximum: 100
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Resource order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SubagentList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List Session Subagents
- tags:
- - Subagents
- /agents/sessions/{session_id}/subagents/{subagent_id}:
- get:
- description: Returns this Session's persisted Subagent. Active includes idle
- between Turns. Resuming preserves opened_at and clears closed_at. Unknown
- or inaccessible parent scopes return not found.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Subagent ID
- in: path
- name: subagent_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Subagent'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve a Session Subagent
- tags:
- - Subagents
- /agents/sessions/{session_id}/subagents/{subagent_id}/items:
- get:
- description: Returns only this Subagent's own Items across all its Turns, not
- its descendants' Items. Cursors are Items of the same tenant, Session and
- Subagent. Any other after value, including a malformed one, returns 400 invalid_request_error
- with the message "Invalid session item ID in `after`".
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Subagent ID
- in: path
- name: subagent_id
- required: true
- type: string
- - description: Last Item ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Resource order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.ItemList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List a Subagent's Items
- tags:
- - Subagents
- /agents/sessions/{session_id}/subagents/{subagent_id}/turns:
- get:
- description: Includes this Subagent's Turns after resume, with the Session's
- Agent ID as agent_id. Cursors are Turns of the same tenant, Session and Subagent.
- Any other after value, including a malformed one, returns 400 invalid_request_error
- with the message "Invalid resource ID in `after`". Missing recorded usage
- remains null. A limit outside 1–100 is rejected.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Subagent ID
- in: path
- name: subagent_id
- required: true
- type: string
- - description: Last Turn ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size
- in: query
- maximum: 100
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.TurnList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List a Subagent's Turns
- tags:
- - Subagents
- /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}:
- get:
- description: Returns a Turn owned by this Subagent. Its agent_id is the Session's
- Agent ID and its subagent_id identifies the Subagent. Session Turn routes
- do not return child Turns. Unknown or inaccessible parent scopes return not
- found.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Subagent ID
- in: path
- name: subagent_id
- required: true
- type: string
- - description: Turn ID
- in: path
- name: turn_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Turn'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve a Subagent Turn
- tags:
- - Subagents
- /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items:
- get:
- description: Returns Items owned by this exact Subagent Turn. Cursors are Items
- of the same tenant, Session, Subagent and Turn. Any other after value, including
- a malformed one, returns 400 invalid_request_error with the message "Invalid
- session item ID in `after`".
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Subagent ID
- in: path
- name: subagent_id
- required: true
- type: string
- - description: Turn ID
- in: path
- name: turn_id
- required: true
- type: string
- - description: Last Item ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 is treated as 1 and values above 100 as 100
- in: query
- minimum: 0
- name: limit
- type: integer
- - default: desc
- description: Resource order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.ItemList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List a Subagent Turn's Items
- tags:
- - Subagents
- /agents/sessions/{session_id}/turns:
- get:
- description: Returns the Session's root Turns in creation order; Subagent Turns
- are listed through the Subagent Turn routes. The cursor belongs to the same
- Session and tenant; any other after value, including a malformed one or a
- Subagent Turn ID, returns not found. Usage contains the latest recorded complete
- token breakdown; missing measurements remain null.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Last Turn ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Page size
- in: query
- maximum: 100
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.TurnList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List execution Turns
- tags:
- - Turns
- /agents/sessions/{session_id}/turns/{turn_id}:
- get:
- description: Returns a root Turn of this Session. A Subagent Turn ID returns
- the same not found error as a missing Turn; read it through the Subagent Turn
- routes.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Session ID
- in: path
- name: session_id
- required: true
- type: string
- - description: Turn ID
- in: path
- name: turn_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Turn'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve an execution Turn
- tags:
- - Turns
- /files:
- get:
- description: Lists project-owned Files without reading their bodies. The limit
- defaults to 10000 and must be 1–10000. Equal creation times use ID ordering.
- Purpose validation precedes cursor lookup; current storage contains only user_data.
- An explicit empty purpose is treated as omitted. Repeated purpose values remain
- rejected. Hosted positive filtering, default order and concurrent-page behavior
- remain unverified. No Beta header is required.
- parameters:
- - description: Last File ID from the previous page
- in: query
- name: after
- type: string
- - default: 10000
- description: Maximum page size, 1–10000
- in: query
- maximum: 10000
- minimum: 1
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- - description: Only return Files with this purpose
- in: query
- name: purpose
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SourceFileList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List source files
- tags:
- - Files
- post:
- consumes:
- - multipart/form-data
- description: Accepts one multipart file and purpose=user_data in either order,
- with a private 512 MiB content limit and 64 KiB envelope allowance. Commits
- only after the entire request validates. The source is project-owned, independent
- of Sessions and workspace copies. No Beta header is required. Other purposes,
- expires_after, listing, resumable Uploads, quotas/rate-limit and complete
- hosted error/status parity remain unsupported or unverified.
- parameters:
- - description: Source bytes
- in: formData
- name: file
- required: true
- type: file
- - description: user_data
- enum:
- - user_data
- in: formData
- name: purpose
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SourceFile'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Upload a source file
- tags:
- - Files
- /files/{file_id}:
- delete:
- description: Atomically deletes project-owned metadata and stored bytes. Already-admitted
- reads or copies may finish. Workspace copies remain independent. Historical
- WAL/backups are not erased. No Beta header is required; exact hosted concurrent
- deletion/error semantics remain unverified.
- parameters:
- - description: Source file ID
- in: path
- name: file_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SourceFileDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete a source file
- tags:
- - Files
- get:
- description: Returns immutable project-owned user_data file metadata. No Beta
- header is required. Other purposes, expiration and full hosted status/error
- semantics remain unimplemented or unverified.
- parameters:
- - description: Source file ID
- in: path
- name: file_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SourceFile'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve source file metadata
- tags:
- - Files
- /files/{file_id}/content:
- get:
- description: Resolves project-owned File metadata before enforcing download
- policy. Public download of user_data Files returns 400; missing and foreign
- Files return the same 404. Internal initial-file and workspace copies remain
- available. No Beta header is required.
- parameters:
- - description: Source file ID
- in: path
- name: file_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Download source file bytes
- tags:
- - Files
- /skills:
- get:
- description: Lists tenant-owned metadata in timestamp order. Default page size
- 20, maximum 100. Limit 0 returns an empty page whose has_more reports whether
- any Skill follows the cursor; exact hosted defaults remain unverified.
- parameters:
- - description: Skill resource cursor
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 returns an empty page
- in: query
- maximum: 100
- minimum: 0
- name: limit
- type: integer
- - description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillList'
- security:
- - BearerAuth: []
- summary: List Skills
- tags:
- - Skills
- post:
- consumes:
- - multipart/form-data
- description: Accepts one ZIP in files or a directory in files[]. Applies the
- qualified portable Skill bundle profile. No Beta header is required; full
- hosted upload limits and activation extensions are not qualified.
- parameters:
- - description: Skill ZIP or directory files
- in: formData
- name: files
- required: true
- type: file
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Skill'
- security:
- - BearerAuth: []
- summary: Upload a Skill
- tags:
- - Skills
- /skills/{skill_id}:
- delete:
- description: Deletes tenant-owned source bundles. Existing Session installation
- snapshots remain independent.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillDeleted'
- security:
- - BearerAuth: []
- summary: Delete a Skill and its versions
- tags:
- - Skills
- get:
- description: Returns tenant-owned metadata without decrypting contents or starting
- Runtime. No Beta header is required.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Skill'
- security:
- - BearerAuth: []
- summary: Retrieve Skill metadata
- tags:
- - Skills
- post:
- consumes:
- - application/json
- description: Changes only the tenant-owned default pointer; immutable versions
- and existing Session snapshots remain unchanged.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Default version
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.SkillUpdateRequest'
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Skill'
- security:
- - BearerAuth: []
- summary: Update the default Skill version
- tags:
- - Skills
- /skills/{skill_id}/content:
- get:
- description: Downloads an authorized ZIP using the default pointer when no concrete
- version is supplied. Exact upstream unversioned selection, content headers
- and range semantics remain unverified.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- produces:
- - application/octet-stream
- responses:
- "200":
- description: OK
- schema:
- type: file
- security:
- - BearerAuth: []
- summary: Download Skill content
- tags:
- - Skills
- /skills/{skill_id}/versions:
- get:
- description: Orders by version number; after identifies a version resource,
- not a version number. An after value that does not begin with skillver, or
- a version of another Skill, returns 400 invalid_value with param after; a
- missing version returns not found. No contents are decrypted. Limit 0 returns
- an empty page whose has_more reports whether any version follows the cursor.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Version resource cursor
- in: query
- name: after
- type: string
- - default: 20
- description: Page size; 0 returns an empty page
- in: query
- maximum: 100
- minimum: 0
- name: limit
- type: integer
- - description: Version order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillVersionList'
- security:
- - BearerAuth: []
- summary: List Skill versions
- tags:
- - Skills
- post:
- consumes:
- - multipart/form-data
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Skill ZIP or directory files
- in: formData
- name: files
- required: true
- type: file
- - description: Set as default
- in: formData
- name: default
- type: boolean
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillVersion'
- security:
- - BearerAuth: []
- summary: Upload an immutable Skill version
- tags:
- - Skills
- /skills/{skill_id}/versions/{version}:
- delete:
- description: Deleting the only remaining version also deletes the Skill; existing
- Session installation snapshots remain independent. The default version cannot
- be deleted while other versions remain. Version numbers are never reused.
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Concrete version number
- in: path
- name: version
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillVersionDeleted'
- security:
- - BearerAuth: []
- summary: Delete a Skill version
- tags:
- - Skills
- get:
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Concrete version number
- in: path
- name: version
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.SkillVersion'
- security:
- - BearerAuth: []
- summary: Retrieve Skill version metadata
- tags:
- - Skills
- /skills/{skill_id}/versions/{version}/content:
- get:
- parameters:
- - description: Skill ID
- in: path
- name: skill_id
- required: true
- type: string
- - description: Concrete version number
- in: path
- name: version
- required: true
- type: string
- produces:
- - application/octet-stream
- responses:
- "200":
- description: OK
- schema:
- type: file
- security:
- - BearerAuth: []
- summary: Download immutable Skill version content
- tags:
- - Skills
- /vaults:
- get:
- description: Lists project-owned Vaults independently of execution. An unknown,
- malformed or foreign after cursor returns not found. Includes active and archived
- records by default. Status accepts a scalar, the SDK's status[] array or both,
- filtering by their union; a repeated scalar is rejected. Limits default to
- 20 and clamp to 1–100. Equal creation times use ID ordering; exact hosted
- errors and concurrent-page behavior remain unverified. Archive/delete lifecycle
- is not implemented.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Last Vault ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Requested page size, clamped to 1–100
- in: query
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- - description: Scalar status filter
- enum:
- - active
- - archived
- in: query
- name: status
- type: string
- - collectionFormat: multi
- description: Array status filter; combined with status as a union
- in: query
- items:
- enum:
- - active
- - archived
- type: string
- name: status[]
- type: array
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.VaultList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List Vaults
- tags:
- - Vaults
- post:
- consumes:
- - application/json
- description: Creates a project-owned Vault independently of execution. Omitted
- name stays null; a supplied string is trimmed and must contain 1–256 UTF-8
- bytes. Explicit null name is invalid. Omitted/null metadata becomes an empty
- object; non-string values return invalid_request_error with a metadata.
- param. Metadata has a local 64 KiB encoded storage bound. U+0000 in stored
- strings is rejected as a local storage limit. Credentials, Session binding
- and hosted error/retry parity remain incomplete.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault name and metadata
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.CreateVaultRequest'
- produces:
- - application/json
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.Vault'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create a Vault
- tags:
- - Vaults
- /vaults/{vault_id}:
- delete:
- description: Atomically removes the authenticated project's Vault and all its
- stored Credentials without an encryption key, decryption or external requests.
- Existing Session snapshots, history and recorded retries retain their frozen
- identities; subsequent credential lookups fail without reselection or anonymous
- fallback. Already-resolved tokens and running Sessions are not revoked or
- cancelled. Missing/repeated deletion locally returns 404. Exact hosted archive,
- post-delete visibility and concurrent/error semantics remain unverified; physical
- erasure from native history, WAL or backups is not established.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.VaultDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete a Vault and all its Credentials
- tags:
- - Vaults
- get:
- description: Reads a Vault owned by the authenticated project without resolving
- credentials, Sessions or execution devices. Missing and foreign IDs share
- the same not-found response; exact hosted error semantics remain unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Vault'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve a Vault
- tags:
- - Vaults
- /vaults/{vault_id}/credentials:
- get:
- description: Lists only metadata from the authenticated project's requested
- Vault, without decryption or execution. An unknown, malformed or foreign after
- cursor, including another Vault's Credential, returns not found. Includes
- active and archived Credentials by default, independently of Vault status.
- Status accepts a scalar, the SDK status[] array or both, filtering by their
- union; a repeated scalar is rejected. Limits default to 20 and clamp to 1–100.
- Equal creation times use ID ordering. Hosted errors, concurrent-page behavior
- and archive/delete lifecycle remain unverified or unimplemented.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- - description: Last Credential ID from the previous page
- in: query
- name: after
- type: string
- - default: 20
- description: Requested page size, clamped to 1–100
- in: query
- name: limit
- type: integer
- - default: desc
- description: Creation order; omit for descending, explicit empty values are
- invalid
- enum:
- - asc
- - desc
- in: query
- name: order
- type: string
- - description: Scalar status filter
- enum:
- - active
- - archived
- in: query
- name: status
- type: string
- - collectionFormat: multi
- description: Array status filter; combined with status as a union
- in: query
- items:
- enum:
- - active
- - archived
- type: string
- name: status[]
- type: array
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.CredentialList'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: List safe Vault Credential metadata
- tags:
- - Credentials
- post:
- consumes:
- - application/json
- description: Stores static_bearer or mcp_oauth secrets as execution-owned authenticated
- ciphertext without contacting any endpoint. Static bearer and OAuth access
- tokens must be nonempty strings; their bytes are preserved. OAuth accepts
- a required access token, nullable RFC3339 expiry and optional refresh configuration
- with none, client_secret_basic or client_secret_post authentication. Required
- name is trimmed to 1–256 UTF-8 bytes. Credential and token endpoints require
- HTTPS without userinfo or fragments. Responses contain safe metadata only,
- including explicit nullable OAuth expiry, refresh, resource and scope. Missing
- encryption configuration returns local 503. External authorization and provider
- revocation remain caller responsibilities; exact hosted error/default semantics
- remain unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- - description: Write-only credential authentication union
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.CreateCredentialRequest'
- produces:
- - application/json
- responses:
- "201":
- description: Created
- schema:
- $ref: '#/definitions/v1.Credential'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Create a Vault Credential
- tags:
- - Credentials
- /vaults/{vault_id}/credentials/{credential_id}:
- delete:
- description: Removes one Credential and its encrypted token within the authenticated
- project and owning Vault, without an encryption key or secret decryption.
- Subsequent metadata reads, updates and dispatch lookups cannot use it. Existing
- Session snapshots and history retain their frozen identities; already-resolved
- tokens and running Sessions are not revoked or cancelled. This local policy
- removes the row rather than defining archived lifecycle; missing/repeated
- deletion returns 404. Exact hosted archive, post-delete visibility and retry/error
- semantics remain unverified. Provider revocation and physical erasure from
- native history, WAL or backups are separate concerns.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- - description: Credential ID
- in: path
- name: credential_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.CredentialDeleted'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Delete a Vault Credential
- tags:
- - Credentials
- get:
- description: Reads only non-secret metadata scoped to the authenticated project
- and owning Vault. No token decryption, network request or execution is performed.
- Unknown, foreign, wrong-Vault and malformed IDs use the same local not-found
- response; hosted error parity remains unverified.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- - description: Credential ID
- in: path
- name: credential_id
- required: true
- type: string
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Credential'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Retrieve safe Vault Credential metadata
- tags:
- - Credentials
- post:
- consumes:
- - application/json
- description: Explicitly empty static bearer or OAuth access tokens and OAuth
- patches without a mutable field are rejected before storage. Omitted OAuth
- access tokens preserve the existing grant when expiry or refresh fields change.
- Updates the existing static_bearer or mcp_oauth authentication method without
- network requests. OAuth access_token omission/null retains the token; a new
- token clears omitted expiry, explicit null clears expiry, and other omitted
- fields remain unchanged. OAuth refresh patches cannot add configuration or
- change client, endpoint, resource or authentication method; nullable token/client-secret
- values retain stored secrets while explicit null scope clears scope. Whole-null
- refresh and token_endpoint_auth retain existing configuration under local
- policy. Identity, destination, creation time and Session bindings remain unchanged.
- Responses expose safe metadata only. Already-dispatched work is not revoked;
- provider revocation, storage-key rotation and exact hosted concurrent-update/error
- semantics remain separate.
- parameters:
- - description: agents=v1
- in: header
- name: OpenAI-Beta
- required: true
- type: string
- - description: Vault ID
- in: path
- name: vault_id
- required: true
- type: string
- - description: Credential ID
- in: path
- name: credential_id
- required: true
- type: string
- - description: Write-only credential authentication replacement union
- in: body
- name: body
- required: true
- schema:
- $ref: '#/definitions/v1.UpdateCredentialRequest'
- produces:
- - application/json
- responses:
- "200":
- description: OK
- schema:
- $ref: '#/definitions/v1.Credential'
- "400":
- description: Bad Request
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "401":
- description: Unauthorized
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "404":
- description: Not Found
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "413":
- description: Request Entity Too Large
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "500":
- description: Internal Server Error
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- "503":
- description: Service Unavailable
- schema:
- $ref: '#/definitions/v1.ErrorResponse'
- security:
- - BearerAuth: []
- summary: Replace Vault Credential authentication secrets
- tags:
- - Credentials
-schemes:
-- http
-- https
-securityDefinitions:
- BearerAuth:
- in: header
- name: Authorization
- type: apiKey
-swagger: "2.0"
+{
+ "openapi": "3.1.0",
+ "info": {
+ "title": "OpenAgentCore public API",
+ "version": "v1",
+ "description": "The pinned OpenAI Agents, Files and Skills API with x_agents_core extensions. See the coverage ledger for implementation qualification."
+ },
+ "servers": [
+ {
+ "url": "/v1"
+ }
+ ],
+ "security": [
+ {
+ "ProjectKey": []
+ }
+ ],
+ "tags": [
+ {
+ "name": "Assistants",
+ "description": "Build Assistants that can call models and use tools."
+ },
+ {
+ "name": "Audio",
+ "description": "Turn audio into text or text into audio."
+ },
+ {
+ "name": "Chat",
+ "description": "Given a list of messages comprising a conversation, the model will return a response."
+ },
+ {
+ "name": "Conversations",
+ "description": "Manage conversations and conversation items."
+ },
+ {
+ "name": "Completions",
+ "description": "Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position."
+ },
+ {
+ "name": "Embeddings",
+ "description": "Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms."
+ },
+ {
+ "name": "Evals",
+ "description": "Manage and run evals in the OpenAI platform."
+ },
+ {
+ "name": "Fine-tuning",
+ "description": "Manage fine-tuning jobs to tailor a model to your specific training data."
+ },
+ {
+ "name": "Graders",
+ "description": "Manage and run graders in the OpenAI platform."
+ },
+ {
+ "name": "Batch",
+ "description": "Create large batches of API requests to run asynchronously."
+ },
+ {
+ "name": "Files",
+ "description": "Files are used to upload documents that can be used with features like Assistants and Fine-tuning."
+ },
+ {
+ "name": "Uploads",
+ "description": "Use Uploads to upload large files in multiple parts."
+ },
+ {
+ "name": "Images",
+ "description": "Given a prompt and/or an input image, the model will generate a new image."
+ },
+ {
+ "name": "Models",
+ "description": "List and describe the various models available in the API."
+ },
+ {
+ "name": "Moderations",
+ "description": "Given text and/or image inputs, classifies if those inputs are potentially harmful."
+ },
+ {
+ "name": "Audit Logs",
+ "description": "List user actions and configuration changes within this organization."
+ }
+ ],
+ "paths": {
+ "/files": {
+ "get": {
+ "operationId": "listFiles",
+ "tags": [
+ "Files"
+ ],
+ "summary": "Returns a list of files.",
+ "parameters": [
+ {
+ "in": "query",
+ "name": "purpose",
+ "required": false,
+ "schema": {
+ "type": "string"
+ },
+ "description": "Only return files with the given purpose."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.\n",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "default": 10000
+ }
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "description": "Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.\n",
+ "schema": {
+ "type": "string",
+ "default": "desc",
+ "enum": [
+ "asc",
+ "desc"
+ ]
+ }
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "description": "A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.\n",
+ "schema": {
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ListFilesResponse"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List files",
+ "group": "files",
+ "examples": {
+ "request": {
+ "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n",
+ "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.list()\n",
+ "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const list = await openai.files.list();\n\n for await (const file of list) {\n console.log(file);\n }\n}\n\nmain();"
+ },
+ "response": "{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 175,\n \"created_at\": 1613677385,\n \"expires_at\": 1677614202,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n },\n {\n \"id\": \"file-abc456\",\n \"object\": \"file\",\n \"bytes\": 140,\n \"created_at\": 1613779121,\n \"expires_at\": 1677614202,\n \"filename\": \"puppy.jsonl\",\n \"purpose\": \"fine-tune\",\n }\n ],\n \"first_id\": \"file-abc123\",\n \"last_id\": \"file-abc456\",\n \"has_more\": false\n}\n"
+ }
+ }
+ },
+ "post": {
+ "operationId": "createFile",
+ "tags": [
+ "Files"
+ ],
+ "summary": "Upload a file that can be used across various endpoints. Individual files\ncan be up to 512 MB, and each project can store up to 2.5 TB of files in\ntotal. There is no organization-wide storage limit. Uploads to this\nendpoint are rate-limited to 1,000 requests per minute per authenticated\nuser.\n\n- The Assistants API supports files up to 2 million tokens and of specific\n file types. See the [Assistants Tools guide](https://developers.openai.com/api/docs/guides/tools) for\n details.\n- The Fine-tuning API only supports `.jsonl` files. The input also has\n certain required formats for fine-tuning\n [chat](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) or\n [completions](https://developers.openai.com/api/docs/guides/supervised-fine-tuning#formatting-your-data) models.\n- The Batch API only supports `.jsonl` files up to 200 MB in size. The input\n also has a specific required\n [format](https://developers.openai.com/api/docs/guides/batch#1-prepare-your-batch-file).\n- For Retrieval or `file_search` ingestion, upload files here first. If\n you need to attach multiple uploaded files to the same vector store, use\n [`/vector_stores/{vector_store_id}/file_batches`](https://developers.openai.com/api/reference/resources/vector_stores/subresources/file_batches/methods/create)\n instead of attaching them one by one. Vector store attachment has separate\n limits from file upload, including 2,000 attached files per minute per\n organization.\n\nPlease [contact us](https://help.openai.com/) if you need to increase these\nstorage limits.\n",
+ "requestBody": {
+ "required": true,
+ "content": {
+ "multipart/form-data": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateFileRequest"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OpenAIFile"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Upload file",
+ "group": "files",
+ "description": "Uploads a file for later use across OpenAI APIs. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user. For Retrieval or `file_search` ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use vector store file batches instead of attaching them one by one.\n",
+ "examples": {
+ "request": {
+ "curl": "curl https://api.openai.com/v1/files \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F purpose=\"fine-tune\" \\\n -F file=\"@mydata.jsonl\"\n -F expires_after[anchor]=\"created_at\"\n -F expires_after[seconds]=2592000\n",
+ "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.create(\n file=open(\"mydata.jsonl\", \"rb\"),\n purpose=\"fine-tune\",\n expires_after={\n \"anchor\": \"created_at\",\n \"seconds\": 2592000\n }\n)\n",
+ "javascript": "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.create({\n file: fs.createReadStream(\"mydata.jsonl\"),\n purpose: \"fine-tune\",\n expires_after: {\n anchor: \"created_at\",\n seconds: 2592000\n }\n });\n\n console.log(file);\n}\n\nmain();"
+ },
+ "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n"
+ }
+ }
+ }
+ },
+ "/files/{file_id}": {
+ "delete": {
+ "operationId": "deleteFile",
+ "tags": [
+ "Files"
+ ],
+ "summary": "Delete a file and remove it from all vector stores.",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "file_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "description": "The ID of the file to use for this request."
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeleteFileResponse"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete file",
+ "group": "files",
+ "examples": {
+ "request": {
+ "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -X DELETE \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n",
+ "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.delete(\"file-abc123\")\n",
+ "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.delete(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();"
+ },
+ "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"deleted\": true\n}\n"
+ }
+ }
+ },
+ "get": {
+ "operationId": "retrieveFile",
+ "tags": [
+ "Files"
+ ],
+ "summary": "Returns information about a specific file.",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "file_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "description": "The ID of the file to use for this request."
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/OpenAIFile"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve file",
+ "group": "files",
+ "examples": {
+ "request": {
+ "curl": "curl https://api.openai.com/v1/files/file-abc123 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\"\n",
+ "python": "from openai import OpenAI\nclient = OpenAI()\n\nclient.files.retrieve(\"file-abc123\")\n",
+ "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const file = await openai.files.retrieve(\"file-abc123\");\n\n console.log(file);\n}\n\nmain();"
+ },
+ "response": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1677614202,\n \"filename\": \"mydata.jsonl\",\n \"purpose\": \"fine-tune\",\n}\n"
+ }
+ }
+ }
+ },
+ "/files/{file_id}/content": {
+ "get": {
+ "operationId": "downloadFile",
+ "tags": [
+ "Files"
+ ],
+ "summary": "Returns a response containing the contents of the specified file.",
+ "parameters": [
+ {
+ "in": "path",
+ "name": "file_id",
+ "required": true,
+ "schema": {
+ "type": "string"
+ },
+ "description": "The ID of the file to use for this request."
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "OK",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve file content",
+ "group": "files",
+ "examples": {
+ "request": {
+ "curl": "curl https://api.openai.com/v1/files/file-abc123/content \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" > file.jsonl\n",
+ "python": "from openai import OpenAI\nclient = OpenAI()\n\ncontent = client.files.content(\"file-abc123\")\n",
+ "javascript": "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const response = await openai.files.content(\"file-abc123\");\n const content = await response.text();\n\n console.log(content);\n}\n\nmain();\n"
+ }
+ }
+ }
+ }
+ },
+ "/skills": {
+ "post": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Create a new skill.",
+ "operationId": "CreateSkill",
+ "parameters": [],
+ "requestBody": {
+ "content": {
+ "multipart/form-data": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateSkillBody"
+ }
+ },
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateSkillBody"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ },
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "List all skills for the current project.",
+ "operationId": "ListSkills",
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Number of items to retrieve",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 100
+ }
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "description": "Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/OrderEnum"
+ }
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "description": "Identifier for the last item from the previous pagination request",
+ "required": false,
+ "schema": {
+ "description": "Identifier for the last item from the previous pagination request",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillListResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/skills/{skill_id}": {
+ "delete": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Delete a skill by its ID.",
+ "operationId": "DeleteSkill",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill to delete.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedSkillResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ },
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Get a skill by its ID.",
+ "operationId": "GetSkill",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill to retrieve.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ },
+ "post": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Update the default version pointer for a skill.",
+ "operationId": "UpdateSkillDefaultVersion",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SetDefaultSkillVersionBody"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/skills/{skill_id}/content": {
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Download a skill zip bundle by its ID.",
+ "operationId": "GetSkillContent",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill to download.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The skill zip bundle.",
+ "content": {
+ "application/zip": {
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ },
+ "application/json": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/skills/{skill_id}/versions": {
+ "post": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Create a new immutable skill version.",
+ "operationId": "CreateSkillVersion",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill to version.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "multipart/form-data": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateSkillVersionBody"
+ }
+ },
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateSkillVersionBody"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillVersionResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ },
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "List skill versions for a skill.",
+ "operationId": "ListSkillVersions",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "Number of versions to retrieve.",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 100
+ }
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "description": "Sort order of results by version number.",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/OrderEnum"
+ }
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "description": "The skill version ID to start after.",
+ "required": false,
+ "schema": {
+ "example": "skillver_123",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillVersionListResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/skills/{skill_id}/versions/{version}": {
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Get a specific skill version.",
+ "operationId": "GetSkillVersion",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ },
+ {
+ "name": "version",
+ "in": "path",
+ "description": "The version number to retrieve.",
+ "required": true,
+ "schema": {
+ "description": "The version number to retrieve.",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SkillVersionResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ },
+ "delete": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Delete a skill version.",
+ "operationId": "DeleteSkillVersion",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ },
+ {
+ "name": "version",
+ "in": "path",
+ "description": "The skill version number.",
+ "required": true,
+ "schema": {
+ "description": "The skill version number.",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Success",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedSkillVersionResource"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/skills/{skill_id}/versions/{version}/content": {
+ "get": {
+ "tags": [
+ "Skills"
+ ],
+ "summary": "Download a skill version zip bundle.",
+ "operationId": "GetSkillVersionContent",
+ "parameters": [
+ {
+ "name": "skill_id",
+ "in": "path",
+ "description": "The identifier of the skill.",
+ "required": true,
+ "schema": {
+ "example": "skill_123",
+ "type": "string"
+ }
+ },
+ {
+ "name": "version",
+ "in": "path",
+ "description": "The skill version number.",
+ "required": true,
+ "schema": {
+ "description": "The skill version number.",
+ "type": "string"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The skill zip bundle.",
+ "content": {
+ "application/zip": {
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ },
+ "application/json": {
+ "schema": {
+ "type": "string"
+ }
+ }
+ }
+ },
+ "429": {
+ "$ref": "#/components/responses/TooManyRequests"
+ }
+ }
+ }
+ },
+ "/agents/environments/{environment_id}": {
+ "get": {
+ "operationId": "retrieveAgentEnvironment",
+ "summary": "Retrieves an execution environment's connection status and safe installed metadata. See [environment lifecycle](https://developers.openai.com/api/docs/guides/agents-api/environments/lifecycle).",
+ "description": "Retrieves an execution environment's connection status and safe installed metadata.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the environment."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested environment.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/PublicEnvironmentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent environment"
+ }
+ }
+ },
+ "/agents/environments/{environment_id}/files": {
+ "get": {
+ "operationId": "listAgentEnvironmentFiles",
+ "summary": "Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files).",
+ "description": "Lists live files on a connected execution environment with optional directory filtering and opaque cursor pagination.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the environment."
+ },
+ {
+ "name": "path",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Restrict the listing to this absolute workspace directory."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100
+ },
+ "description": "The maximum number of files to return, between 1 and 100."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam"
+ },
+ "description": "Sort by case-sensitive path components. Defaults to descending."
+ },
+ {
+ "name": "page",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The opaque token from the previous page. Keep the same path, order, and limit."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of live environment files.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentFileListResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent environment files"
+ }
+ },
+ "post": {
+ "operationId": "createAgentEnvironmentFile",
+ "summary": "Copies inline bytes or a Files API file into a connected execution environment. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files).",
+ "description": "Copies inline bytes or a Files API file into a connected execution environment.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the environment."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParam"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created live environment file.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentFileResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create an agent environment file"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents": {
+ "get": {
+ "operationId": "listAgentSessionSubagents",
+ "summary": "Lists subagents in a session, including nested and closed subagents. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Lists subagents in a session, including nested and closed subagents.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagents.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SubagentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List session subagents"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents/{subagent_id}": {
+ "get": {
+ "operationId": "retrieveAgentSessionSubagent",
+ "summary": "Retrieves a subagent belonging to this session. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Retrieves a subagent belonging to this session.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "subagent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the subagent in this session."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagent.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SubagentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve a session subagent"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents/{subagent_id}/items": {
+ "get": {
+ "operationId": "listAgentSessionSubagentItems",
+ "summary": "Lists this subagent's own items across all of its turns. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Lists this subagent's own items across all of its turns.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "subagent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the subagent in this session."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagent history.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionItemListResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List subagent items"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents/{subagent_id}/turns": {
+ "get": {
+ "operationId": "listAgentSessionSubagentTurns",
+ "summary": "Lists all turns of this subagent, including turns after a resume. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Lists all turns of this subagent, including turns after a resume.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "subagent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the subagent in this session."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagent history.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionTurnListResource",
+ "description": "A page of turns from an agent session or subagent."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List subagent turns"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}": {
+ "get": {
+ "operationId": "retrieveAgentSessionSubagentTurn",
+ "summary": "Retrieves a turn belonging to this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Retrieves a turn belonging to this subagent.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "subagent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the subagent in this session."
+ },
+ {
+ "name": "turn_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of a turn belonging to this subagent."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagent history.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TurnResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve a subagent turn"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items": {
+ "get": {
+ "operationId": "listAgentSessionSubagentTurnItems",
+ "summary": "Lists items belonging to one turn of this subagent. See [subagent workflows](https://developers.openai.com/api/docs/guides/agents-api/multi-agent).",
+ "description": "Lists items belonging to one turn of this subagent.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "subagent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the subagent in this session."
+ },
+ {
+ "name": "turn_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of a turn belonging to this subagent."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested subagent history.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionItemListResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List subagent turn items"
+ }
+ }
+ },
+ "/agents": {
+ "get": {
+ "operationId": "listAgents",
+ "summary": "Lists reusable agents in the current project. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).",
+ "description": "Lists reusable agents in the current project.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 1
+ },
+ "description": "The maximum number of resources to return."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of agents.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentListResource",
+ "description": "A page of reusable agents."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agents"
+ }
+ },
+ "post": {
+ "operationId": "createAgent",
+ "summary": "Creates a reusable agent without storing credentials. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).",
+ "description": "Creates a reusable agent without storing credentials.",
+ "tags": [
+ "Agents"
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateAgentParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created agent.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create an agent"
+ },
+ "parameters": [
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ]
+ }
+ },
+ "/agents/{agent_id}": {
+ "get": {
+ "operationId": "retrieveAgent",
+ "summary": "Retrieves a reusable agent by ID. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).",
+ "description": "Retrieves a reusable agent by ID.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "agent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable agent."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested agent.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent"
+ }
+ },
+ "post": {
+ "operationId": "updateAgent",
+ "summary": "Updates a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).",
+ "description": "Updates a reusable agent.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "agent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable agent."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateAgentParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The updated agent.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/AgentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Update an agent"
+ }
+ },
+ "delete": {
+ "operationId": "deleteAgent",
+ "summary": "Deletes a reusable agent. See [agent configuration](https://developers.openai.com/api/docs/guides/agents-api/configuration).",
+ "description": "Deletes a reusable agent.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "agent_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable agent."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted agent.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedAgentResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete an agent"
+ }
+ }
+ },
+ "/agents/environments/templates": {
+ "get": {
+ "operationId": "listAgentEnvironmentTemplates",
+ "summary": "Lists reusable environment templates without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).",
+ "description": "Lists reusable environment templates without returning confidential values.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of environment templates.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentTemplateListResource",
+ "description": "A page of reusable environment templates."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested environment definition was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent environment templates"
+ }
+ },
+ "post": {
+ "operationId": "createAgentEnvironmentTemplate",
+ "summary": "Creates reusable environment configuration without returning confidential setup commands or environment values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).",
+ "description": "Creates reusable environment configuration without returning confidential setup commands or environment values.",
+ "tags": [
+ "Agents"
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateEnvironmentTemplateParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created environment template.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentTemplateResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested environment definition was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create an agent environment template"
+ },
+ "parameters": [
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ]
+ }
+ },
+ "/agents/environments/templates/{environment_template_id}": {
+ "get": {
+ "operationId": "retrieveAgentEnvironmentTemplate",
+ "summary": "Retrieves reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).",
+ "description": "Retrieves reusable environment configuration without returning confidential values.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_template_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable environment template."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested environment template.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentTemplateResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested environment definition was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent environment template"
+ }
+ },
+ "post": {
+ "operationId": "updateAgentEnvironmentTemplate",
+ "summary": "Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).",
+ "description": "Updates reusable environment configuration without returning confidential values.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_template_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable environment template."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateEnvironmentTemplateParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The updated environment template.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/EnvironmentTemplateResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested environment definition was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current environment state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Update an agent environment template"
+ }
+ },
+ "delete": {
+ "operationId": "deleteAgentEnvironmentTemplate",
+ "summary": "Deletes reusable environment configuration and all confidential template inputs. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).",
+ "description": "Deletes reusable environment configuration and all confidential template inputs.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "environment_template_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the reusable environment template."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted environment template.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedEnvironmentTemplateResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested environment definition was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current environment state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete an agent environment template"
+ }
+ }
+ },
+ "/agents/sessions": {
+ "get": {
+ "operationId": "listAgentSessions",
+ "summary": "Lists managed agent sessions using ID-based pagination and the requested sort order. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).",
+ "description": "Lists managed agent sessions using ID-based pagination and the requested sort order.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 1
+ },
+ "description": "The maximum number of resources to return."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`."
+ },
+ {
+ "name": "agent_id",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Only return sessions whose root agent has this ID. Omit to return sessions for all agents."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of sessions.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionListResource",
+ "description": "A paginated list of sessions."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent sessions"
+ }
+ },
+ "post": {
+ "operationId": "createAgentSession",
+ "summary": "Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true. See [running sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions).",
+ "description": "Creates a managed agent session, optionally submits initial input, and returns the session or streams its events when stream is true.",
+ "tags": [
+ "Agents"
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateAgentSessionParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created session or its event stream.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionResource"
+ }
+ },
+ "text/event-stream": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionEvent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oai-streaming": {
+ "request_field": "stream",
+ "response_status_code": 201
+ },
+ "x-oaiMeta": {
+ "name": "Create an agent session"
+ },
+ "parameters": [
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ]
+ }
+ },
+ "/agents/sessions/{session_id}": {
+ "get": {
+ "operationId": "retrieveAgentSession",
+ "summary": "Retrieves the current state of a managed agent session. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).",
+ "description": "Retrieves the current state of a managed agent session.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested session.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent session"
+ }
+ },
+ "post": {
+ "operationId": "updateAgentSession",
+ "summary": "Updates session metadata. Omitted fields are unchanged. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).",
+ "description": "Updates session metadata. Omitted fields are unchanged.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/UpdateAgentSessionParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The updated session.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Update an agent session"
+ }
+ },
+ "delete": {
+ "operationId": "deleteAgentSession",
+ "summary": "Removes a managed agent session from the public API and returns a deletion confirmation. Physical cleanup may continue asynchronously. See [managing sessions](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage).",
+ "description": "Removes a managed agent session from the public API and returns a deletion confirmation. Physical cleanup may continue asynchronously.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted session.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedSessionResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete an agent session"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/artifacts": {
+ "get": {
+ "operationId": "listAgentSessionArtifacts",
+ "summary": "Lists immutable artifacts published by completed hosted session turns. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).",
+ "description": "Lists immutable artifacts published by completed hosted session turns.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam"
+ },
+ "description": "Sort by creation time and ID. Defaults to descending."
+ },
+ {
+ "name": "environment_id",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Restrict the listing to artifacts produced by this environment."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100
+ },
+ "description": "The maximum number of artifacts to return, between 1 and 100."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return artifacts after this immutable artifact ID."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of durable session artifacts.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionArtifactListResource",
+ "description": "A page of durable artifacts published by a session."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent session artifacts"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/artifacts/{artifact_id}": {
+ "get": {
+ "operationId": "retrieveAgentSessionArtifact",
+ "summary": "Retrieves immutable metadata for one durable session artifact. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).",
+ "description": "Retrieves immutable metadata for one durable session artifact.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session that owns the artifact."
+ },
+ {
+ "name": "artifact_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The immutable session artifact ID."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested session artifact.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionArtifactResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent session artifact"
+ }
+ },
+ "delete": {
+ "operationId": "deleteAgentSessionArtifact",
+ "summary": "Deletes an immutable session artifact without deleting its live environment file or original Files API object. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).",
+ "description": "Deletes an immutable session artifact without deleting its live environment file or original Files API object.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session that owns the artifact."
+ },
+ {
+ "name": "artifact_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The immutable session artifact ID."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted session artifact.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedSessionArtifactResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete an agent session artifact"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/artifacts/{artifact_id}/content": {
+ "get": {
+ "operationId": "retrieveAgentSessionArtifactContent",
+ "summary": "Downloads immutable session artifact bytes after the execution environment expires. See [session artifacts](https://developers.openai.com/api/docs/guides/agents-api/environments/files#openai-hosted-artifacts).",
+ "description": "Downloads immutable session artifact bytes after the execution environment expires.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session that owns the artifact."
+ },
+ {
+ "name": "artifact_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The immutable session artifact ID."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The immutable artifact contents.",
+ "content": {
+ "application/octet-stream": {
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve agent session artifact content"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/events": {
+ "get": {
+ "operationId": "listAgentSessionEvents",
+ "summary": "Streams live events for an agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events).",
+ "description": "Streams live events for an agent session.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A live stream of session events.",
+ "content": {
+ "text/event-stream": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionEvent"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oai-streaming": {
+ "request_field": null,
+ "response_status_code": 200
+ },
+ "x-oaiMeta": {
+ "name": "Stream agent session events"
+ }
+ },
+ "post": {
+ "operationId": "createAgentSessionEvents",
+ "summary": "Submits message, cancellation, or tool-result events to a managed agent session. See [session events](https://developers.openai.com/api/docs/guides/agents-api/sessions/events).",
+ "description": "Submits message, cancellation, or tool-result events to a managed agent session.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "Idempotency-Key",
+ "in": "header",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "description": "An optional client-generated key that makes retries of submitted messages idempotent."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateSessionEventsParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "202": {
+ "description": "The events were accepted."
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create agent session input events"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/items": {
+ "get": {
+ "operationId": "listAgentSessionItems",
+ "summary": "Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history. See [inspecting agent output](https://developers.openai.com/api/docs/guides/agents-api/observability).",
+ "description": "Lists items produced by the session's root agent, including its interactions with subagents. Each subagent has its own item history.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of session items.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionItemListResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required Responses permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent session items"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/turns": {
+ "get": {
+ "operationId": "listAgentSessionTurns",
+ "summary": "Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).",
+ "description": "Lists turns by creation time and turn ID. The after cursor is exclusive in the selected order.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 100,
+ "default": 20
+ },
+ "description": "The maximum number of resources to return, between 1 and 100. Defaults to 20."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "The order in which resources are returned. Defaults to `desc`."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of session turns.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/SessionTurnListResource",
+ "description": "A page of turns from an agent session or subagent."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List agent session turns"
+ }
+ }
+ },
+ "/agents/sessions/{session_id}/turns/{turn_id}": {
+ "get": {
+ "operationId": "retrieveAgentSessionTurn",
+ "summary": "Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session. See [session turns](https://developers.openai.com/api/docs/guides/agents-api/sessions/manage#inspect-session-turns).",
+ "description": "Retrieves a turn's current status, timestamps, usage, and error. Returns 404 if the turn does not belong to the session.",
+ "tags": [
+ "Agents"
+ ],
+ "parameters": [
+ {
+ "name": "session_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the session that owns the turn."
+ },
+ {
+ "name": "turn_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the turn."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested turn.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/TurnResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested session or event was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current session state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve an agent session turn"
+ }
+ }
+ },
+ "/vaults": {
+ "get": {
+ "operationId": "listVaults",
+ "summary": "Lists vaults using ID-based pagination. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Lists vaults using ID-based pagination.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 0
+ },
+ "description": "The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100."
+ },
+ {
+ "name": "status",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/VaultStatusFilterParam"
+ },
+ "description": "Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of vaults.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultListResource",
+ "description": "A page of vaults."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List vaults"
+ }
+ },
+ "post": {
+ "operationId": "createVault",
+ "summary": "Creates a vault for the current project. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Creates a vault for the current project.",
+ "tags": [
+ "Vaults"
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateVaultParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created vault.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create a vault"
+ },
+ "parameters": [
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ]
+ }
+ },
+ "/vaults/{vault_id}": {
+ "get": {
+ "operationId": "retrieveVault",
+ "summary": "Retrieves a vault by its ID. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Retrieves a vault by its ID.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested vault.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve a vault"
+ }
+ },
+ "delete": {
+ "operationId": "deleteVault",
+ "summary": "Deletes a vault and all its credentials. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Deletes a vault and all its credentials.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted vault.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedVaultResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete a vault"
+ }
+ }
+ },
+ "/vaults/{vault_id}/credentials": {
+ "get": {
+ "operationId": "listVaultCredentials",
+ "summary": "Lists a vault's credentials using ID-based pagination without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Lists a vault's credentials using ID-based pagination without returning secret values.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/ListOrderParam",
+ "default": "desc"
+ },
+ "description": "Sort order by the `created_at` timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `desc`."
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 0
+ },
+ "description": "The maximum number of resources to return. Defaults to 20. Values are clamped between 1 and 100."
+ },
+ {
+ "name": "status",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "$ref": "#/components/schemas/VaultStatusFilterParam"
+ },
+ "description": "Filter by one status or a list, such as `status=active` or `status[]=active&status[]=archived`. Both statuses are included by default."
+ },
+ {
+ "name": "after",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "Return resources after this resource ID in the selected order."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "A page of vault credentials.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultCredentialListResource",
+ "description": "A page of credentials in a vault."
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "List vault credentials"
+ }
+ },
+ "post": {
+ "operationId": "createVaultCredential",
+ "summary": "Creates a vault credential. Secret values are write-only and are never returned. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Creates a vault credential. Secret values are write-only and are never returned.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CreateVaultCredentialParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "201": {
+ "description": "The created vault credential without secret values.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultCredentialResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Create a vault credential"
+ }
+ }
+ },
+ "/vaults/{vault_id}/credentials/{credential_id}": {
+ "get": {
+ "operationId": "retrieveVaultCredential",
+ "summary": "Retrieves vault credential metadata without returning secret values. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Retrieves vault credential metadata without returning secret values.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "credential_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault credential."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The requested vault credential without secret values.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultCredentialResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Retrieve a vault credential"
+ }
+ },
+ "post": {
+ "operationId": "rotateVaultCredential",
+ "summary": "Rotates a vault credential's write-only secret and returns only credential metadata. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Rotates a vault credential's write-only secret and returns only credential metadata.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "credential_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault credential."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/RotateVaultCredentialParams"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "The rotated vault credential without secret values.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/VaultCredentialResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Rotate a vault credential"
+ }
+ },
+ "delete": {
+ "operationId": "deleteVaultCredential",
+ "summary": "Deletes a vault credential. See [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults).",
+ "description": "Deletes a vault credential.",
+ "tags": [
+ "Vaults"
+ ],
+ "parameters": [
+ {
+ "name": "vault_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault."
+ },
+ {
+ "name": "credential_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "description": "The ID of the vault credential."
+ },
+ {
+ "name": "OpenAI-Beta",
+ "in": "header",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "const": "agents=v1"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "The deleted vault credential.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/DeletedVaultCredentialResource"
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "The request was invalid.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "401": {
+ "description": "Authentication or project context was missing.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "403": {
+ "description": "The API key lacks the required management permission.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "404": {
+ "description": "The requested vault or credential was not found.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "409": {
+ "description": "The request conflicted with the current vault state.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "500": {
+ "description": "An internal error occurred.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ },
+ "503": {
+ "description": "The service is temporarily unavailable.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse-2"
+ }
+ }
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "name": "Delete a vault credential"
+ }
+ }
+ }
+ },
+ "webhooks": {
+ "batch_cancelled": {
+ "post": {
+ "description": "Sent when a batch has been cancelled.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookBatchCancelled"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "batch_completed": {
+ "post": {
+ "description": "Sent when a batch has completed processing.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookBatchCompleted"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "batch_expired": {
+ "post": {
+ "description": "Sent when a batch has expired before completion.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookBatchExpired"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "batch_failed": {
+ "post": {
+ "description": "Sent when a batch has failed.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookBatchFailed"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "eval_run_canceled": {
+ "post": {
+ "description": "Sent when an eval run has been canceled.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookEvalRunCanceled"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "eval_run_failed": {
+ "post": {
+ "description": "Sent when an eval run has failed.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookEvalRunFailed"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "eval_run_succeeded": {
+ "post": {
+ "description": "Sent when an eval run has succeeded.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookEvalRunSucceeded"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "fine_tuning_job_cancelled": {
+ "post": {
+ "description": "Sent when a fine-tuning job has been cancelled.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookFineTuningJobCancelled"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "fine_tuning_job_failed": {
+ "post": {
+ "description": "Sent when a fine-tuning job has failed.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookFineTuningJobFailed"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "fine_tuning_job_succeeded": {
+ "post": {
+ "description": "Sent when a fine-tuning job has succeeded.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookFineTuningJobSucceeded"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "live_call_incoming": {
+ "post": {
+ "deprecated": true,
+ "description": "Deprecated: use `live.transport.incoming`. Retained only for existing subscriptions.\nSent when an incoming API SIP session is available for Live acceptance.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookLiveCallIncoming"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "live_transport_incoming": {
+ "post": {
+ "description": "Sent when an incoming API SIP session is available for Live acceptance.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookLiveTransportIncoming"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "realtime_call_incoming": {
+ "post": {
+ "description": "Sent when an incoming API SIP session is available for Realtime acceptance.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookRealtimeCallIncoming"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200\nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "response_cancelled": {
+ "post": {
+ "description": "Sent when a background response has been cancelled.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookResponseCancelled"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "response_completed": {
+ "post": {
+ "description": "Sent when a background response has completed successfully.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookResponseCompleted"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried. \n"
+ }
+ }
+ }
+ },
+ "response_failed": {
+ "post": {
+ "description": "Sent when a background response has failed.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookResponseFailed"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "response_incomplete": {
+ "post": {
+ "description": "Sent when a background response is incomplete.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookResponseIncomplete"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return a 200 status code to acknowledge receipt of the event. Non-200 \nstatus codes will be retried.\n"
+ }
+ }
+ }
+ },
+ "safety_alert_created": {
+ "post": {
+ "description": "Sent when an approved safety alert is available for an API project.\nRetrieve the alert with a project API key granted `api.safety.alerts.read`.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookSafetyAlertCreated"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried."
+ }
+ }
+ }
+ },
+ "safety_org_alert_created": {
+ "post": {
+ "description": "Sent when an approved safety alert is available for an enterprise workspace.\nRetrieve the alert from `https://api.chatgpt.com/v1/safety/alerts/{id}` with\nan administrator API key for the workspace's backing organization granted\n`chatgpt.enterprise.safety_alerts.read`.\n",
+ "requestBody": {
+ "description": "The event payload sent by the API.",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WebhookSafetyOrgAlertCreated"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Return any 2xx status code to acknowledge receipt. A 410 Gone response also stops retries; other non-2xx responses are retried."
+ }
+ }
+ }
+ }
+ },
+ "components": {
+ "schemas": {
+ "CreateFileRequest": {
+ "type": "object",
+ "additionalProperties": false,
+ "properties": {
+ "file": {
+ "description": "The File object (not file name) to be uploaded.\n",
+ "type": "string",
+ "format": "binary"
+ },
+ "purpose": {
+ "description": "The intended purpose of the uploaded file. One of:\n- `assistants`: Used in the Assistants API\n- `batch`: Used in the Batch API\n- `fine-tune`: Used for fine-tuning\n- `vision`: Images used for vision fine-tuning\n- `user_data`: Flexible file type for any purpose\n- `evals`: Used for eval data sets\n",
+ "type": "string",
+ "enum": [
+ "assistants",
+ "batch",
+ "fine-tune",
+ "vision",
+ "user_data",
+ "evals"
+ ]
+ },
+ "expires_after": {
+ "$ref": "#/components/schemas/FileExpirationAfter"
+ }
+ },
+ "required": [
+ "file",
+ "purpose"
+ ]
+ },
+ "DeleteFileResponse": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "file"
+ ],
+ "x-stainless-const": true
+ },
+ "deleted": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ]
+ },
+ "Error": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "message": {
+ "type": "string"
+ },
+ "param": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "type": {
+ "type": "string"
+ },
+ "misalignment": {
+ "$ref": "#/components/schemas/MisalignmentErrorDetailsResource"
+ }
+ },
+ "required": [
+ "type",
+ "message",
+ "param",
+ "code"
+ ]
+ },
+ "ErrorResponse": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "$ref": "#/components/schemas/Error"
+ }
+ },
+ "required": [
+ "error"
+ ]
+ },
+ "FileExpirationAfter": {
+ "type": "object",
+ "title": "File expiration policy",
+ "description": "The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.",
+ "properties": {
+ "anchor": {
+ "description": "Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.",
+ "type": "string",
+ "enum": [
+ "created_at"
+ ],
+ "x-stainless-const": true
+ },
+ "seconds": {
+ "description": "The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).",
+ "type": "integer",
+ "format": "int64",
+ "minimum": 3600,
+ "maximum": 2592000
+ }
+ },
+ "required": [
+ "anchor",
+ "seconds"
+ ]
+ },
+ "ListFilesResponse": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "example": "list"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/OpenAIFile"
+ }
+ },
+ "first_id": {
+ "type": "string",
+ "example": "file-abc123"
+ },
+ "last_id": {
+ "type": "string",
+ "example": "file-abc456"
+ },
+ "has_more": {
+ "type": "boolean",
+ "example": false
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ]
+ },
+ "OpenAIFile": {
+ "title": "OpenAIFile",
+ "description": "The `File` object represents a document that has been uploaded to OpenAI.",
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "The file identifier, which can be referenced in the API endpoints."
+ },
+ "bytes": {
+ "type": "integer",
+ "description": "The size of the file, in bytes."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "unixtime",
+ "description": "The Unix timestamp (in seconds) for when the file was created."
+ },
+ "expires_at": {
+ "type": "integer",
+ "format": "unixtime",
+ "description": "The Unix timestamp (in seconds) for when the file will expire."
+ },
+ "filename": {
+ "type": "string",
+ "description": "The name of the file."
+ },
+ "object": {
+ "type": "string",
+ "description": "The object type, which is always `file`.",
+ "enum": [
+ "file"
+ ],
+ "x-stainless-const": true
+ },
+ "purpose": {
+ "type": "string",
+ "description": "The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.",
+ "enum": [
+ "assistants",
+ "assistants_output",
+ "batch",
+ "batch_output",
+ "fine-tune",
+ "fine-tune-results",
+ "vision",
+ "user_data"
+ ]
+ },
+ "status": {
+ "type": "string",
+ "deprecated": true,
+ "description": "Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.",
+ "enum": [
+ "uploaded",
+ "processed",
+ "error"
+ ]
+ },
+ "status_details": {
+ "type": "string",
+ "deprecated": true,
+ "description": "Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "bytes",
+ "created_at",
+ "filename",
+ "purpose",
+ "status"
+ ],
+ "x-oaiMeta": {
+ "name": "The file object",
+ "example": "{\n \"id\": \"file-abc123\",\n \"object\": \"file\",\n \"bytes\": 120000,\n \"created_at\": 1677610602,\n \"expires_at\": 1680202602,\n \"filename\": \"salesOverview.pdf\",\n \"purpose\": \"assistants\",\n}\n"
+ }
+ },
+ "_MisalignmentErrorType": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "string",
+ "enum": [
+ "potentially_unintended_data_transfer",
+ "potentially_unintended_data_access",
+ "potentially_unintended_destructive_activity",
+ "other"
+ ]
+ }
+ ]
+ },
+ "_MisalignmentSteer": {
+ "properties": {
+ "message": {
+ "type": "string",
+ "description": "The public continuation instruction."
+ }
+ },
+ "type": "object",
+ "required": [
+ "message"
+ ]
+ },
+ "MisalignmentErrorDetailsResource": {
+ "properties": {
+ "error_type": {
+ "$ref": "#/components/schemas/_MisalignmentErrorType",
+ "description": "An optional classification; clients must accept additional values."
+ },
+ "detailed_explanation": {
+ "type": "string",
+ "description": "The public explanation for this block."
+ },
+ "steer": {
+ "$ref": "#/components/schemas/_MisalignmentSteer",
+ "description": "An optional public continuation instruction."
+ }
+ },
+ "type": "object",
+ "required": []
+ },
+ "OrderEnum": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ]
+ },
+ "SkillResource": {
+ "properties": {
+ "id": {
+ "type": "string",
+ "description": "Unique identifier for the skill."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "skill"
+ ],
+ "description": "The object type, which is `skill`.",
+ "default": "skill",
+ "x-stainless-const": true
+ },
+ "name": {
+ "type": "string",
+ "description": "Name of the skill."
+ },
+ "description": {
+ "type": "string",
+ "description": "Description of the skill."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "unixtime",
+ "description": "Unix timestamp (seconds) for when the skill was created."
+ },
+ "default_version": {
+ "type": "string",
+ "description": "Default version for the skill."
+ },
+ "latest_version": {
+ "type": "string",
+ "description": "Latest version for the skill."
+ }
+ },
+ "type": "object",
+ "required": [
+ "id",
+ "object",
+ "name",
+ "description",
+ "created_at",
+ "default_version",
+ "latest_version"
+ ]
+ },
+ "SkillListResource": {
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "description": "The type of object returned, must be `list`.",
+ "default": "list",
+ "x-stainless-const": true
+ },
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SkillResource"
+ },
+ "type": "array",
+ "description": "A list of items"
+ },
+ "first_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "description": "The ID of the first item in the list."
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "last_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "description": "The ID of the last item in the list."
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more items available."
+ }
+ },
+ "type": "object",
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ]
+ },
+ "CreateSkillBody": {
+ "properties": {
+ "files": {
+ "oneOf": [
+ {
+ "items": {
+ "type": "string",
+ "format": "binary"
+ },
+ "type": "array",
+ "maxItems": 500,
+ "description": "Skill files to upload (directory upload) or a single zip file."
+ },
+ {
+ "type": "string",
+ "format": "binary",
+ "description": "Skill zip file to upload."
+ }
+ ]
+ }
+ },
+ "type": "object",
+ "required": [
+ "files"
+ ],
+ "title": "Create skill request",
+ "description": "Uploads a skill either as a directory (multipart `files[]`) or as a single zip file."
+ },
+ "SetDefaultSkillVersionBody": {
+ "properties": {
+ "default_version": {
+ "type": "string",
+ "description": "The skill version number to set as default."
+ }
+ },
+ "type": "object",
+ "required": [
+ "default_version"
+ ],
+ "title": "Update skill request",
+ "description": "Updates the default version pointer for a skill."
+ },
+ "DeletedSkillResource": {
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "skill.deleted"
+ ],
+ "default": "skill.deleted",
+ "x-stainless-const": true
+ },
+ "deleted": {
+ "type": "boolean"
+ },
+ "id": {
+ "type": "string"
+ }
+ },
+ "type": "object",
+ "required": [
+ "object",
+ "deleted",
+ "id"
+ ]
+ },
+ "SkillVersionResource": {
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "skill.version"
+ ],
+ "description": "The object type, which is `skill.version`.",
+ "default": "skill.version",
+ "x-stainless-const": true
+ },
+ "id": {
+ "type": "string",
+ "description": "Unique identifier for the skill version."
+ },
+ "skill_id": {
+ "type": "string",
+ "description": "Identifier of the skill for this version."
+ },
+ "version": {
+ "type": "string",
+ "description": "Version number for this skill."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "unixtime",
+ "description": "Unix timestamp (seconds) for when the version was created."
+ },
+ "name": {
+ "type": "string",
+ "description": "Name of the skill version."
+ },
+ "description": {
+ "type": "string",
+ "description": "Description of the skill version."
+ }
+ },
+ "type": "object",
+ "required": [
+ "object",
+ "id",
+ "skill_id",
+ "version",
+ "created_at",
+ "name",
+ "description"
+ ]
+ },
+ "SkillVersionListResource": {
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "description": "The type of object returned, must be `list`.",
+ "default": "list",
+ "x-stainless-const": true
+ },
+ "data": {
+ "items": {
+ "$ref": "#/components/schemas/SkillVersionResource"
+ },
+ "type": "array",
+ "description": "A list of items"
+ },
+ "first_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "description": "The ID of the first item in the list."
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "last_id": {
+ "anyOf": [
+ {
+ "type": "string",
+ "description": "The ID of the last item in the list."
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more items available."
+ }
+ },
+ "type": "object",
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ]
+ },
+ "CreateSkillVersionBody": {
+ "properties": {
+ "files": {
+ "oneOf": [
+ {
+ "items": {
+ "type": "string",
+ "format": "binary"
+ },
+ "type": "array",
+ "maxItems": 500,
+ "description": "Skill files to upload (directory upload) or a single zip file."
+ },
+ {
+ "type": "string",
+ "format": "binary",
+ "description": "Skill zip file to upload."
+ }
+ ]
+ },
+ "default": {
+ "type": "boolean",
+ "description": "Whether to set this version as the default."
+ }
+ },
+ "type": "object",
+ "required": [
+ "files"
+ ],
+ "title": "Create skill version request",
+ "description": "Uploads a new immutable version of a skill."
+ },
+ "DeletedSkillVersionResource": {
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "skill.version.deleted"
+ ],
+ "default": "skill.version.deleted",
+ "x-stainless-const": true
+ },
+ "deleted": {
+ "type": "boolean"
+ },
+ "id": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string",
+ "description": "The deleted skill version."
+ }
+ },
+ "type": "object",
+ "required": [
+ "object",
+ "deleted",
+ "id",
+ "version"
+ ]
+ },
+ "EnvironmentTypeResource": {
+ "type": "string",
+ "enum": [
+ "openai_hosted",
+ "self_hosted"
+ ],
+ "description": "The kind of execution environment."
+ },
+ "EnvironmentStatusResource": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "connected",
+ "disconnected",
+ "expired",
+ "failed"
+ ],
+ "description": "The public lifecycle status of an execution environment."
+ },
+ "HostedEnvironmentFileResourceFileId": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "file_id"
+ ],
+ "default": "file_id",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `file_id`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The session-scoped ID of the file in the execution environment."
+ },
+ "file_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the uploaded file."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The file's absolute path inside the environment."
+ },
+ "size_bytes": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "description": "The decoded file size in bytes."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "file_id",
+ "path",
+ "size_bytes"
+ ],
+ "additionalProperties": false,
+ "description": "A file copied from the OpenAI Files API."
+ },
+ "HostedEnvironmentFileResourceInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The session-scoped ID of the file in the execution environment."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The file's absolute path inside the environment."
+ },
+ "size_bytes": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "description": "The decoded file size in bytes."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "path",
+ "size_bytes"
+ ],
+ "additionalProperties": false,
+ "description": "A file supplied inline when the session was created."
+ },
+ "HostedEnvironmentFileResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedEnvironmentFileResourceFileId"
+ },
+ {
+ "$ref": "#/components/schemas/HostedEnvironmentFileResourceInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "file_id": "#/components/schemas/HostedEnvironmentFileResourceFileId",
+ "inline": "#/components/schemas/HostedEnvironmentFileResourceInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "file_id",
+ "inline"
+ ],
+ "description": "Metadata for a file materialized in an OpenAI-hosted execution environment."
+ },
+ "HostedSkillResourceSkillReference": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "skill_reference"
+ ],
+ "default": "skill_reference",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `skill_reference`."
+ },
+ "skill_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The referenced skill ID."
+ },
+ "version": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The concrete skill version installed for this session."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed skill name."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed skill description."
+ }
+ },
+ "required": [
+ "type",
+ "skill_id",
+ "version",
+ "name",
+ "description"
+ ],
+ "additionalProperties": false,
+ "description": "A skill installed from the Skills API."
+ },
+ "HostedSkillResourceInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed skill name."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed skill description."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description"
+ ],
+ "additionalProperties": false,
+ "description": "A skill installed from an inline ZIP archive."
+ },
+ "HostedSkillResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedSkillResourceSkillReference"
+ },
+ {
+ "$ref": "#/components/schemas/HostedSkillResourceInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "skill_reference": "#/components/schemas/HostedSkillResourceSkillReference",
+ "inline": "#/components/schemas/HostedSkillResourceInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "skill_reference",
+ "inline"
+ ],
+ "description": "A skill installed in an OpenAI-hosted environment."
+ },
+ "HostedPluginResourceInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed plugin name."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The installed plugin description."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description"
+ ],
+ "additionalProperties": false,
+ "description": "A plugin installed from an inline ZIP archive."
+ },
+ "HostedPluginResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedPluginResourceInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "inline": "#/components/schemas/HostedPluginResourceInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "inline"
+ ],
+ "description": "A plugin installed in an OpenAI-hosted environment."
+ },
+ "PublicEnvironmentResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the environment."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.environment"
+ ],
+ "default": "agent.environment",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.environment`."
+ },
+ "type": {
+ "$ref": "#/components/schemas/EnvironmentTypeResource",
+ "description": "Whether the environment is hosted by OpenAI or by the application."
+ },
+ "status": {
+ "$ref": "#/components/schemas/EnvironmentStatusResource",
+ "description": "The current environment connection status."
+ },
+ "files": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Files installed in the environment, without their contents."
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedSkillResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Skills installed in the environment, without their archive contents."
+ },
+ "plugins": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Plugins installed in the environment, without their archive contents."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "type",
+ "status",
+ "files",
+ "skills",
+ "plugins"
+ ],
+ "additionalProperties": false,
+ "description": "Safe metadata for a first-class execution environment."
+ },
+ "ErrorBodyResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The error type."
+ },
+ "code": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A machine-readable error code."
+ },
+ "message": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A human-readable error message."
+ },
+ "param": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The request parameter that caused the error, or null for a request-wide error."
+ }
+ },
+ "required": [
+ "type",
+ "code",
+ "message",
+ "param"
+ ],
+ "additionalProperties": false,
+ "description": "Details about an API error."
+ },
+ "ErrorResponse-2": {
+ "type": "object",
+ "properties": {
+ "error": {
+ "$ref": "#/components/schemas/ErrorBodyResource",
+ "description": "The error returned by the API."
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "additionalProperties": false,
+ "description": "An API error response."
+ },
+ "ListOrderParam": {
+ "type": "string",
+ "enum": [
+ "asc",
+ "desc"
+ ],
+ "x-enumDescriptions": [
+ "Returns resources in ascending order.",
+ "Returns resources in descending order."
+ ],
+ "description": "The order in which paginated resources are returned."
+ },
+ "EnvironmentFilePageObjectResource": {
+ "type": "string",
+ "enum": [
+ "page"
+ ],
+ "default": "page",
+ "x-stainless-const": true,
+ "description": "The object type for a page of files in an execution environment."
+ },
+ "EnvironmentFileResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.environment.file"
+ ],
+ "default": "agent.environment.file",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.environment.file`."
+ },
+ "environment_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the environment containing this file."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The absolute file path inside the environment's workspace."
+ },
+ "size_bytes": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "description": "The file size in bytes."
+ }
+ },
+ "required": [
+ "object",
+ "environment_id",
+ "path",
+ "size_bytes"
+ ],
+ "additionalProperties": false,
+ "description": "A live file in an execution environment."
+ },
+ "EnvironmentFileListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "$ref": "#/components/schemas/EnvironmentFilePageObjectResource",
+ "description": "The object type. Always `page`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/EnvironmentFileResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Files available on the current page."
+ },
+ "next": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The opaque cursor to use when requesting the next page, if any."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether more files follow this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "next",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A paginated list of live execution environment files."
+ },
+ "HostedEnvironmentFileParamFileId": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "file_id"
+ ],
+ "default": "file_id",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `file_id`."
+ },
+ "file_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256,
+ "description": "The ID of the uploaded file."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 4096,
+ "description": "The absolute destination path inside `/workspace`."
+ }
+ },
+ "required": [
+ "type",
+ "file_id",
+ "path"
+ ],
+ "additionalProperties": false,
+ "description": "A file previously uploaded through the OpenAI Files API."
+ },
+ "HostedEnvironmentFileParamInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "data": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 6990508,
+ "description": "The standard-base64-encoded file contents."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 4096,
+ "description": "The absolute destination path inside `/workspace`."
+ }
+ },
+ "required": [
+ "type",
+ "data",
+ "path"
+ ],
+ "additionalProperties": false,
+ "description": "A file supplied directly as standard-base64 data."
+ },
+ "HostedEnvironmentFileParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParamFileId"
+ },
+ {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParamInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "file_id": "#/components/schemas/HostedEnvironmentFileParamFileId",
+ "inline": "#/components/schemas/HostedEnvironmentFileParamInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "file_id",
+ "inline"
+ ],
+ "description": "A file materialized in an OpenAI-hosted execution environment."
+ },
+ "SubagentObjectResource": {
+ "type": "string",
+ "enum": [
+ "agent.session.subagent"
+ ],
+ "default": "agent.session.subagent",
+ "x-stainless-const": true,
+ "description": "The object type for a subagent."
+ },
+ "OutputTextResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "output_text"
+ ],
+ "default": "output_text",
+ "x-stainless-const": true,
+ "description": "The content type. Always `output_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The text produced by the agent."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "A text content part produced by the agent."
+ },
+ "EncryptedContentResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "encrypted_content"
+ ],
+ "default": "encrypted_content",
+ "x-stainless-const": true,
+ "description": "The content type. Always `encrypted_content`."
+ },
+ "encrypted_content": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The encrypted content payload."
+ }
+ },
+ "required": [
+ "type",
+ "encrypted_content"
+ ],
+ "additionalProperties": false,
+ "description": "Encrypted content exchanged between agents."
+ },
+ "AgentContentResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/OutputTextResource"
+ },
+ {
+ "$ref": "#/components/schemas/EncryptedContentResource"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "output_text": "#/components/schemas/OutputTextResource",
+ "encrypted_content": "#/components/schemas/EncryptedContentResource"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "output_text",
+ "encrypted_content"
+ ],
+ "description": "A plaintext or encrypted content part exchanged between agents."
+ },
+ "SubagentStatusResource": {
+ "type": "string",
+ "enum": [
+ "active",
+ "closed"
+ ],
+ "x-enumDescriptions": [
+ "The subagent remains available, including while idle between turns.",
+ "The subagent is closed."
+ ],
+ "description": "The current status of a subagent."
+ },
+ "SubagentResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the subagent."
+ },
+ "object": {
+ "$ref": "#/components/schemas/SubagentObjectResource",
+ "description": "The object type. Always `agent.session.subagent`."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session that owns the subagent."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The runner-assigned nickname, or null when unavailable."
+ },
+ "instructions": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/AgentContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Initial task content, or null when unavailable. Text may contain placeholders for images or audio when only a preview is available."
+ },
+ "parent_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent that created this subagent."
+ },
+ "status": {
+ "$ref": "#/components/schemas/SubagentStatusResource",
+ "description": "The current status of the subagent."
+ },
+ "opened_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the subagent was first opened. Resuming does not change it."
+ },
+ "closed_at": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the subagent was closed. Null while active, including after resume."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "session_id",
+ "name",
+ "instructions",
+ "parent_agent_id",
+ "status",
+ "opened_at",
+ "closed_at"
+ ],
+ "additionalProperties": false,
+ "description": "A subagent created within a session."
+ },
+ "SessionMessageRoleResource": {
+ "type": "string",
+ "enum": [
+ "user",
+ "assistant"
+ ],
+ "description": "The author of a session message."
+ },
+ "MessageContentResourceInputText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_text"
+ ],
+ "default": "input_text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The text supplied by the user."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Text supplied by the user."
+ },
+ "MessageContentResourceInputImage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_image"
+ ],
+ "default": "input_image",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_image`."
+ },
+ "image_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The URL of the image supplied by the user, which may be a base64-encoded data URL."
+ }
+ },
+ "required": [
+ "type",
+ "image_url"
+ ],
+ "additionalProperties": false,
+ "description": "An image supplied by the user."
+ },
+ "MessageContentResourceOutputText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "output_text"
+ ],
+ "default": "output_text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `output_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The text produced by the assistant."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Text produced by the assistant."
+ },
+ "MessageContentResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/MessageContentResourceInputText"
+ },
+ {
+ "$ref": "#/components/schemas/MessageContentResourceInputImage"
+ },
+ {
+ "$ref": "#/components/schemas/MessageContentResourceOutputText"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "input_text": "#/components/schemas/MessageContentResourceInputText",
+ "input_image": "#/components/schemas/MessageContentResourceInputImage",
+ "output_text": "#/components/schemas/MessageContentResourceOutputText"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "input_text",
+ "input_image",
+ "output_text"
+ ],
+ "description": "A content part in a session message."
+ },
+ "OutputItemStatusResource": {
+ "type": "string",
+ "enum": [
+ "in_progress",
+ "completed",
+ "incomplete"
+ ],
+ "x-enumDescriptions": [
+ "The item is in progress.",
+ "The item is complete.",
+ "The item stopped before completing."
+ ],
+ "description": "The status of an agent output item."
+ },
+ "MessagePhaseResource": {
+ "type": "string",
+ "enum": [
+ "commentary",
+ "final_answer"
+ ],
+ "x-enumDescriptions": [
+ "Commentary produced while the agent works.",
+ "The agent's final answer."
+ ],
+ "description": "The phase of an assistant message."
+ },
+ "MessageItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "message"
+ ],
+ "default": "message",
+ "x-stainless-const": true,
+ "description": "The item type. Always `message`."
+ },
+ "id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of this item, or null for legacy user messages whose ID was not recorded."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "role": {
+ "$ref": "#/components/schemas/SessionMessageRoleResource",
+ "description": "The role of the message author."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/MessageContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The content of the message. User messages contain input text or images; assistant messages contain output text."
+ },
+ "status": {
+ "$ref": "#/components/schemas/OutputItemStatusResource",
+ "description": "The status of the message. User messages are always `completed`."
+ },
+ "phase": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/MessagePhaseResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The phase of an assistant message. Null for user messages."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "role",
+ "content",
+ "status",
+ "phase"
+ ],
+ "additionalProperties": false,
+ "description": "A user or assistant message recorded in a session."
+ },
+ "SummaryTextResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "summary_text"
+ ],
+ "default": "summary_text",
+ "x-stainless-const": true,
+ "description": "The content type. Always `summary_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The reasoning summary text."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "A reasoning summary content part."
+ },
+ "ReasoningItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "reasoning"
+ ],
+ "default": "reasoning",
+ "x-stainless-const": true,
+ "description": "The item type. Always `reasoning`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reasoning item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "summary": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SummaryTextResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The reasoning summaries produced by the agent."
+ },
+ "status": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/OutputItemStatusResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The status of the reasoning item."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "summary",
+ "status"
+ ],
+ "additionalProperties": false,
+ "description": "A reasoning item produced by the agent."
+ },
+ "FunctionCallStatusResource": {
+ "type": "string",
+ "enum": [
+ "in_progress",
+ "completed",
+ "failed",
+ "incomplete"
+ ],
+ "x-enumDescriptions": [
+ "The call is in progress.",
+ "The call completed successfully.",
+ "The call failed.",
+ "The call stopped before completing."
+ ],
+ "description": "The status of a tool call."
+ },
+ "FunctionCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function_call"
+ ],
+ "default": "function_call",
+ "x-stainless-const": true,
+ "description": "The item type. Always `function_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the function call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "call_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID used to submit the function result."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The name of the function to call."
+ },
+ "arguments": {
+ "description": "The arguments to pass to the function."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the function call."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "call_id",
+ "name",
+ "arguments",
+ "status"
+ ],
+ "additionalProperties": false,
+ "description": "A function call produced by the agent."
+ },
+ "InputContentResourceInputText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_text"
+ ],
+ "default": "input_text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The text supplied to the agent."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Text input recorded in a session item."
+ },
+ "InputContentResourceInputImage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_image"
+ ],
+ "default": "input_image",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_image`."
+ },
+ "image_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The URL of the image supplied to the agent, which may be a base64-encoded data URL."
+ }
+ },
+ "required": [
+ "type",
+ "image_url"
+ ],
+ "additionalProperties": false,
+ "description": "Image input recorded in a session item."
+ },
+ "InputContentResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/InputContentResourceInputText"
+ },
+ {
+ "$ref": "#/components/schemas/InputContentResourceInputImage"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "input_text": "#/components/schemas/InputContentResourceInputText",
+ "input_image": "#/components/schemas/InputContentResourceInputImage"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "input_text",
+ "input_image"
+ ],
+ "description": "User-provided content recorded in a session item."
+ },
+ "FunctionCallOutputResource": {
+ "oneOf": [
+ {
+ "type": "string",
+ "minLength": 0
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/InputContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000
+ }
+ ],
+ "description": "The text or model-input content supplied as a function result."
+ },
+ "FunctionCallOutputItemResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the function call output item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "function_call_output"
+ ],
+ "default": "function_call_output",
+ "x-stainless-const": true,
+ "description": "The item type. Always `function_call_output`."
+ },
+ "call_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the function call that produced this output."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the function call."
+ },
+ "output": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/FunctionCallOutputResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The function result, if the call succeeded."
+ },
+ "error": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The error message, if the call failed."
+ }
+ },
+ "required": [
+ "id",
+ "turn_id",
+ "type",
+ "call_id",
+ "status",
+ "output",
+ "error"
+ ],
+ "additionalProperties": false,
+ "description": "The result supplied for a function call."
+ },
+ "AgentMessageItemResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent_message"
+ ],
+ "default": "agent_message",
+ "x-stainless-const": true,
+ "description": "The item type. Always `agent_message`."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID or name of the sending agent."
+ },
+ "recipient_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID or name of the receiving agent."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The content exchanged between the agents."
+ }
+ },
+ "required": [
+ "id",
+ "turn_id",
+ "type",
+ "sender_agent_id",
+ "recipient_agent_id",
+ "content"
+ ],
+ "additionalProperties": false,
+ "description": "A message exchanged between agent threads."
+ },
+ "McpCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp_call"
+ ],
+ "default": "mcp_call",
+ "x-stainless-const": true,
+ "description": "The item type. Always `mcp_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the MCP call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "server_label": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The label of the MCP server."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The name of the MCP tool."
+ },
+ "arguments": {
+ "description": "The arguments passed to the MCP tool."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the MCP tool call."
+ },
+ "output": {
+ "anyOf": [
+ {},
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The output returned by the MCP tool, if any."
+ },
+ "error": {
+ "anyOf": [
+ {},
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The error returned by the MCP tool, if any."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "server_label",
+ "name",
+ "arguments",
+ "status",
+ "output",
+ "error"
+ ],
+ "additionalProperties": false,
+ "description": "A call to a tool on an MCP server."
+ },
+ "WebSearchActionResourceSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "search"
+ ],
+ "default": "search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `search`."
+ },
+ "query": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The search query, when a single query was used."
+ },
+ "queries": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The search queries, when multiple queries were used."
+ }
+ },
+ "required": [
+ "type",
+ "query",
+ "queries"
+ ],
+ "additionalProperties": false,
+ "description": "A search query or group of search queries."
+ },
+ "WebSearchActionResourceOpenPage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "open_page"
+ ],
+ "default": "open_page",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `open_page`."
+ },
+ "url": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The URL of the page that was opened."
+ }
+ },
+ "required": [
+ "type",
+ "url"
+ ],
+ "additionalProperties": false,
+ "description": "Opens a web page."
+ },
+ "WebSearchActionResourceFindInPage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "find_in_page"
+ ],
+ "default": "find_in_page",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `find_in_page`."
+ },
+ "url": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The URL of the page that was searched."
+ },
+ "pattern": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The text pattern that was searched for."
+ }
+ },
+ "required": [
+ "type",
+ "url",
+ "pattern"
+ ],
+ "additionalProperties": false,
+ "description": "Finds text within a web page."
+ },
+ "WebSearchActionResourceOther": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "other"
+ ],
+ "default": "other",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `other`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Another web search action."
+ },
+ "WebSearchActionResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchActionResourceSearch"
+ },
+ {
+ "$ref": "#/components/schemas/WebSearchActionResourceOpenPage"
+ },
+ {
+ "$ref": "#/components/schemas/WebSearchActionResourceFindInPage"
+ },
+ {
+ "$ref": "#/components/schemas/WebSearchActionResourceOther"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "search": "#/components/schemas/WebSearchActionResourceSearch",
+ "open_page": "#/components/schemas/WebSearchActionResourceOpenPage",
+ "find_in_page": "#/components/schemas/WebSearchActionResourceFindInPage",
+ "other": "#/components/schemas/WebSearchActionResourceOther"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "search",
+ "open_page",
+ "find_in_page",
+ "other"
+ ],
+ "description": "An action performed by the web search tool."
+ },
+ "WebSearchCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "web_search_call"
+ ],
+ "default": "web_search_call",
+ "x-stainless-const": true,
+ "description": "The item type. Always `web_search_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the web search call."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/OutputItemStatusResource",
+ "description": "The status of the web search call."
+ },
+ "action": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchActionResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The action performed by the web search tool."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "action"
+ ],
+ "additionalProperties": false,
+ "description": "A web search call produced by the agent."
+ },
+ "CommandExecutionItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "command_execution"
+ ],
+ "default": "command_execution",
+ "x-stainless-const": true,
+ "description": "The item type. Always `command_execution`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the command execution item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The command that was executed."
+ },
+ "cwd": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The working directory used to execute the command."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the command execution."
+ },
+ "output": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The command output, if available."
+ },
+ "exit_code": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "description": "The process exit code, if the command completed."
+ },
+ "duration_ms": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "description": "The command duration in milliseconds."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "command",
+ "cwd",
+ "status",
+ "output",
+ "exit_code",
+ "duration_ms"
+ ],
+ "additionalProperties": false,
+ "description": "A command execution produced by the agent."
+ },
+ "InterruptSubagentCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "interrupt_subagent_call"
+ ],
+ "default": "interrupt_subagent_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `interrupt_subagent_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent requesting the interrupt."
+ },
+ "recipient_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent to interrupt."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "sender_agent_id",
+ "recipient_agent_id"
+ ],
+ "additionalProperties": false,
+ "description": "A request to interrupt a subagent's current turn. The subagent remains available."
+ },
+ "CreateSubagentCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "create_subagent_call"
+ ],
+ "default": "create_subagent_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `create_subagent_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent that requested the subagent."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The task given to the spawned agent."
+ },
+ "model": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The model requested for the spawned agent."
+ },
+ "reasoning_effort": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The reasoning effort requested for the spawned agent."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "agent_id",
+ "content",
+ "model",
+ "reasoning_effort"
+ ],
+ "additionalProperties": false,
+ "description": "A request to spawn a subagent."
+ },
+ "SendSubagentInputCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "send_subagent_input_call"
+ ],
+ "default": "send_subagent_input_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `send_subagent_input_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent sending the input."
+ },
+ "recipient_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent receiving the input."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentContentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The input sent to the receiving agent."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "sender_agent_id",
+ "recipient_agent_id",
+ "content"
+ ],
+ "additionalProperties": false,
+ "description": "A request to send input to another agent."
+ },
+ "ResumeSubagentCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "resume_subagent_call"
+ ],
+ "default": "resume_subagent_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `resume_subagent_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent requesting the resume."
+ },
+ "recipient_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent to resume."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "sender_agent_id",
+ "recipient_agent_id"
+ ],
+ "additionalProperties": false,
+ "description": "A request to resume a subagent."
+ },
+ "WaitForSubagentsCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "wait_for_subagents_call"
+ ],
+ "default": "wait_for_subagents_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `wait_for_subagents_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent waiting for results."
+ },
+ "recipient_agent_ids": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The IDs of the agents to wait for."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "sender_agent_id",
+ "recipient_agent_ids"
+ ],
+ "additionalProperties": false,
+ "description": "A request to wait for one or more subagents."
+ },
+ "CloseSubagentCallItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "close_subagent_call"
+ ],
+ "default": "close_subagent_call",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "The current public item type."
+ ],
+ "description": "The item type. Always `close_subagent_call`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the tool call item."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "status": {
+ "$ref": "#/components/schemas/FunctionCallStatusResource",
+ "description": "The status of the tool call."
+ },
+ "sender_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent requesting the close."
+ },
+ "recipient_agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent to close."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "status",
+ "sender_agent_id",
+ "recipient_agent_id"
+ ],
+ "additionalProperties": false,
+ "description": "A request to close a subagent."
+ },
+ "SessionTurnItemResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/MessageItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/ReasoningItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/FunctionCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/FunctionCallOutputItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/AgentMessageItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/McpCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/WebSearchCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CommandExecutionItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CreateSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/SendSubagentInputCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/ResumeSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/WaitForSubagentsCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/InterruptSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CloseSubagentCallItemResource"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "message": "#/components/schemas/MessageItemResource",
+ "reasoning": "#/components/schemas/ReasoningItemResource",
+ "function_call": "#/components/schemas/FunctionCallItemResource",
+ "function_call_output": "#/components/schemas/FunctionCallOutputItemResource",
+ "agent_message": "#/components/schemas/AgentMessageItemResource",
+ "mcp_call": "#/components/schemas/McpCallItemResource",
+ "web_search_call": "#/components/schemas/WebSearchCallItemResource",
+ "command_execution": "#/components/schemas/CommandExecutionItemResource",
+ "interrupt_subagent_call": "#/components/schemas/InterruptSubagentCallItemResource",
+ "create_subagent_call": "#/components/schemas/CreateSubagentCallItemResource",
+ "send_subagent_input_call": "#/components/schemas/SendSubagentInputCallItemResource",
+ "resume_subagent_call": "#/components/schemas/ResumeSubagentCallItemResource",
+ "wait_for_subagents_call": "#/components/schemas/WaitForSubagentsCallItemResource",
+ "close_subagent_call": "#/components/schemas/CloseSubagentCallItemResource"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "message",
+ "reasoning",
+ "function_call",
+ "function_call_output",
+ "agent_message",
+ "mcp_call",
+ "web_search_call",
+ "command_execution",
+ "create_subagent_call",
+ "send_subagent_input_call",
+ "resume_subagent_call",
+ "wait_for_subagents_call",
+ "interrupt_subagent_call",
+ "close_subagent_call"
+ ],
+ "description": "An item associated with a session turn."
+ },
+ "SessionItemListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SessionTurnItemResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of messages, reasoning, and tool calls from a session's item history."
+ },
+ "TurnObjectResource": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn"
+ ],
+ "default": "agent.session.turn",
+ "x-stainless-const": true,
+ "description": "The object type for a turn."
+ },
+ "TurnStatusResource": {
+ "type": "string",
+ "enum": [
+ "queued",
+ "in_progress",
+ "waiting",
+ "completed",
+ "failed",
+ "cancelled"
+ ],
+ "x-enumDescriptions": [
+ "The turn is waiting to start.",
+ "The turn is in progress.",
+ "The turn is waiting for external input.",
+ "The turn completed successfully.",
+ "The turn failed.",
+ "The turn was cancelled."
+ ],
+ "description": "The current status of a turn."
+ },
+ "SessionTurnErrorCodeResource": {
+ "type": "string",
+ "enum": [
+ "context_length_exceeded",
+ "session_budget_exceeded",
+ "usage_limit_exceeded",
+ "rate_limit_exceeded",
+ "server_overloaded",
+ "cyber_policy",
+ "connection_failed",
+ "server_error",
+ "authentication_error",
+ "invalid_request",
+ "resource_not_found",
+ "sandbox_error",
+ "executor_version_incompatible",
+ "active_turn_not_steerable",
+ "request_timeout",
+ "internal_error"
+ ],
+ "x-enumDescriptions": [
+ "The request exceeds the model's context window.",
+ "The session has reached its usage budget.",
+ "The organization has reached a usage, plan, or billing limit.",
+ "The request exceeds the available rate limit.",
+ "The model service is temporarily overloaded.",
+ "The request was rejected by a safety policy.",
+ "The request could not connect to the model service.",
+ "The model service encountered an unexpected error.",
+ "The API credentials are invalid or lack the required access.",
+ "The request contains invalid input or configuration.",
+ "The requested model or resource is unavailable.",
+ "The request could not complete in its execution environment.",
+ "The executor must be upgraded before it can run this turn.",
+ "The session cannot accept additional input while a request is running.",
+ "The request timed out before the model service responded.",
+ "An unexpected internal error prevented the session request from completing."
+ ],
+ "description": "Stable public categories for session request failures."
+ },
+ "SessionTurnErrorResource": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "$ref": "#/components/schemas/SessionTurnErrorCodeResource",
+ "description": "A stable, machine-readable failure category."
+ },
+ "message": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A customer-safe explanation of the failure."
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "additionalProperties": false,
+ "description": "A customer-safe error describing why a session request failed."
+ },
+ "InputTokensDetailsResource": {
+ "type": "object",
+ "properties": {
+ "cached_tokens": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The number of input tokens retrieved from the prompt cache."
+ }
+ },
+ "required": [
+ "cached_tokens"
+ ],
+ "additionalProperties": false,
+ "description": "A breakdown of input token usage for a session or turn."
+ },
+ "OutputTokensDetailsResource": {
+ "type": "object",
+ "properties": {
+ "reasoning_tokens": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The number of output tokens used for reasoning."
+ }
+ },
+ "required": [
+ "reasoning_tokens"
+ ],
+ "additionalProperties": false,
+ "description": "A breakdown of output token usage for a session or turn."
+ },
+ "TokenUsageResource": {
+ "type": "object",
+ "properties": {
+ "input_tokens": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The number of input tokens used by the agent."
+ },
+ "input_tokens_details": {
+ "$ref": "#/components/schemas/InputTokensDetailsResource",
+ "description": "A breakdown of the agent's input token usage."
+ },
+ "output_tokens": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The number of output tokens generated by the agent."
+ },
+ "output_tokens_details": {
+ "$ref": "#/components/schemas/OutputTokensDetailsResource",
+ "description": "A breakdown of the agent's output token usage."
+ },
+ "total_tokens": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The total number of input and output tokens used by the agent."
+ }
+ },
+ "required": [
+ "input_tokens",
+ "input_tokens_details",
+ "output_tokens",
+ "output_tokens_details",
+ "total_tokens"
+ ],
+ "additionalProperties": false,
+ "description": "Recorded token usage for a session or turn. Usage is best effort and may change."
+ },
+ "TurnResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn."
+ },
+ "object": {
+ "$ref": "#/components/schemas/TurnObjectResource",
+ "description": "The object type. Always `agent.session.turn`."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session that owns the turn."
+ },
+ "agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent that ran the turn."
+ },
+ "subagent_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the subagent that ran the turn, if applicable."
+ },
+ "status": {
+ "$ref": "#/components/schemas/TurnStatusResource",
+ "description": "The current status of the turn."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, used to order the turn by creation time. Subagent turns use their start time, falling back to completion time or the subagent opening time when the preceding timestamps are unavailable."
+ },
+ "started_at": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the turn started."
+ },
+ "completed_at": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the turn reached a terminal state."
+ },
+ "error": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/SessionTurnErrorResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "A customer-safe error. Non-null only for a failed turn."
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TokenUsageResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Best-effort token usage for the turn, or null if unknown. Recorded usage may change."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "session_id",
+ "agent_id",
+ "subagent_id",
+ "status",
+ "created_at",
+ "started_at",
+ "completed_at",
+ "error",
+ "usage"
+ ],
+ "additionalProperties": false,
+ "description": "The canonical public representation of a session turn."
+ },
+ "SessionTurnListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/TurnResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "ReasoningEffortResource": {
+ "type": "string",
+ "enum": [
+ "none",
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh",
+ "max"
+ ],
+ "description": "The amount of reasoning effort used by an agent."
+ },
+ "ReasoningSummaryResource": {
+ "type": "string",
+ "enum": [
+ "concise",
+ "detailed",
+ "auto"
+ ],
+ "x-enumDescriptions": [
+ "Returns a concise reasoning summary when supported.",
+ "Returns a detailed reasoning summary when supported.",
+ "Automatically selects the most detailed summary supported by the model."
+ ],
+ "description": "The reasoning summary format requested from an agent."
+ },
+ "ReasoningResource": {
+ "type": "object",
+ "properties": {
+ "effort": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningEffortResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The requested reasoning effort, or `null` when the model selects its own default."
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningSummaryResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The requested reasoning summary format, or `null` when summaries are disabled."
+ }
+ },
+ "required": [
+ "effort",
+ "summary"
+ ],
+ "additionalProperties": false,
+ "description": "The reasoning configuration used by an agent."
+ },
+ "TextFormatResourceText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "text"
+ ],
+ "default": "text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `text`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Generates ordinary text without a structured-output constraint."
+ },
+ "TextFormatResourceJsonSchema": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "json_schema"
+ ],
+ "default": "json_schema",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `json_schema`."
+ },
+ "schema": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "The JSON Schema that generated text must match."
+ }
+ },
+ "required": [
+ "type",
+ "schema"
+ ],
+ "additionalProperties": false,
+ "description": "Constrains generated text to a JSON Schema."
+ },
+ "TextFormatResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/TextFormatResourceText"
+ },
+ {
+ "$ref": "#/components/schemas/TextFormatResourceJsonSchema"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "text": "#/components/schemas/TextFormatResourceText",
+ "json_schema": "#/components/schemas/TextFormatResourceJsonSchema"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "text",
+ "json_schema"
+ ],
+ "description": "The effective output format for generated text."
+ },
+ "VerbosityResource": {
+ "type": "string",
+ "enum": [
+ "low",
+ "medium",
+ "high"
+ ],
+ "description": "The amount of text produced by an agent."
+ },
+ "TextResource": {
+ "type": "object",
+ "properties": {
+ "format": {
+ "$ref": "#/components/schemas/TextFormatResource",
+ "description": "The effective output format. Defaults to ordinary text."
+ },
+ "verbosity": {
+ "$ref": "#/components/schemas/VerbosityResource",
+ "description": "The amount of text produced by the agent. Defaults to `medium`."
+ }
+ },
+ "required": [
+ "format",
+ "verbosity"
+ ],
+ "additionalProperties": false,
+ "description": "The text configuration used by an agent."
+ },
+ "ServiceTierResource": {
+ "type": "string",
+ "enum": [
+ "auto",
+ "default",
+ "flex",
+ "priority",
+ "fast"
+ ],
+ "description": "The service-tier policy configured for an agent."
+ },
+ "PersistedAgentToolResourceFunction": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function"
+ ],
+ "default": "function",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `function`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The name of the function."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A description of what the function does."
+ },
+ "parameters": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "A JSON Schema object describing the function's arguments."
+ },
+ "defer_loading": {
+ "type": "boolean",
+ "description": "Whether the function is deferred and discovered through tool search."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "parameters",
+ "defer_loading"
+ ],
+ "additionalProperties": false,
+ "description": "A function defined by the application."
+ },
+ "PersistedAgentToolResourceToolSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "tool_search"
+ ],
+ "default": "tool_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `tool_search`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Discovers deferred function tools and loads them into the model context."
+ },
+ "PersistedAgentToolResourceProgrammaticToolCalling": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "programmatic_tool_calling"
+ ],
+ "default": "programmatic_tool_calling",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `programmatic_tool_calling`."
+ },
+ "enabled": {
+ "type": "boolean",
+ "description": "Whether tools can be called from model-generated code."
+ }
+ },
+ "required": [
+ "type",
+ "enabled"
+ ],
+ "additionalProperties": false,
+ "description": "Enables calling tools from model-generated code."
+ },
+ "PersistedMcpTransportResourceHttp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "http"
+ ],
+ "default": "http",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `http`."
+ },
+ "server_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The URL of the MCP server."
+ },
+ "headers": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Non-secret HTTP headers sent to the MCP server."
+ }
+ },
+ "required": [
+ "type",
+ "server_url",
+ "headers"
+ ],
+ "additionalProperties": false,
+ "description": "Connects to an MCP server over HTTP."
+ },
+ "PersistedMcpTransportResourceStdio": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "stdio"
+ ],
+ "default": "stdio",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `stdio`."
+ },
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The command used to start the MCP server."
+ },
+ "args": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Arguments passed to the MCP server command."
+ },
+ "cwd": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The working directory used to start the MCP server."
+ },
+ "env_vars": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Environment variable names inherited from the execution environment."
+ }
+ },
+ "required": [
+ "type",
+ "command",
+ "args",
+ "cwd",
+ "env_vars"
+ ],
+ "additionalProperties": false,
+ "description": "Starts an MCP server as a local process."
+ },
+ "PersistedMcpTransportResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/PersistedMcpTransportResourceHttp"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedMcpTransportResourceStdio"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "http": "#/components/schemas/PersistedMcpTransportResourceHttp",
+ "stdio": "#/components/schemas/PersistedMcpTransportResourceStdio"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "http",
+ "stdio"
+ ],
+ "description": "A credential-free transport used to connect to an MCP server."
+ },
+ "McpConnectionOriginResource": {
+ "type": "string",
+ "enum": [
+ "service",
+ "environment"
+ ],
+ "description": "Where outbound MCP HTTP connections originate."
+ },
+ "PersistedAgentToolResourceMcp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp"
+ ],
+ "default": "mcp",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp`."
+ },
+ "server_label": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A label used to identify the MCP server in tool calls."
+ },
+ "credential_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The vault credential selected for this MCP server, if any."
+ },
+ "transport": {
+ "$ref": "#/components/schemas/PersistedMcpTransportResource",
+ "description": "The credential-free transport used to connect to the MCP server."
+ },
+ "request_metadata": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Metadata included with requests to this MCP server."
+ },
+ "allowed_tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The MCP tools the agent may call, or null when all server tools are allowed."
+ },
+ "required": {
+ "type": "boolean",
+ "description": "Whether this MCP server must initialize before the first turn."
+ },
+ "connection_origin": {
+ "$ref": "#/components/schemas/McpConnectionOriginResource",
+ "description": "Where outbound MCP HTTP connections originate."
+ }
+ },
+ "required": [
+ "type",
+ "server_label",
+ "credential_id",
+ "transport",
+ "request_metadata",
+ "allowed_tools",
+ "required",
+ "connection_origin"
+ ],
+ "additionalProperties": false,
+ "description": "Tools provided by a remote MCP server without stored credentials."
+ },
+ "WebSearchModeResource": {
+ "type": "string",
+ "enum": [
+ "disabled",
+ "cached",
+ "live"
+ ],
+ "description": "The source used for web search results."
+ },
+ "WebSearchContextSizeResource": {
+ "type": "string",
+ "enum": [
+ "low",
+ "medium",
+ "high"
+ ],
+ "description": "The amount of web search context made available to the model."
+ },
+ "WebSearchLocationResource": {
+ "type": "object",
+ "properties": {
+ "country": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The two-letter ISO country code, such as `US`."
+ },
+ "region": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The region or state name."
+ },
+ "city": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The city name."
+ },
+ "timezone": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The IANA timezone, such as `America/Los_Angeles`."
+ }
+ },
+ "required": [
+ "country",
+ "region",
+ "city",
+ "timezone"
+ ],
+ "additionalProperties": false,
+ "description": "Approximate user location used to localize web search results."
+ },
+ "PersistedAgentToolResourceWebSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "web_search"
+ ],
+ "default": "web_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `web_search`."
+ },
+ "mode": {
+ "$ref": "#/components/schemas/WebSearchModeResource",
+ "description": "The source used for web search results."
+ },
+ "context_size": {
+ "$ref": "#/components/schemas/WebSearchContextSizeResource",
+ "description": "The amount of search context made available to the model. Defaults to `medium`."
+ },
+ "allowed_domains": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Allowed search domains, or `null` when the search is unrestricted."
+ },
+ "location": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchLocationResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Approximate location used to localize search results, if provided."
+ }
+ },
+ "required": [
+ "type",
+ "mode",
+ "context_size",
+ "allowed_domains",
+ "location"
+ ],
+ "additionalProperties": false,
+ "description": "Web search."
+ },
+ "PersistedAgentToolResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolResourceFunction"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolResourceToolSearch"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolResourceMcp"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolResourceWebSearch"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "function": "#/components/schemas/PersistedAgentToolResourceFunction",
+ "tool_search": "#/components/schemas/PersistedAgentToolResourceToolSearch",
+ "programmatic_tool_calling": "#/components/schemas/PersistedAgentToolResourceProgrammaticToolCalling",
+ "mcp": "#/components/schemas/PersistedAgentToolResourceMcp",
+ "web_search": "#/components/schemas/PersistedAgentToolResourceWebSearch"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "function",
+ "tool_search",
+ "programmatic_tool_calling",
+ "mcp",
+ "web_search"
+ ],
+ "description": "A credential-free tool available to a reusable agent."
+ },
+ "MultiAgentConfigResource": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "type": "boolean",
+ "description": "Whether subagent tools are enabled. Defaults to false."
+ },
+ "max_concurrent_subagents": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 4294967295,
+ "description": "Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled."
+ }
+ },
+ "required": [
+ "enabled",
+ "max_concurrent_subagents"
+ ],
+ "additionalProperties": false,
+ "description": "The resolved configuration for creating and coordinating subagents."
+ },
+ "AgentResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reusable agent."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent"
+ ],
+ "default": "agent",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent`."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the agent was created."
+ },
+ "updated_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the agent was last updated."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "A human-readable name for the agent, or null if it is unnamed."
+ },
+ "metadata": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Custom string key-value pairs attached to the agent."
+ },
+ "model": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The requested model name used for inference."
+ },
+ "reasoning": {
+ "$ref": "#/components/schemas/ReasoningResource",
+ "description": "The resolved reasoning configuration, including the model default for an omitted effort."
+ },
+ "text": {
+ "$ref": "#/components/schemas/TextResource",
+ "description": "The resolved configuration for text generated by the agent."
+ },
+ "service_tier": {
+ "$ref": "#/components/schemas/ServiceTierResource",
+ "description": "The resolved service-tier policy used for model requests."
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "Custom instructions appended to the agent's default base instructions."
+ },
+ "tools": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/PersistedAgentToolResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Tools available to the agent."
+ },
+ "multi_agent": {
+ "$ref": "#/components/schemas/MultiAgentConfigResource",
+ "description": "The resolved configuration for creating and coordinating subagents."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.SavedAgentCore"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "created_at",
+ "updated_at",
+ "name",
+ "metadata",
+ "model",
+ "reasoning",
+ "text",
+ "service_tier",
+ "instructions",
+ "tools",
+ "multi_agent"
+ ],
+ "additionalProperties": false,
+ "description": "A reusable agent scoped to the caller's project."
+ },
+ "AgentListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "ReasoningEffortParam": {
+ "type": "string",
+ "enum": [
+ "none",
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh",
+ "max"
+ ],
+ "description": "The amount of reasoning effort the model should use."
+ },
+ "ReasoningSummaryParam": {
+ "type": "string",
+ "enum": [
+ "concise",
+ "detailed",
+ "auto"
+ ],
+ "x-enumDescriptions": [
+ "Returns a concise reasoning summary when supported.",
+ "Returns a detailed reasoning summary when supported.",
+ "Automatically selects the most detailed summary supported by the model."
+ ],
+ "description": "The reasoning summary format requested from the model."
+ },
+ "ReasoningParam": {
+ "type": "object",
+ "properties": {
+ "effort": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningEffortParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The amount of reasoning effort the model should use. Omission lets the model select it."
+ },
+ "summary": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningSummaryParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Controls whether the response includes a reasoning summary."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Reasoning configuration for the agent."
+ },
+ "TextFormatParamText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "text"
+ ],
+ "default": "text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `text`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Generates ordinary text without a structured-output constraint."
+ },
+ "TextFormatParamJsonSchema": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "json_schema"
+ ],
+ "default": "json_schema",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `json_schema`."
+ },
+ "schema": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "The JSON Schema that generated text must match."
+ }
+ },
+ "required": [
+ "type",
+ "schema"
+ ],
+ "additionalProperties": false,
+ "description": "Constrains generated text to a JSON Schema."
+ },
+ "TextFormatParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/TextFormatParamText"
+ },
+ {
+ "$ref": "#/components/schemas/TextFormatParamJsonSchema"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "text": "#/components/schemas/TextFormatParamText",
+ "json_schema": "#/components/schemas/TextFormatParamJsonSchema"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "text",
+ "json_schema"
+ ],
+ "description": "The output format for generated text."
+ },
+ "VerbosityParam": {
+ "type": "string",
+ "enum": [
+ "low",
+ "medium",
+ "high"
+ ],
+ "x-enumDescriptions": [
+ "Produces less text.",
+ "Uses the default amount of text.",
+ "Produces more text."
+ ],
+ "description": "The amount of text the model should produce."
+ },
+ "TextParam": {
+ "type": "object",
+ "properties": {
+ "format": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TextFormatParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The output format. Omission uses ordinary text (`{\"type\": \"text\"}`)."
+ },
+ "verbosity": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/VerbosityParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The amount of text the model should produce. Defaults to `medium`, matching Responses."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Configuration for text generated by the agent."
+ },
+ "ServiceTierParam": {
+ "type": "string",
+ "enum": [
+ "auto",
+ "default",
+ "flex",
+ "priority",
+ "fast"
+ ],
+ "x-enumDescriptions": [
+ "Selects the service tier automatically.",
+ "Uses the default service tier.",
+ "Uses the flex service tier.",
+ "Uses the priority service tier.",
+ "Uses the fast service tier."
+ ],
+ "description": "The service tier used for model requests."
+ },
+ "PersistedAgentToolConfigParamFunction": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function"
+ ],
+ "default": "function",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `function`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The name of the function."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A description of what the function does."
+ },
+ "parameters": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "A JSON Schema object describing the function's arguments."
+ },
+ "defer_loading": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether this function is deferred and discovered through tool search. Defaults to `false`."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "parameters"
+ ],
+ "additionalProperties": false,
+ "description": "A function defined by the application."
+ },
+ "PersistedAgentToolConfigParamToolSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "tool_search"
+ ],
+ "default": "tool_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `tool_search`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Discovers deferred function tools and loads them into the model context."
+ },
+ "PersistedAgentToolConfigParamProgrammaticToolCalling": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "programmatic_tool_calling"
+ ],
+ "default": "programmatic_tool_calling",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `programmatic_tool_calling`."
+ },
+ "enabled": {
+ "type": "boolean",
+ "default": true,
+ "description": "Whether tools can be called from model-generated code. Defaults to `true`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Enables calling tools from model-generated code."
+ },
+ "PersistedMcpTransportConfigParamHttp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "http"
+ ],
+ "default": "http",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `http`."
+ },
+ "server_url": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The URL of the MCP server."
+ },
+ "headers": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Non-secret HTTP headers sent to the MCP server."
+ }
+ },
+ "required": [
+ "type",
+ "server_url"
+ ],
+ "additionalProperties": false,
+ "description": "Connects to an MCP server over HTTP."
+ },
+ "PersistedMcpTransportConfigParamStdio": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "stdio"
+ ],
+ "default": "stdio",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `stdio`."
+ },
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The command used to start the MCP server."
+ },
+ "args": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Arguments passed to the MCP server command."
+ },
+ "cwd": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The working directory used to start the MCP server."
+ },
+ "env_vars": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Environment variable names to inherit from the selected execution environment."
+ }
+ },
+ "required": [
+ "type",
+ "command",
+ "cwd"
+ ],
+ "additionalProperties": false,
+ "description": "Starts an MCP server as a local process."
+ },
+ "PersistedMcpTransportConfigParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/PersistedMcpTransportConfigParamHttp"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedMcpTransportConfigParamStdio"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "http": "#/components/schemas/PersistedMcpTransportConfigParamHttp",
+ "stdio": "#/components/schemas/PersistedMcpTransportConfigParamStdio"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "http",
+ "stdio"
+ ],
+ "description": "A credential-free transport used to connect to an MCP server."
+ },
+ "McpConnectionOriginParam": {
+ "type": "string",
+ "enum": [
+ "service",
+ "environment"
+ ],
+ "x-enumDescriptions": [
+ "Uses the Managed Agents service network.",
+ "Uses the session's execution environment."
+ ],
+ "description": "Where outbound MCP HTTP connections originate."
+ },
+ "PersistedAgentToolConfigParamMcp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp"
+ ],
+ "default": "mcp",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp`."
+ },
+ "server_label": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A label used to identify the MCP server in tool calls."
+ },
+ "credential_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL."
+ },
+ "transport": {
+ "$ref": "#/components/schemas/PersistedMcpTransportConfigParam",
+ "description": "The credential-free transport used to connect to the MCP server."
+ },
+ "request_metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Metadata included with requests to this MCP server."
+ },
+ "allowed_tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The MCP tools the agent may call. All server tools are allowed when omitted."
+ },
+ "required": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether this MCP server must initialize before the first turn. Defaults to `false`."
+ },
+ "connection_origin": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/McpConnectionOriginParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Selects where outbound MCP HTTP connections originate."
+ }
+ },
+ "required": [
+ "type",
+ "server_label",
+ "transport"
+ ],
+ "additionalProperties": false,
+ "description": "Tools provided by a remote MCP server without stored credentials."
+ },
+ "WebSearchModeParam": {
+ "type": "string",
+ "enum": [
+ "disabled",
+ "cached",
+ "live"
+ ],
+ "x-enumDescriptions": [
+ "Disables web search.",
+ "Uses cached search results.",
+ "Searches the live web."
+ ],
+ "description": "The source used for web search results."
+ },
+ "WebSearchContextSizeParam": {
+ "type": "string",
+ "enum": [
+ "low",
+ "medium",
+ "high"
+ ],
+ "description": "The amount of web search context made available to the model."
+ },
+ "WebSearchLocationParam": {
+ "type": "object",
+ "properties": {
+ "country": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The two-letter ISO country code, such as `US`."
+ },
+ "region": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The region or state name."
+ },
+ "city": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The city name."
+ },
+ "timezone": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The IANA timezone, such as `America/Los_Angeles`."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Approximate user location used to localize web search results."
+ },
+ "PersistedAgentToolConfigParamWebSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "web_search"
+ ],
+ "default": "web_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `web_search`."
+ },
+ "mode": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchModeParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The source used for web search results. Defaults to `live`."
+ },
+ "context_size": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchContextSizeParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The amount of search context made available to the model. Defaults to `medium`."
+ },
+ "allowed_domains": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Domains the search may include."
+ },
+ "location": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchLocationParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Approximate location used to localize search results."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Web search."
+ },
+ "PersistedAgentToolConfigParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParamFunction"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParamToolSearch"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParamMcp"
+ },
+ {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParamWebSearch"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "function": "#/components/schemas/PersistedAgentToolConfigParamFunction",
+ "tool_search": "#/components/schemas/PersistedAgentToolConfigParamToolSearch",
+ "programmatic_tool_calling": "#/components/schemas/PersistedAgentToolConfigParamProgrammaticToolCalling",
+ "mcp": "#/components/schemas/PersistedAgentToolConfigParamMcp",
+ "web_search": "#/components/schemas/PersistedAgentToolConfigParamWebSearch"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "function",
+ "tool_search",
+ "programmatic_tool_calling",
+ "mcp",
+ "web_search"
+ ],
+ "description": "A tool that can be stored on a reusable agent without session credentials."
+ },
+ "MultiAgentConfigCurrentParam": {
+ "type": "object",
+ "properties": {
+ "enabled": {
+ "type": "boolean",
+ "description": "Whether subagent tools are enabled."
+ },
+ "max_concurrent_subagents": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 1,
+ "maximum": 4294967295,
+ "description": "Maximum number of subagents that may run concurrently. Defaults to 6."
+ }
+ },
+ "required": [
+ "enabled"
+ ],
+ "additionalProperties": false,
+ "description": "Explicit configuration for creating and coordinating subagents."
+ },
+ "CreateAgentParams": {
+ "type": "object",
+ "properties": {
+ "metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 512
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64
+ },
+ "minProperties": 0,
+ "maxProperties": 16,
+ "description": "Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 128,
+ "description": "A human-readable name for the agent. Omission or null leaves the agent unnamed."
+ },
+ "model": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The model to use for the agent. The requested model name is preserved."
+ },
+ "reasoning": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for model reasoning. Omission uses the model's default effort."
+ },
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TextParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for generated text. Defaults to the `text` format and medium verbosity."
+ },
+ "service_tier": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ServiceTierParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The service tier used for model requests. Defaults to `auto`."
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Additional instructions appended to the agent's default base instructions. Omit or set to null to add no custom instructions."
+ },
+ "tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParam"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Tools available to the agent. Defaults to an empty list."
+ },
+ "multi_agent": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/MultiAgentConfigCurrentParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for creating and coordinating subagents. Subagent tools are disabled by default."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.SavedAgentCoreInput"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "model"
+ ],
+ "additionalProperties": false,
+ "description": "Parameters for creating a reusable agent."
+ },
+ "UpdateAgentParams": {
+ "type": "object",
+ "properties": {
+ "model": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The model to use for the agent. The requested model name is preserved."
+ },
+ "reasoning": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort."
+ },
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TextParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for text generated by the agent."
+ },
+ "service_tier": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ServiceTierParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The service tier used for model requests."
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Additional instructions appended to the agent's default base instructions. Omit to leave unchanged."
+ },
+ "multi_agent": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/MultiAgentConfigCurrentParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for creating and coordinating subagents."
+ },
+ "metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 512
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64
+ },
+ "minProperties": 0,
+ "maxProperties": 16,
+ "description": "Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 128,
+ "description": "A replacement name. Omit to leave unchanged, or pass null to clear it."
+ },
+ "tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/PersistedAgentToolConfigParam"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Tools available to the agent."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.SavedAgentCoreInput"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "description": "Fields to replace on an existing reusable agent."
+ },
+ "DeletedAgentResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted agent."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.deleted"
+ ],
+ "default": "agent.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the agent was deleted. Always `true`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "A deleted reusable agent."
+ },
+ "EnvironmentPackagesResource": {
+ "type": "object",
+ "properties": {
+ "python": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Python packages installed in the environment."
+ },
+ "system": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "System packages installed in the environment."
+ },
+ "npm": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "npm packages installed globally in the environment."
+ }
+ },
+ "required": [
+ "python",
+ "system",
+ "npm"
+ ],
+ "additionalProperties": false,
+ "description": "Packages installed in an OpenAI-hosted environment."
+ },
+ "NetworkAccessResource": {
+ "type": "string",
+ "enum": [
+ "enabled",
+ "disabled",
+ "restricted"
+ ],
+ "x-enumDescriptions": [
+ "Allows unrestricted network access.",
+ "Disables network access.",
+ "Allows access only to configured domains."
+ ],
+ "description": "The network access mode for an OpenAI-hosted environment."
+ },
+ "NetworkPolicyResource": {
+ "type": "object",
+ "properties": {
+ "access": {
+ "$ref": "#/components/schemas/NetworkAccessResource",
+ "description": "The environment's network access mode."
+ },
+ "allowed_domains": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Domains the environment may access when network access is restricted."
+ }
+ },
+ "required": [
+ "access",
+ "allowed_domains"
+ ],
+ "additionalProperties": false,
+ "description": "Network access for an OpenAI-hosted environment."
+ },
+ "HostedTemplateSkillResourceSkillReference": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "skill_reference"
+ ],
+ "default": "skill_reference",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `skill_reference`."
+ },
+ "skill_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The referenced skill ID."
+ },
+ "version": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The requested version selector, including `latest`."
+ }
+ },
+ "required": [
+ "type",
+ "skill_id",
+ "version"
+ ],
+ "additionalProperties": false,
+ "description": "A skill resolved afresh from the Skills API whenever a session starts."
+ },
+ "HostedTemplateSkillResourceInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The skill name declared in `SKILL.md`."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The skill description declared in `SKILL.md`."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description"
+ ],
+ "additionalProperties": false,
+ "description": "Safe metadata for an inline skill archive."
+ },
+ "HostedTemplateSkillResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedTemplateSkillResourceSkillReference"
+ },
+ {
+ "$ref": "#/components/schemas/HostedTemplateSkillResourceInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "skill_reference": "#/components/schemas/HostedTemplateSkillResourceSkillReference",
+ "inline": "#/components/schemas/HostedTemplateSkillResourceInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "skill_reference",
+ "inline"
+ ],
+ "description": "Safe metadata for a skill configured by an environment template."
+ },
+ "HostedTemplateFileResourceFileId": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "file_id"
+ ],
+ "default": "file_id",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `file_id`."
+ },
+ "file_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the uploaded file."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The file's absolute path inside the environment."
+ }
+ },
+ "required": [
+ "type",
+ "file_id",
+ "path"
+ ],
+ "additionalProperties": false,
+ "description": "A project-scoped Files API reference resolved separately for each session."
+ },
+ "HostedTemplateFileResourceInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The file's absolute path inside the environment."
+ },
+ "size_bytes": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "description": "The decoded size of the inline file in bytes."
+ }
+ },
+ "required": [
+ "type",
+ "path",
+ "size_bytes"
+ ],
+ "additionalProperties": false,
+ "description": "Metadata for confidential inline file contents."
+ },
+ "HostedTemplateFileResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedTemplateFileResourceFileId"
+ },
+ {
+ "$ref": "#/components/schemas/HostedTemplateFileResourceInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "file_id": "#/components/schemas/HostedTemplateFileResourceFileId",
+ "inline": "#/components/schemas/HostedTemplateFileResourceInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "file_id",
+ "inline"
+ ],
+ "description": "Safe metadata for a file configured by an environment template."
+ },
+ "EnvironmentTemplateResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reusable environment template."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "An optional human-readable display name for the template."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.environment.template"
+ ],
+ "default": "agent.environment.template",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.environment.template`."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the template was created."
+ },
+ "updated_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the template was last updated."
+ },
+ "packages": {
+ "$ref": "#/components/schemas/EnvironmentPackagesResource",
+ "description": "Packages installed in each fresh OpenAI-hosted environment."
+ },
+ "network": {
+ "$ref": "#/components/schemas/NetworkPolicyResource",
+ "description": "Runtime network access for each OpenAI-hosted environment."
+ },
+ "capability_directories": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Directories that expose capabilities to the agent."
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedTemplateSkillResource"
+ },
+ "minItems": 0,
+ "maxItems": 200,
+ "description": "Safe skill metadata, preserving unresolved version selectors."
+ },
+ "plugins": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginResource"
+ },
+ "minItems": 0,
+ "maxItems": 32,
+ "description": "Safe plugin metadata, excluding inline archive contents."
+ },
+ "files": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedTemplateFileResource"
+ },
+ "minItems": 0,
+ "maxItems": 50,
+ "description": "Safe file metadata, excluding contents and session-scoped file IDs."
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "object",
+ "created_at",
+ "updated_at",
+ "packages",
+ "network",
+ "capability_directories",
+ "skills",
+ "plugins",
+ "files"
+ ],
+ "additionalProperties": false,
+ "description": "Reusable configuration that provisions a fresh OpenAI-hosted environment for each session."
+ },
+ "EnvironmentTemplateListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/EnvironmentTemplateResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "EnvironmentPackagesParam": {
+ "type": "object",
+ "properties": {
+ "python": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Python packages to install. Defaults to an empty list."
+ },
+ "system": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "System packages to install. Defaults to an empty list."
+ },
+ "npm": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "npm packages to install globally. Defaults to an empty list."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Packages to install in an OpenAI-hosted environment."
+ },
+ "SetupCommandParam": {
+ "type": "object",
+ "properties": {
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 65536,
+ "description": "The shell command to execute."
+ },
+ "cwd": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 4096,
+ "description": "The absolute working directory. Defaults to `/workspace`."
+ }
+ },
+ "required": [
+ "command"
+ ],
+ "additionalProperties": false,
+ "description": "A confidential setup command executed before the hosted agent starts."
+ },
+ "NetworkAccessParam": {
+ "type": "string",
+ "enum": [
+ "enabled",
+ "disabled",
+ "restricted"
+ ],
+ "x-enumDescriptions": [
+ "Allows unrestricted network access, matching an omitted network policy.",
+ "Disables network access.",
+ "Allows access only to configured domains."
+ ],
+ "description": "The network access mode for an OpenAI-hosted environment."
+ },
+ "NetworkPolicyParam": {
+ "type": "object",
+ "properties": {
+ "access": {
+ "$ref": "#/components/schemas/NetworkAccessParam",
+ "description": "The environment's network access mode."
+ },
+ "allowed_domains": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Domains the environment may access when network access is restricted."
+ }
+ },
+ "required": [
+ "access"
+ ],
+ "additionalProperties": false,
+ "description": "Network access for an OpenAI-hosted environment."
+ },
+ "HostedSkillParamSkillReference": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "skill_reference"
+ ],
+ "default": "skill_reference",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `skill_reference`."
+ },
+ "skill_id": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64,
+ "description": "The ID of the skill created through `/v1/skills`."
+ },
+ "version": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The skill version, a positive integer or `latest`; omission selects the default."
+ }
+ },
+ "required": [
+ "type",
+ "skill_id"
+ ],
+ "additionalProperties": false,
+ "description": "References a skill uploaded through the Skills API."
+ },
+ "InlineCapabilitySourceParamBase64": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "base64"
+ ],
+ "default": "base64",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `base64`."
+ },
+ "media_type": {
+ "type": "string",
+ "enum": [
+ "application/zip"
+ ],
+ "default": "application/zip",
+ "x-stainless-const": true,
+ "x-enumDescriptions": [
+ "A ZIP archive."
+ ],
+ "description": "The archive media type, always `application/zip`."
+ },
+ "data": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 70254592,
+ "description": "Standard-base64 encoded ZIP archive bytes."
+ }
+ },
+ "required": [
+ "type",
+ "media_type",
+ "data"
+ ],
+ "additionalProperties": false,
+ "description": "Provides ZIP bytes encoded with standard base64."
+ },
+ "InlineCapabilitySourceParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/InlineCapabilitySourceParamBase64"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "base64": "#/components/schemas/InlineCapabilitySourceParamBase64"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "base64"
+ ],
+ "description": "The encoded ZIP archive for an inline skill or plugin."
+ },
+ "HostedSkillParamInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64,
+ "description": "The skill name declared in `SKILL.md`."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The skill description declared in `SKILL.md`."
+ },
+ "source": {
+ "$ref": "#/components/schemas/InlineCapabilitySourceParam",
+ "description": "The inline ZIP archive."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "source"
+ ],
+ "additionalProperties": false,
+ "description": "Supplies a skill ZIP directly in the session request."
+ },
+ "HostedSkillParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedSkillParamSkillReference"
+ },
+ {
+ "$ref": "#/components/schemas/HostedSkillParamInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "skill_reference": "#/components/schemas/HostedSkillParamSkillReference",
+ "inline": "#/components/schemas/HostedSkillParamInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "skill_reference",
+ "inline"
+ ],
+ "description": "A skill installed in an OpenAI-hosted environment."
+ },
+ "HostedPluginParamInline": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "inline"
+ ],
+ "default": "inline",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `inline`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64,
+ "description": "The plugin name declared in `.codex-plugin/plugin.json`."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The plugin description declared in `.codex-plugin/plugin.json`."
+ },
+ "source": {
+ "$ref": "#/components/schemas/InlineCapabilitySourceParam",
+ "description": "The inline ZIP archive."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "source"
+ ],
+ "additionalProperties": false,
+ "description": "Supplies a plugin ZIP directly in the session request."
+ },
+ "HostedPluginParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/HostedPluginParamInline"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "inline": "#/components/schemas/HostedPluginParamInline"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "inline"
+ ],
+ "description": "A plugin installed in an OpenAI-hosted environment."
+ },
+ "CreateEnvironmentTemplateParams": {
+ "type": "object",
+ "properties": {
+ "packages": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/EnvironmentPackagesParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Packages to install in the environment. Defaults to empty package lists."
+ },
+ "setup_commands": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/SetupCommandParam"
+ },
+ "minItems": 0,
+ "maxItems": 16,
+ "description": "Ordered, confidential setup commands. Command bodies are never returned."
+ },
+ "network": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/NetworkPolicyParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Network access policy for the environment. Defaults to enabled."
+ },
+ "env": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Environment variables made available to the agent."
+ },
+ "capability_directories": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Directories that contain capabilities exposed to the agent. Defaults to an empty list."
+ },
+ "skills": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedSkillParam"
+ },
+ "minItems": 0,
+ "maxItems": 200,
+ "description": "Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list."
+ },
+ "plugins": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginParam"
+ },
+ "minItems": 0,
+ "maxItems": 32,
+ "description": "Plugins provided as inline ZIP archives. Defaults to an empty list."
+ },
+ "files": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParam"
+ },
+ "minItems": 0,
+ "maxItems": 50,
+ "description": "Files available before the agent starts. Defaults to an empty list."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 1,
+ "maxLength": 256,
+ "description": "An optional human-readable display name for the template."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Parameters for creating a reusable, project-scoped OpenAI-hosted environment template."
+ },
+ "UpdateEnvironmentTemplateParams": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 1,
+ "maxLength": 256,
+ "description": "A replacement human-readable display name, or `null` to clear the name."
+ },
+ "packages": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/EnvironmentPackagesParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Packages installed before the runtime network policy applies."
+ },
+ "setup_commands": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/SetupCommandParam"
+ },
+ "minItems": 0,
+ "maxItems": 16,
+ "description": "Replacement confidential setup commands, never included in returned resources."
+ },
+ "network": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/NetworkPolicyParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Network access available after setup completes."
+ },
+ "env": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Replacement confidential environment values."
+ },
+ "capability_directories": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Directories that expose capabilities to the agent."
+ },
+ "skills": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedSkillParam"
+ },
+ "minItems": 0,
+ "maxItems": 200,
+ "description": "Replacement skill configuration installed for each new session."
+ },
+ "plugins": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginParam"
+ },
+ "minItems": 0,
+ "maxItems": 32,
+ "description": "Replacement plugin configuration installed for each new session."
+ },
+ "files": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParam"
+ },
+ "minItems": 0,
+ "maxItems": 50,
+ "description": "Replacement file configuration materialized for each new session."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Fields to replace on an existing reusable OpenAI-hosted environment template."
+ },
+ "DeletedEnvironmentTemplateResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted environment template."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.environment.template.deleted"
+ ],
+ "default": "agent.environment.template.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.environment.template.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the environment template was deleted. Always `true`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "A deleted reusable environment template."
+ },
+ "SessionStatusResource": {
+ "type": "string",
+ "enum": [
+ "idle",
+ "in_progress",
+ "requires_action",
+ "failed"
+ ],
+ "x-enumDescriptions": [
+ "The session has no turn in progress and is ready for input. A hosted environment may still be provisioning.",
+ "The session is processing a turn.",
+ "The session is waiting for one or more required actions.",
+ "The session failed."
+ ],
+ "description": "The current status of a session."
+ },
+ "SessionRequiredActionResourceFunctionCall": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function_call"
+ ],
+ "default": "function_call",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `function_call`."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that requested the function call."
+ },
+ "call_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID to include when submitting the function result."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The function name."
+ },
+ "arguments": {
+ "description": "The arguments supplied by the model."
+ }
+ },
+ "required": [
+ "type",
+ "turn_id",
+ "call_id",
+ "name",
+ "arguments"
+ ],
+ "additionalProperties": false,
+ "description": "Run a function tool and submit its result."
+ },
+ "SessionRequiredActionResourceEnvironmentConnection": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "environment_connection"
+ ],
+ "default": "environment_connection",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `environment_connection`."
+ },
+ "environment_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the environment to reconnect."
+ }
+ },
+ "required": [
+ "type",
+ "environment_id"
+ ],
+ "additionalProperties": false,
+ "description": "Reconnect a session environment."
+ },
+ "SessionRequiredActionResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/SessionRequiredActionResourceFunctionCall"
+ },
+ {
+ "$ref": "#/components/schemas/SessionRequiredActionResourceEnvironmentConnection"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "function_call": "#/components/schemas/SessionRequiredActionResourceFunctionCall",
+ "environment_connection": "#/components/schemas/SessionRequiredActionResourceEnvironmentConnection"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "function_call",
+ "environment_connection"
+ ],
+ "description": "An action that must be completed before a session can continue."
+ },
+ "AgentToolResourceFunction": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function"
+ ],
+ "default": "function",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `function`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The name of the function."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A description of what the function does."
+ },
+ "parameters": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "A JSON Schema object describing the function's arguments."
+ },
+ "defer_loading": {
+ "type": "boolean",
+ "description": "Whether the function is deferred and discovered through tool search."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "parameters",
+ "defer_loading"
+ ],
+ "additionalProperties": false,
+ "description": "A function defined by the application."
+ },
+ "AgentToolResourceProgrammaticToolCalling": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "programmatic_tool_calling"
+ ],
+ "default": "programmatic_tool_calling",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `programmatic_tool_calling`."
+ },
+ "enabled": {
+ "type": "boolean",
+ "description": "Whether tools can be called from model-generated code."
+ }
+ },
+ "required": [
+ "type",
+ "enabled"
+ ],
+ "additionalProperties": false,
+ "description": "Enables calling tools from model-generated code."
+ },
+ "McpTransportResourceHttp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "http"
+ ],
+ "default": "http",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `http`."
+ },
+ "server_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The URL of the MCP server."
+ }
+ },
+ "required": [
+ "type",
+ "server_url"
+ ],
+ "additionalProperties": false,
+ "description": "Connects to an MCP server over HTTP."
+ },
+ "McpTransportResourceStdio": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "stdio"
+ ],
+ "default": "stdio",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `stdio`."
+ },
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The command used to start the MCP server."
+ },
+ "args": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Arguments passed to the MCP server command."
+ },
+ "cwd": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The working directory used to start the MCP server."
+ },
+ "env_vars": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Environment variable names inherited from the execution environment."
+ }
+ },
+ "required": [
+ "type",
+ "command",
+ "args",
+ "cwd",
+ "env_vars"
+ ],
+ "additionalProperties": false,
+ "description": "Starts an MCP server as a local process."
+ },
+ "McpTransportResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/McpTransportResourceHttp"
+ },
+ {
+ "$ref": "#/components/schemas/McpTransportResourceStdio"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "http": "#/components/schemas/McpTransportResourceHttp",
+ "stdio": "#/components/schemas/McpTransportResourceStdio"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "http",
+ "stdio"
+ ],
+ "description": "The transport used to connect to an MCP server."
+ },
+ "AgentToolResourceMcp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp"
+ ],
+ "default": "mcp",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp`."
+ },
+ "server_label": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A label used to identify the MCP server in tool calls."
+ },
+ "credential_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The attached vault credential selected for this MCP server, if any. Optional when exactly one attached credential matches the server URL."
+ },
+ "transport": {
+ "$ref": "#/components/schemas/McpTransportResource",
+ "description": "The transport used to connect to the MCP server."
+ },
+ "request_metadata": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Metadata included with requests to this MCP server."
+ },
+ "allowed_tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The MCP tools the agent may call."
+ },
+ "required": {
+ "type": "boolean",
+ "description": "Whether this MCP server must initialize before the first turn."
+ },
+ "connection_origin": {
+ "$ref": "#/components/schemas/McpConnectionOriginResource",
+ "description": "Where outbound MCP HTTP connections originate."
+ }
+ },
+ "required": [
+ "type",
+ "server_label",
+ "credential_id",
+ "transport",
+ "request_metadata",
+ "allowed_tools",
+ "required",
+ "connection_origin"
+ ],
+ "additionalProperties": false,
+ "description": "Tools provided by a remote MCP server."
+ },
+ "AgentToolResourceWebSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "web_search"
+ ],
+ "default": "web_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `web_search`."
+ },
+ "mode": {
+ "$ref": "#/components/schemas/WebSearchModeResource",
+ "description": "The source used for web search results."
+ },
+ "context_size": {
+ "$ref": "#/components/schemas/WebSearchContextSizeResource",
+ "description": "The amount of search context made available to the model. Defaults to `medium`."
+ },
+ "allowed_domains": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Allowed search domains, or `null` when the search is unrestricted."
+ },
+ "location": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchLocationResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Approximate location used to localize search results, if provided."
+ }
+ },
+ "required": [
+ "type",
+ "mode",
+ "context_size",
+ "allowed_domains",
+ "location"
+ ],
+ "additionalProperties": false,
+ "description": "Web search."
+ },
+ "AgentToolResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/AgentToolResourceFunction"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolResourceProgrammaticToolCalling"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolResourceMcp"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolResourceWebSearch"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "function": "#/components/schemas/AgentToolResourceFunction",
+ "programmatic_tool_calling": "#/components/schemas/AgentToolResourceProgrammaticToolCalling",
+ "mcp": "#/components/schemas/AgentToolResourceMcp",
+ "web_search": "#/components/schemas/AgentToolResourceWebSearch"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "function",
+ "programmatic_tool_calling",
+ "mcp",
+ "web_search"
+ ],
+ "description": "A tool available to the agent."
+ },
+ "SessionAgentResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the agent."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The reusable agent's name when the session was created, or null if no name was saved. Later changes to the agent's name do not affect this value."
+ },
+ "model": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The model used by the agent."
+ },
+ "reasoning": {
+ "$ref": "#/components/schemas/ReasoningResource",
+ "description": "The agent's reasoning configuration."
+ },
+ "text": {
+ "$ref": "#/components/schemas/TextResource",
+ "description": "Configuration for text generated by the agent."
+ },
+ "service_tier": {
+ "$ref": "#/components/schemas/ServiceTierResource",
+ "description": "The effective service-tier policy for model requests. Defaults to `auto`."
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "Custom instructions appended to the agent's default base instructions."
+ },
+ "tools": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/AgentToolResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Tools available to the agent."
+ },
+ "multi_agent": {
+ "$ref": "#/components/schemas/MultiAgentConfigResource",
+ "description": "Configuration for creating and coordinating subagents."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.AgentsCore"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "model",
+ "reasoning",
+ "text",
+ "service_tier",
+ "instructions",
+ "tools",
+ "multi_agent"
+ ],
+ "additionalProperties": false,
+ "description": "The effective agent configuration for a session."
+ },
+ "EnvironmentResourceNone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "none"
+ ],
+ "default": "none",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `none`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "The session talks to CCA without selecting or provisioning an execution environment."
+ },
+ "EnvironmentResourceOpenaiHosted": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "openai_hosted"
+ ],
+ "default": "openai_hosted",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `openai_hosted`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The public ID of the environment."
+ },
+ "packages": {
+ "$ref": "#/components/schemas/EnvironmentPackagesResource",
+ "description": "Packages installed in the environment."
+ },
+ "network": {
+ "$ref": "#/components/schemas/NetworkPolicyResource",
+ "description": "The effective network access policy for the environment."
+ },
+ "capability_directories": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Directories that contain capabilities exposed to the agent."
+ },
+ "skills": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedSkillResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Skills installed in the environment, excluding their archive contents."
+ },
+ "plugins": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Plugins installed in the environment, excluding their archive contents."
+ },
+ "files": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileResource"
+ },
+ "minItems": 0,
+ "maxItems": 50,
+ "description": "Files available in the environment, excluding their contents."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "packages",
+ "network",
+ "capability_directories",
+ "skills",
+ "plugins",
+ "files"
+ ],
+ "additionalProperties": false,
+ "description": "An environment hosted by OpenAI."
+ },
+ "EnvironmentResourceSelfHosted": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "self_hosted"
+ ],
+ "default": "self_hosted",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `self_hosted`."
+ },
+ "remote_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "Pass this URL unchanged to `codex exec-server --remote` when connecting this environment."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The public ID of the environment."
+ },
+ "workspace_directory": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The absolute project directory inside the environment. Defaults to `/workspace`."
+ },
+ "capability_directories": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Directories that contain capabilities exposed to the agent."
+ }
+ },
+ "required": [
+ "type",
+ "remote_url",
+ "id",
+ "workspace_directory",
+ "capability_directories"
+ ],
+ "additionalProperties": false,
+ "description": "An environment hosted by the application."
+ },
+ "EnvironmentResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/EnvironmentResourceNone"
+ },
+ {
+ "$ref": "#/components/schemas/EnvironmentResourceOpenaiHosted"
+ },
+ {
+ "$ref": "#/components/schemas/EnvironmentResourceSelfHosted"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "none": "#/components/schemas/EnvironmentResourceNone",
+ "openai_hosted": "#/components/schemas/EnvironmentResourceOpenaiHosted",
+ "self_hosted": "#/components/schemas/EnvironmentResourceSelfHosted"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "none",
+ "openai_hosted",
+ "self_hosted"
+ ],
+ "description": "The execution environment for a session."
+ },
+ "SessionResource": {
+ "type": "object",
+ "properties": {
+ "metadata": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Custom string key-value pairs attached to the session."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.session"
+ ],
+ "default": "agent.session",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.session`."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the session was created."
+ },
+ "last_active_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the session was last active."
+ },
+ "status": {
+ "$ref": "#/components/schemas/SessionStatusResource",
+ "description": "The current status of the session."
+ },
+ "required_actions": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SessionRequiredActionResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "Actions that must be completed before the session can continue."
+ },
+ "error": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The error that caused the session to fail, if any."
+ },
+ "agent": {
+ "$ref": "#/components/schemas/SessionAgentResource",
+ "description": "The agent running in the session."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/EnvironmentResource",
+ "description": "The execution environment for the session."
+ },
+ "vault_ids": {
+ "type": "array",
+ "items": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The IDs of vaults made available to the session."
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TokenUsageResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Best-effort token usage for the session, or null if unknown. Recorded usage may change."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.SessionCore"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "metadata",
+ "id",
+ "object",
+ "created_at",
+ "last_active_at",
+ "status",
+ "required_actions",
+ "error",
+ "agent",
+ "environment",
+ "vault_ids",
+ "usage"
+ ],
+ "additionalProperties": false,
+ "description": "A Managed Agents session."
+ },
+ "SessionListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SessionResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "AgentToolConfigParamFunction": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "function"
+ ],
+ "default": "function",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `function`."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The name of the function."
+ },
+ "description": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A description of what the function does."
+ },
+ "parameters": {
+ "type": "object",
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "A JSON Schema object describing the function's arguments."
+ },
+ "defer_loading": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether this function is deferred and discovered through tool search. Defaults to `false`."
+ }
+ },
+ "required": [
+ "type",
+ "name",
+ "description",
+ "parameters"
+ ],
+ "additionalProperties": false,
+ "description": "A function defined by the application."
+ },
+ "AgentToolConfigParamToolSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "tool_search"
+ ],
+ "default": "tool_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `tool_search`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Discovers deferred function tools and loads them into the model context."
+ },
+ "AgentToolConfigParamProgrammaticToolCalling": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "programmatic_tool_calling"
+ ],
+ "default": "programmatic_tool_calling",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `programmatic_tool_calling`."
+ },
+ "enabled": {
+ "type": "boolean",
+ "default": true,
+ "description": "Whether tools can be called from model-generated code. Defaults to `true`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Enables calling tools from model-generated code."
+ },
+ "McpTransportConfigParamHttp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "http"
+ ],
+ "default": "http",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `http`."
+ },
+ "server_url": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The URL of the MCP server."
+ },
+ "authorization": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The authorization value sent to the MCP server, if any."
+ },
+ "headers": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Additional HTTP headers sent to the MCP server."
+ }
+ },
+ "required": [
+ "type",
+ "server_url"
+ ],
+ "additionalProperties": false,
+ "description": "Connects to an MCP server over HTTP."
+ },
+ "McpTransportConfigParamStdio": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "stdio"
+ ],
+ "default": "stdio",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `stdio`."
+ },
+ "command": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The command used to start the MCP server."
+ },
+ "args": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Arguments passed to the MCP server command."
+ },
+ "cwd": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The working directory used to start the MCP server."
+ },
+ "env": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Environment variables set for the MCP server process."
+ },
+ "env_vars": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Environment variable names to inherit from the selected execution environment."
+ }
+ },
+ "required": [
+ "type",
+ "command",
+ "cwd"
+ ],
+ "additionalProperties": false,
+ "description": "Starts an MCP server as a local process."
+ },
+ "McpTransportConfigParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/McpTransportConfigParamHttp"
+ },
+ {
+ "$ref": "#/components/schemas/McpTransportConfigParamStdio"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "http": "#/components/schemas/McpTransportConfigParamHttp",
+ "stdio": "#/components/schemas/McpTransportConfigParamStdio"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "http",
+ "stdio"
+ ],
+ "description": "The transport used to connect to an MCP server."
+ },
+ "AgentToolConfigParamMcp": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp"
+ ],
+ "default": "mcp",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp`."
+ },
+ "server_label": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A label used to identify the MCP server in tool calls."
+ },
+ "credential_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The attached vault credential used to authenticate this MCP server. Optional when exactly one attached credential matches the server URL."
+ },
+ "transport": {
+ "$ref": "#/components/schemas/McpTransportConfigParam",
+ "description": "The transport used to connect to the MCP server."
+ },
+ "request_metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {},
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Metadata included with requests to this MCP server."
+ },
+ "allowed_tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The MCP tools the agent may call. All server tools are allowed when omitted."
+ },
+ "required": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether this MCP server must initialize before the first turn. Defaults to `false`."
+ },
+ "connection_origin": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/McpConnectionOriginParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Selects where outbound MCP HTTP connections originate. Omitted or `service` uses the Managed Agents service network; `environment` uses the session's selected environment."
+ }
+ },
+ "required": [
+ "type",
+ "server_label",
+ "transport"
+ ],
+ "additionalProperties": false,
+ "description": "Tools provided by a remote MCP server."
+ },
+ "AgentToolConfigParamWebSearch": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "web_search"
+ ],
+ "default": "web_search",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `web_search`."
+ },
+ "mode": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchModeParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The source used for web search results. Defaults to `live`."
+ },
+ "context_size": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchContextSizeParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The amount of search context made available to the model. Defaults to `medium`."
+ },
+ "allowed_domains": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Domains the search may include."
+ },
+ "location": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/WebSearchLocationParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Approximate location used to localize search results."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Web search."
+ },
+ "AgentToolConfigParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/AgentToolConfigParamFunction"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolConfigParamToolSearch"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolConfigParamProgrammaticToolCalling"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolConfigParamMcp"
+ },
+ {
+ "$ref": "#/components/schemas/AgentToolConfigParamWebSearch"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "function": "#/components/schemas/AgentToolConfigParamFunction",
+ "tool_search": "#/components/schemas/AgentToolConfigParamToolSearch",
+ "programmatic_tool_calling": "#/components/schemas/AgentToolConfigParamProgrammaticToolCalling",
+ "mcp": "#/components/schemas/AgentToolConfigParamMcp",
+ "web_search": "#/components/schemas/AgentToolConfigParamWebSearch"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "function",
+ "tool_search",
+ "programmatic_tool_calling",
+ "mcp",
+ "web_search"
+ ],
+ "description": "A tool available to the agent."
+ },
+ "SessionAgentConfigParam": {
+ "type": "object",
+ "properties": {
+ "model": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The model to use for the agent. The requested model name is preserved."
+ },
+ "reasoning": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ReasoningParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for model reasoning. Omit to keep the current settings; pass `null` to reset to the model's default effort."
+ },
+ "text": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TextParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for text generated by the agent."
+ },
+ "service_tier": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/ServiceTierParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The service tier used for model requests."
+ },
+ "instructions": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Additional instructions appended to the agent's default base instructions. Omit to leave unchanged."
+ },
+ "multi_agent": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/MultiAgentConfigCurrentParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Configuration for creating and coordinating subagents."
+ },
+ "tools": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/AgentToolConfigParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Tools available to the agent. Omit to inherit, or pass null to clear them."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.AgentsCore"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "additionalProperties": false,
+ "description": "Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields."
+ },
+ "EnvironmentParamNone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "none"
+ ],
+ "default": "none",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `none`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Runs the agent without an execution environment."
+ },
+ "EnvironmentParamOpenaiHosted": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "openai_hosted"
+ ],
+ "default": "openai_hosted",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `openai_hosted`."
+ },
+ "packages": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/EnvironmentPackagesParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Packages to install in the environment. Defaults to empty package lists."
+ },
+ "setup_commands": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/SetupCommandParam"
+ },
+ "minItems": 0,
+ "maxItems": 16,
+ "description": "Ordered, confidential setup commands. Command bodies are never returned."
+ },
+ "network": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/NetworkPolicyParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Network access policy for the environment. Defaults to enabled."
+ },
+ "env": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Environment variables made available to the agent."
+ },
+ "capability_directories": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Directories that contain capabilities exposed to the agent. Defaults to an empty list."
+ },
+ "skills": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedSkillParam"
+ },
+ "minItems": 0,
+ "maxItems": 200,
+ "description": "Skills referenced by ID or provided as inline ZIP archives. Defaults to an empty list."
+ },
+ "plugins": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedPluginParam"
+ },
+ "minItems": 0,
+ "maxItems": 32,
+ "description": "Plugins provided as inline ZIP archives. Defaults to an empty list."
+ },
+ "files": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "$ref": "#/components/schemas/HostedEnvironmentFileParam"
+ },
+ "minItems": 0,
+ "maxItems": 50,
+ "description": "Files available before the agent starts. Defaults to an empty list."
+ },
+ "environment_template_id": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 64,
+ "description": "A reusable hosted template applied before inline session configuration. Omitted fields inherit the template; network overrides cannot broaden its policy."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "An OpenAI-hosted environment, optionally based on a reusable template."
+ },
+ "EnvironmentParamSelfHosted": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "self_hosted"
+ ],
+ "default": "self_hosted",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `self_hosted`."
+ },
+ "workspace_directory": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Absolute project directory inside the self-hosted environment."
+ },
+ "capability_directories": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "Directories that contain capabilities exposed to the agent. Defaults to an empty list."
+ }
+ },
+ "required": [
+ "type",
+ "workspace_directory"
+ ],
+ "additionalProperties": false,
+ "description": "An application-hosted environment configured inline."
+ },
+ "EnvironmentParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/EnvironmentParamNone"
+ },
+ {
+ "$ref": "#/components/schemas/EnvironmentParamOpenaiHosted"
+ },
+ {
+ "$ref": "#/components/schemas/EnvironmentParamSelfHosted"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "none": "#/components/schemas/EnvironmentParamNone",
+ "openai_hosted": "#/components/schemas/EnvironmentParamOpenaiHosted",
+ "self_hosted": "#/components/schemas/EnvironmentParamSelfHosted"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "none",
+ "openai_hosted",
+ "self_hosted"
+ ],
+ "description": "The execution environment and optional reusable template for a session."
+ },
+ "InputContentParamInputText": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_text"
+ ],
+ "default": "input_text",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_text`."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The text sent to the model."
+ }
+ },
+ "required": [
+ "type",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Text input to the model."
+ },
+ "InputContentParamInputImage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "input_image"
+ ],
+ "default": "input_image",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `input_image`."
+ },
+ "image_url": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The URL of the image sent to the model."
+ }
+ },
+ "required": [
+ "type",
+ "image_url"
+ ],
+ "additionalProperties": false,
+ "description": "Image input to the model."
+ },
+ "InputContentParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/InputContentParamInputText"
+ },
+ {
+ "$ref": "#/components/schemas/InputContentParamInputImage"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "input_text": "#/components/schemas/InputContentParamInputText",
+ "input_image": "#/components/schemas/InputContentParamInputImage"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "input_text",
+ "input_image"
+ ],
+ "description": "Content included in an input message."
+ },
+ "InputMessageParam": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "message"
+ ],
+ "default": "message",
+ "x-stainless-const": true,
+ "description": "The type of the input item. Always `message`."
+ },
+ "role": {
+ "type": "string",
+ "enum": [
+ "user"
+ ],
+ "default": "user",
+ "x-stainless-const": true,
+ "description": "The role of the message author. Always `user`."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/InputContentParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The content of the message."
+ }
+ },
+ "required": [
+ "role",
+ "content"
+ ],
+ "additionalProperties": false,
+ "description": "A user message submitted to a session."
+ },
+ "CreateSessionInputParam": {
+ "oneOf": [
+ {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1048576
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/InputMessageParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384
+ }
+ ],
+ "description": "Initial input submitted when creating a session."
+ },
+ "CreateAgentSessionParams": {
+ "type": "object",
+ "properties": {
+ "metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 512
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64
+ },
+ "minProperties": 0,
+ "maxProperties": 16,
+ "description": "Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map."
+ },
+ "agent": {
+ "$ref": "#/components/schemas/SessionAgentConfigParam",
+ "description": "Agent configuration. With `agent_id`, supplied fields override the saved agent for this session. Without `agent_id`, `model` is required."
+ },
+ "agent_id": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 64,
+ "description": "The ID of a saved reusable agent. Omit `agent` to use its configuration unchanged."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/EnvironmentParam",
+ "description": "An inline execution environment or a reference to an environment template."
+ },
+ "vault_ids": {
+ "type": [
+ "array",
+ "null"
+ ],
+ "items": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The IDs of vaults made available to the session."
+ },
+ "input": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CreateSessionInputParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Initial input to submit when the session is created. A string is shorthand for a single user message. Required when `environment.type` is `none`, or when `stream` is `true` for an environment that is not `self_hosted`; optional for self-hosted and non-streaming execution environments."
+ },
+ "stream": {
+ "type": "boolean",
+ "default": false,
+ "description": "Whether to stream session events as server-sent events. Defaults to `false`."
+ },
+ "x_agents_core": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/v1.SessionExecutionInput"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Parameters for creating a Managed Agents session."
+ },
+ "SessionErrorResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The error type."
+ },
+ "code": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The machine-readable error code, if any."
+ },
+ "message": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A customer-safe explanation of the error."
+ },
+ "param": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The request parameter associated with the error, if any."
+ }
+ },
+ "required": [
+ "type",
+ "code",
+ "message",
+ "param"
+ ],
+ "additionalProperties": false,
+ "description": "An error payload with the same public fields as Responses API streaming errors."
+ },
+ "SessionEventError": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "error"
+ ],
+ "default": "error",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `error`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "error": {
+ "$ref": "#/components/schemas/SessionErrorResource",
+ "description": "The error that occurred."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "error"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn or session fails.",
+ "x-oaiMeta": {
+ "example": {
+ "type": "error",
+ "event_id": "event_123",
+ "session_id": "sess_123",
+ "error": {
+ "type": "server_error",
+ "code": null,
+ "message": "The session failed due to an internal server error.",
+ "param": null
+ }
+ }
+ }
+ },
+ "SessionEnvironmentStatusResource": {
+ "type": "string",
+ "enum": [
+ "pending",
+ "ready",
+ "connected",
+ "disconnected",
+ "failed"
+ ],
+ "x-enumDescriptions": [
+ "The environment is being prepared.",
+ "The environment is ready to connect.",
+ "The environment is connected.",
+ "The environment is disconnected.",
+ "The environment failed to connect."
+ ],
+ "description": "The connection status of a session environment."
+ },
+ "SessionEnvironmentErrorResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The error type."
+ },
+ "code": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A machine-readable error code."
+ },
+ "message": {
+ "type": "string",
+ "minLength": 0,
+ "description": "A human-readable error message."
+ }
+ },
+ "required": [
+ "type",
+ "code",
+ "message"
+ ],
+ "additionalProperties": false,
+ "description": "An error reported while preparing a session environment."
+ },
+ "SessionEnvironmentStateResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The public ID of the environment."
+ },
+ "type": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The environment type."
+ },
+ "status": {
+ "$ref": "#/components/schemas/SessionEnvironmentStatusResource",
+ "description": "The environment's connection status."
+ },
+ "error": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/SessionEnvironmentErrorResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The error reported while preparing the environment, if any."
+ }
+ },
+ "required": [
+ "id",
+ "type",
+ "status",
+ "error"
+ ],
+ "additionalProperties": false,
+ "description": "The current state of a session environment."
+ },
+ "SessionEventAgentSessionEnvironmentReady": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.environment.ready"
+ ],
+ "default": "agent.session.environment.ready",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.environment.ready`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/SessionEnvironmentStateResource",
+ "description": "The current environment state."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a hosted session environment is ready to connect."
+ },
+ "SessionEventAgentOutputCommandExecutionOutputDelta": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.output.command_execution_output.delta"
+ ],
+ "default": "agent.output.command_execution_output.delta",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.output.command_execution_output.delta`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the command execution item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "delta": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The output text that was appended."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "delta"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when command execution produces an output delta."
+ },
+ "SessionEventAgentSessionCreated": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.created"
+ ],
+ "default": "agent.session.created",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.created`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session": {
+ "$ref": "#/components/schemas/SessionResource",
+ "description": "The session that was created."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session is created."
+ },
+ "SessionEventAgentSessionTurnCreated": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.created"
+ ],
+ "default": "agent.session.turn.created",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.created`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event."
+ },
+ "turn": {
+ "$ref": "#/components/schemas/TurnResource",
+ "description": "The turn at the time it was created."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "turn"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn is created."
+ },
+ "SessionEventAgentSessionTurnInProgress": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.in_progress"
+ ],
+ "default": "agent.session.turn.in_progress",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.in_progress`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event."
+ },
+ "turn": {
+ "$ref": "#/components/schemas/TurnResource",
+ "description": "The turn at the time it started running."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "turn"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn starts running."
+ },
+ "SessionEventAgentSessionTurnCompleted": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.completed"
+ ],
+ "default": "agent.session.turn.completed",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.completed`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event."
+ },
+ "turn": {
+ "$ref": "#/components/schemas/TurnResource",
+ "description": "The completed turn."
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TokenUsageResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Token usage by the root agent during the turn, when available."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "turn",
+ "usage"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn completes."
+ },
+ "SessionEventAgentSessionTurnFailed": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.failed"
+ ],
+ "default": "agent.session.turn.failed",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.failed`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event."
+ },
+ "turn": {
+ "$ref": "#/components/schemas/TurnResource",
+ "description": "The failed turn."
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TokenUsageResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Token usage by the root agent during the turn, when available."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "turn",
+ "usage"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn fails."
+ },
+ "SessionEventAgentSessionTurnCancelled": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.cancelled"
+ ],
+ "default": "agent.session.turn.cancelled",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.cancelled`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event."
+ },
+ "turn": {
+ "$ref": "#/components/schemas/TurnResource",
+ "description": "The cancelled turn."
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/TokenUsageResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Token usage by the root agent during the turn, when available."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "turn",
+ "usage"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a turn is cancelled."
+ },
+ "SessionEventAgentSessionTurnItemAdded": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.item.added"
+ ],
+ "default": "agent.session.turn.item.added",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.item.added`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "output_index": {
+ "type": [
+ "integer",
+ "null"
+ ],
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output, when the item is agent output."
+ },
+ "item": {
+ "$ref": "#/components/schemas/SessionTurnItemResource",
+ "description": "The item that was added."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "output_index",
+ "item"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when an item is added to a turn."
+ },
+ "SessionEventAgentSessionIdle": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.idle"
+ ],
+ "default": "agent.session.idle",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.idle`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session": {
+ "$ref": "#/components/schemas/SessionResource",
+ "description": "The session that became idle."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session becomes idle."
+ },
+ "SessionEventAgentSessionInProgress": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.in_progress"
+ ],
+ "default": "agent.session.in_progress",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.in_progress`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session": {
+ "$ref": "#/components/schemas/SessionResource",
+ "description": "The session that started processing."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session starts processing a turn."
+ },
+ "SessionEventAgentSessionRequiresAction": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.requires_action"
+ ],
+ "default": "agent.session.requires_action",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.requires_action`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session": {
+ "$ref": "#/components/schemas/SessionResource",
+ "description": "The session and its current required actions."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session is waiting for one or more required actions."
+ },
+ "SessionEventAgentSessionFailed": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.failed"
+ ],
+ "default": "agent.session.failed",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.failed`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session": {
+ "$ref": "#/components/schemas/SessionResource",
+ "description": "The failed session."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session fails."
+ },
+ "SessionEventAgentSessionEnvironmentPending": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.environment.pending"
+ ],
+ "default": "agent.session.environment.pending",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.environment.pending`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/SessionEnvironmentStateResource",
+ "description": "The current environment state."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted while a session environment is being prepared."
+ },
+ "SessionEventAgentSessionEnvironmentConnected": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.environment.connected"
+ ],
+ "default": "agent.session.environment.connected",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.environment.connected`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/SessionEnvironmentStateResource",
+ "description": "The current environment state."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session environment connects."
+ },
+ "SessionEventAgentSessionEnvironmentDisconnected": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.environment.disconnected"
+ ],
+ "default": "agent.session.environment.disconnected",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.environment.disconnected`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/SessionEnvironmentStateResource",
+ "description": "The current environment state."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session environment disconnects."
+ },
+ "SessionEventAgentSessionEnvironmentFailed": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.environment.failed"
+ ],
+ "default": "agent.session.environment.failed",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.environment.failed`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "environment": {
+ "$ref": "#/components/schemas/SessionEnvironmentStateResource",
+ "description": "The current environment state."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "environment"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a session environment fails."
+ },
+ "SessionEventAgentSessionSubagentCreated": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.subagent.created"
+ ],
+ "default": "agent.session.subagent.created",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.subagent.created`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "subagent": {
+ "$ref": "#/components/schemas/SubagentResource",
+ "description": "The subagent that was created."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "subagent"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a subagent is created."
+ },
+ "SessionEventAgentSessionSubagentActive": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.subagent.active"
+ ],
+ "default": "agent.session.subagent.active",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.subagent.active`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "subagent": {
+ "$ref": "#/components/schemas/SubagentResource",
+ "description": "The subagent that resumed."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "subagent"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a closed subagent successfully resumes."
+ },
+ "SessionEventAgentSessionSubagentClosed": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.subagent.closed"
+ ],
+ "default": "agent.session.subagent.closed",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.subagent.closed`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "subagent": {
+ "$ref": "#/components/schemas/SubagentResource",
+ "description": "The subagent that was closed."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "subagent"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a subagent is closed."
+ },
+ "AssistantMessageItemResource": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "message"
+ ],
+ "default": "message",
+ "x-stainless-const": true,
+ "description": "The item type. Always `message`."
+ },
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the turn that contains this item."
+ },
+ "role": {
+ "type": "string",
+ "enum": [
+ "assistant"
+ ],
+ "default": "assistant",
+ "x-stainless-const": true,
+ "description": "The role of the message author. Always `assistant`."
+ },
+ "status": {
+ "$ref": "#/components/schemas/OutputItemStatusResource",
+ "description": "The status of the message."
+ },
+ "content": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/OutputTextResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The content of the message."
+ },
+ "phase": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/MessagePhaseResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The phase of the assistant message."
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "turn_id",
+ "role",
+ "status",
+ "content",
+ "phase"
+ ],
+ "additionalProperties": false,
+ "description": "An assistant message produced by the agent."
+ },
+ "AgentOutputItemResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/AssistantMessageItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/ReasoningItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/FunctionCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/McpCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/WebSearchCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CommandExecutionItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CreateSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/SendSubagentInputCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/ResumeSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/WaitForSubagentsCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/InterruptSubagentCallItemResource"
+ },
+ {
+ "$ref": "#/components/schemas/CloseSubagentCallItemResource"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "message": "#/components/schemas/AssistantMessageItemResource",
+ "reasoning": "#/components/schemas/ReasoningItemResource",
+ "function_call": "#/components/schemas/FunctionCallItemResource",
+ "mcp_call": "#/components/schemas/McpCallItemResource",
+ "web_search_call": "#/components/schemas/WebSearchCallItemResource",
+ "command_execution": "#/components/schemas/CommandExecutionItemResource",
+ "interrupt_subagent_call": "#/components/schemas/InterruptSubagentCallItemResource",
+ "create_subagent_call": "#/components/schemas/CreateSubagentCallItemResource",
+ "send_subagent_input_call": "#/components/schemas/SendSubagentInputCallItemResource",
+ "resume_subagent_call": "#/components/schemas/ResumeSubagentCallItemResource",
+ "wait_for_subagents_call": "#/components/schemas/WaitForSubagentsCallItemResource",
+ "close_subagent_call": "#/components/schemas/CloseSubagentCallItemResource"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "message",
+ "reasoning",
+ "function_call",
+ "mcp_call",
+ "web_search_call",
+ "command_execution",
+ "create_subagent_call",
+ "send_subagent_input_call",
+ "resume_subagent_call",
+ "wait_for_subagents_call",
+ "interrupt_subagent_call",
+ "close_subagent_call"
+ ],
+ "description": "An output item produced by an agent."
+ },
+ "SessionEventAgentSessionTurnItemDone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.item.done"
+ ],
+ "default": "agent.session.turn.item.done",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.item.done`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the output item in the turn output."
+ },
+ "item": {
+ "$ref": "#/components/schemas/AgentOutputItemResource",
+ "description": "The completed output item."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "output_index",
+ "item"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when an output item is complete."
+ },
+ "SessionEventAgentSessionTurnContentPartAdded": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.content_part.added"
+ ],
+ "default": "agent.session.turn.content_part.added",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.content_part.added`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "content_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the content part in the message."
+ },
+ "part": {
+ "$ref": "#/components/schemas/OutputTextResource",
+ "description": "The initial content part."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "content_index",
+ "part"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when an output text content part is added."
+ },
+ "SessionEventAgentSessionTurnContentPartDone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.content_part.done"
+ ],
+ "default": "agent.session.turn.content_part.done",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.content_part.done`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "content_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the content part in the message."
+ },
+ "part": {
+ "$ref": "#/components/schemas/OutputTextResource",
+ "description": "The completed content part."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "content_index",
+ "part"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when an output content part is complete."
+ },
+ "SessionEventAgentSessionTurnOutputTextDelta": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.output_text.delta"
+ ],
+ "default": "agent.session.turn.output_text.delta",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.output_text.delta`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "content_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the content part in the message."
+ },
+ "delta": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The text that was appended."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "content_index",
+ "delta"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when text is appended to an output text content part."
+ },
+ "SessionEventAgentSessionTurnOutputTextDone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.output_text.done"
+ ],
+ "default": "agent.session.turn.output_text.done",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.output_text.done`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the message item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "content_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the content part in the message."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The complete output text."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "content_index",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when an output text content part is complete."
+ },
+ "SessionEventAgentSessionTurnReasoningSummaryPartAdded": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.reasoning_summary_part.added"
+ ],
+ "default": "agent.session.turn.reasoning_summary_part.added",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.reasoning_summary_part.added`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reasoning item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "summary_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the summary content part."
+ },
+ "part": {
+ "$ref": "#/components/schemas/SummaryTextResource",
+ "description": "The initial summary part."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "summary_index",
+ "part"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a reasoning summary content part is added."
+ },
+ "SessionEventAgentSessionTurnReasoningSummaryPartDone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.reasoning_summary_part.done"
+ ],
+ "default": "agent.session.turn.reasoning_summary_part.done",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.reasoning_summary_part.done`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reasoning item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "summary_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the summary part."
+ },
+ "part": {
+ "$ref": "#/components/schemas/SummaryTextResource",
+ "description": "The completed summary part."
+ },
+ "status": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "enum": [
+ "incomplete",
+ null
+ ],
+ "description": "Present as `incomplete` when summary generation was interrupted.",
+ "x-stainless-const": true
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "summary_index",
+ "part",
+ "status"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a reasoning summary part is complete."
+ },
+ "SessionEventAgentSessionTurnReasoningSummaryTextDelta": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.reasoning_summary_text.delta"
+ ],
+ "default": "agent.session.turn.reasoning_summary_text.delta",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.reasoning_summary_text.delta`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reasoning item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "summary_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the summary content part."
+ },
+ "delta": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The summary text that was appended."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "summary_index",
+ "delta"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when text is appended to a reasoning summary."
+ },
+ "SessionEventAgentSessionTurnReasoningSummaryTextDone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.turn.reasoning_summary_text.done"
+ ],
+ "default": "agent.session.turn.reasoning_summary_text.done",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.turn.reasoning_summary_text.done`."
+ },
+ "event_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The unique ID of the event."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session associated with the event."
+ },
+ "turn_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the turn associated with the event, when applicable."
+ },
+ "item_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the reasoning item."
+ },
+ "output_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the item in the turn output."
+ },
+ "summary_index": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "maximum": 4294967295,
+ "description": "The index of the summary content part."
+ },
+ "text": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The complete reasoning summary text."
+ }
+ },
+ "required": [
+ "type",
+ "event_id",
+ "session_id",
+ "turn_id",
+ "item_id",
+ "output_index",
+ "summary_index",
+ "text"
+ ],
+ "additionalProperties": false,
+ "description": "Emitted when a reasoning summary content part is complete."
+ },
+ "SessionEvent": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/SessionEventError"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionEnvironmentReady"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionCreated"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnCreated"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnInProgress"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnCompleted"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnFailed"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnCancelled"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnItemAdded"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionIdle"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionInProgress"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionRequiresAction"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionFailed"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionEnvironmentPending"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionEnvironmentConnected"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionEnvironmentFailed"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionSubagentCreated"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionSubagentActive"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionSubagentClosed"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnItemDone"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnContentPartAdded"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnContentPartDone"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnOutputTextDone"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta"
+ },
+ {
+ "$ref": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "error": "#/components/schemas/SessionEventError",
+ "agent.session.environment.ready": "#/components/schemas/SessionEventAgentSessionEnvironmentReady",
+ "agent.output.command_execution_output.delta": "#/components/schemas/SessionEventAgentOutputCommandExecutionOutputDelta",
+ "agent.session.created": "#/components/schemas/SessionEventAgentSessionCreated",
+ "agent.session.turn.created": "#/components/schemas/SessionEventAgentSessionTurnCreated",
+ "agent.session.turn.in_progress": "#/components/schemas/SessionEventAgentSessionTurnInProgress",
+ "agent.session.turn.completed": "#/components/schemas/SessionEventAgentSessionTurnCompleted",
+ "agent.session.turn.failed": "#/components/schemas/SessionEventAgentSessionTurnFailed",
+ "agent.session.turn.cancelled": "#/components/schemas/SessionEventAgentSessionTurnCancelled",
+ "agent.session.turn.item.added": "#/components/schemas/SessionEventAgentSessionTurnItemAdded",
+ "agent.session.idle": "#/components/schemas/SessionEventAgentSessionIdle",
+ "agent.session.in_progress": "#/components/schemas/SessionEventAgentSessionInProgress",
+ "agent.session.requires_action": "#/components/schemas/SessionEventAgentSessionRequiresAction",
+ "agent.session.failed": "#/components/schemas/SessionEventAgentSessionFailed",
+ "agent.session.environment.pending": "#/components/schemas/SessionEventAgentSessionEnvironmentPending",
+ "agent.session.environment.connected": "#/components/schemas/SessionEventAgentSessionEnvironmentConnected",
+ "agent.session.environment.disconnected": "#/components/schemas/SessionEventAgentSessionEnvironmentDisconnected",
+ "agent.session.environment.failed": "#/components/schemas/SessionEventAgentSessionEnvironmentFailed",
+ "agent.session.subagent.created": "#/components/schemas/SessionEventAgentSessionSubagentCreated",
+ "agent.session.subagent.active": "#/components/schemas/SessionEventAgentSessionSubagentActive",
+ "agent.session.subagent.closed": "#/components/schemas/SessionEventAgentSessionSubagentClosed",
+ "agent.session.turn.item.done": "#/components/schemas/SessionEventAgentSessionTurnItemDone",
+ "agent.session.turn.content_part.added": "#/components/schemas/SessionEventAgentSessionTurnContentPartAdded",
+ "agent.session.turn.content_part.done": "#/components/schemas/SessionEventAgentSessionTurnContentPartDone",
+ "agent.session.turn.output_text.delta": "#/components/schemas/SessionEventAgentSessionTurnOutputTextDelta",
+ "agent.session.turn.output_text.done": "#/components/schemas/SessionEventAgentSessionTurnOutputTextDone",
+ "agent.session.turn.reasoning_summary_part.added": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartAdded",
+ "agent.session.turn.reasoning_summary_part.done": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryPartDone",
+ "agent.session.turn.reasoning_summary_text.delta": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDelta",
+ "agent.session.turn.reasoning_summary_text.done": "#/components/schemas/SessionEventAgentSessionTurnReasoningSummaryTextDone"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "error",
+ "agent.session.environment.ready",
+ "agent.output.command_execution_output.delta",
+ "agent.session.created",
+ "agent.session.turn.created",
+ "agent.session.turn.in_progress",
+ "agent.session.turn.completed",
+ "agent.session.turn.failed",
+ "agent.session.turn.cancelled",
+ "agent.session.turn.item.added",
+ "agent.session.idle",
+ "agent.session.in_progress",
+ "agent.session.requires_action",
+ "agent.session.failed",
+ "agent.session.environment.pending",
+ "agent.session.environment.connected",
+ "agent.session.environment.disconnected",
+ "agent.session.environment.failed",
+ "agent.session.subagent.created",
+ "agent.session.subagent.active",
+ "agent.session.subagent.closed",
+ "agent.session.turn.item.done",
+ "agent.session.turn.content_part.added",
+ "agent.session.turn.content_part.done",
+ "agent.session.turn.output_text.delta",
+ "agent.session.turn.output_text.done",
+ "agent.session.turn.reasoning_summary_part.added",
+ "agent.session.turn.reasoning_summary_part.done",
+ "agent.session.turn.reasoning_summary_text.delta",
+ "agent.session.turn.reasoning_summary_text.done"
+ ],
+ "description": "An event emitted by a Managed Agents session."
+ },
+ "UpdateAgentSessionParams": {
+ "type": "object",
+ "properties": {
+ "metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 512
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 64
+ },
+ "minProperties": 0,
+ "maxProperties": 16,
+ "description": "Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Fields to update on an existing session."
+ },
+ "DeletedSessionResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted session."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.session.deleted"
+ ],
+ "default": "agent.session.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.session.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the session has been removed from the public API. Always `true`. Physical cleanup may still be in progress."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously."
+ },
+ "SessionArtifactResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The immutable artifact ID."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.session.artifact"
+ ],
+ "default": "agent.session.artifact",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.session.artifact`."
+ },
+ "session_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the session that owns the artifact."
+ },
+ "environment_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the environment that produced the artifact."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the completed turn that published the artifact."
+ },
+ "path": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The original absolute file path in the execution environment."
+ },
+ "size_bytes": {
+ "type": "integer",
+ "format": "int64",
+ "minimum": 0,
+ "description": "The immutable artifact size in bytes."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the artifact was published."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "session_id",
+ "environment_id",
+ "turn_id",
+ "path",
+ "size_bytes",
+ "created_at"
+ ],
+ "additionalProperties": false,
+ "description": "An immutable file published by a completed hosted session turn."
+ },
+ "SessionArtifactListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SessionArtifactResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "DeletedSessionArtifactResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted session artifact."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "agent.session.artifact.deleted"
+ ],
+ "default": "agent.session.artifact.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `agent.session.artifact.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the session artifact was deleted. Always `true`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "Confirmation that an immutable session artifact was deleted."
+ },
+ "SessionInputParamAgentSessionInputMessage": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.input.message"
+ ],
+ "default": "agent.session.input.message",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.input.message`."
+ },
+ "input": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/InputMessageParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The user messages to add to the session."
+ }
+ },
+ "required": [
+ "type",
+ "input"
+ ],
+ "additionalProperties": false,
+ "description": "Adds one or more user messages and starts a turn."
+ },
+ "SessionInputParamAgentSessionInputCancel": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.input.cancel"
+ ],
+ "default": "agent.session.input.cancel",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.input.cancel`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Cancels the session's active turn."
+ },
+ "FunctionCallOutputParam": {
+ "oneOf": [
+ {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/InputContentParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384
+ }
+ ],
+ "description": "A function result represented as text or supported model-input content."
+ },
+ "SessionInputParamAgentSessionInputToolResult": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "agent.session.input.tool_result"
+ ],
+ "default": "agent.session.input.tool_result",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `agent.session.input.tool_result`."
+ },
+ "turn_id": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The ID of the turn that requested the function call."
+ },
+ "call_id": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The ID of the function call."
+ },
+ "success": {
+ "type": "boolean",
+ "description": "Whether the function call succeeded."
+ },
+ "output": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/FunctionCallOutputParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The function result when the call succeeded."
+ },
+ "error": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The error message when the call failed."
+ }
+ },
+ "required": [
+ "type",
+ "turn_id",
+ "call_id",
+ "success"
+ ],
+ "additionalProperties": false,
+ "description": "Submits the result of a function call."
+ },
+ "SessionInputParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/SessionInputParamAgentSessionInputMessage"
+ },
+ {
+ "$ref": "#/components/schemas/SessionInputParamAgentSessionInputCancel"
+ },
+ {
+ "$ref": "#/components/schemas/SessionInputParamAgentSessionInputToolResult"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "agent.session.input.message": "#/components/schemas/SessionInputParamAgentSessionInputMessage",
+ "agent.session.input.cancel": "#/components/schemas/SessionInputParamAgentSessionInputCancel",
+ "agent.session.input.tool_result": "#/components/schemas/SessionInputParamAgentSessionInputToolResult"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "agent.session.input.message",
+ "agent.session.input.cancel",
+ "agent.session.input.tool_result"
+ ],
+ "description": "Input submitted to an existing session."
+ },
+ "CreateSessionEventsParams": {
+ "type": "object",
+ "properties": {
+ "events": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/SessionInputParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384,
+ "description": "The input events to submit to the session."
+ }
+ },
+ "required": [
+ "events"
+ ],
+ "additionalProperties": false,
+ "description": "Input events submitted to an existing session."
+ },
+ "VaultStatusParam": {
+ "type": "string",
+ "enum": [
+ "active",
+ "archived"
+ ],
+ "description": "Whether a vault or credential is active or archived."
+ },
+ "VaultStatusFilterParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/VaultStatusParam"
+ },
+ {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/VaultStatusParam"
+ },
+ "minItems": 0,
+ "maxItems": 16384
+ }
+ ],
+ "description": "One or more lifecycle statuses to include when listing vaults or credentials."
+ },
+ "VaultResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the vault."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "vault"
+ ],
+ "default": "vault",
+ "x-stainless-const": true,
+ "description": "The object type. Always `vault`."
+ },
+ "name": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The human-readable name of the vault, if set."
+ },
+ "metadata": {
+ "type": "object",
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 0
+ },
+ "minProperties": 0,
+ "description": "Key-value pairs associated with the vault, such as an application or team identifier."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the vault was created."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "name",
+ "metadata",
+ "created_at"
+ ],
+ "additionalProperties": false,
+ "description": "A collection of credentials that agent tools can use to authenticate to MCP servers."
+ },
+ "VaultListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/VaultResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "CreateVaultParams": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1048576,
+ "description": "The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming."
+ },
+ "metadata": {
+ "type": [
+ "object",
+ "null"
+ ],
+ "additionalProperties": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576
+ },
+ "propertyNames": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 256
+ },
+ "minProperties": 0,
+ "maxProperties": 1024,
+ "description": "Key-value pairs to associate with the vault, such as an application or team identifier."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Parameters for creating a vault to store credentials used by agent tools."
+ },
+ "DeletedVaultResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted vault."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "vault.deleted"
+ ],
+ "default": "vault.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `vault.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the resource was deleted. Always `true`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "Confirmation that a vault was deleted."
+ },
+ "McpOauthTokenEndpointAuthResourceNone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "none"
+ ],
+ "default": "none",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `none`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID without a client secret."
+ },
+ "McpOauthTokenEndpointAuthResourceClientSecretBasic": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_basic"
+ ],
+ "default": "client_secret_basic",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_basic`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID and secret using HTTP Basic authentication."
+ },
+ "McpOauthTokenEndpointAuthResourceClientSecretPost": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_post"
+ ],
+ "default": "client_secret_post",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_post`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID and secret in the token request body."
+ },
+ "McpOauthTokenEndpointAuthResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceNone"
+ },
+ {
+ "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic"
+ },
+ {
+ "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "none": "#/components/schemas/McpOauthTokenEndpointAuthResourceNone",
+ "client_secret_basic": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretBasic",
+ "client_secret_post": "#/components/schemas/McpOauthTokenEndpointAuthResourceClientSecretPost"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "none",
+ "client_secret_basic",
+ "client_secret_post"
+ ],
+ "description": "The client authentication method used for OAuth token refresh."
+ },
+ "McpOauthRefreshResource": {
+ "type": "object",
+ "properties": {
+ "token_endpoint": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The HTTPS OAuth token endpoint used for refresh."
+ },
+ "client_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The OAuth client ID used when requesting a new access token."
+ },
+ "resource": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The resource URI sent to the OAuth token endpoint during refresh, if configured."
+ },
+ "scope": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "Space-separated OAuth scopes requested during refresh, if configured."
+ },
+ "token_endpoint_auth": {
+ "$ref": "#/components/schemas/McpOauthTokenEndpointAuthResource",
+ "description": "How the OAuth client authenticates to the token endpoint, excluding its client secret."
+ }
+ },
+ "required": [
+ "token_endpoint",
+ "client_id",
+ "resource",
+ "scope",
+ "token_endpoint_auth"
+ ],
+ "additionalProperties": false,
+ "description": "Configuration used to refresh an MCP OAuth access token, excluding secret values."
+ },
+ "VaultCredentialAuthResourceMcpOauth": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp_oauth"
+ ],
+ "default": "mcp_oauth",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp_oauth`."
+ },
+ "mcp_server_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The HTTPS MCP server URL authorized by this credential."
+ },
+ "expires_at": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "When the OAuth access token expires, as an RFC 3339 timestamp, if known."
+ },
+ "refresh": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/McpOauthRefreshResource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Public refresh metadata without refresh tokens or OAuth client secrets."
+ }
+ },
+ "required": [
+ "type",
+ "mcp_server_url",
+ "expires_at",
+ "refresh"
+ ],
+ "additionalProperties": false,
+ "description": "Public metadata for an OAuth credential; tokens and client secrets are never returned."
+ },
+ "VaultCredentialAuthResourceStaticBearer": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "static_bearer"
+ ],
+ "default": "static_bearer",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `static_bearer`."
+ },
+ "mcp_server_url": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The HTTPS MCP server URL authorized by this credential."
+ }
+ },
+ "required": [
+ "type",
+ "mcp_server_url"
+ ],
+ "additionalProperties": false,
+ "description": "Metadata for a bearer-token credential, without automatic OAuth refresh."
+ },
+ "VaultCredentialAuthResource": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/VaultCredentialAuthResourceMcpOauth"
+ },
+ {
+ "$ref": "#/components/schemas/VaultCredentialAuthResourceStaticBearer"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "mcp_oauth": "#/components/schemas/VaultCredentialAuthResourceMcpOauth",
+ "static_bearer": "#/components/schemas/VaultCredentialAuthResourceStaticBearer"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "mcp_oauth",
+ "static_bearer"
+ ],
+ "description": "The MCP server and authentication configuration of a vault credential, excluding secrets."
+ },
+ "VaultCredentialResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the credential."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "vault.credential"
+ ],
+ "default": "vault.credential",
+ "x-stainless-const": true,
+ "description": "The object type. Always `vault.credential`."
+ },
+ "vault_id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the vault containing this credential."
+ },
+ "name": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The human-readable name of the credential."
+ },
+ "auth": {
+ "$ref": "#/components/schemas/VaultCredentialAuthResource",
+ "description": "The authentication method and non-secret configuration for the MCP server."
+ },
+ "created_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the credential was created."
+ },
+ "updated_at": {
+ "type": "integer",
+ "format": "int64",
+ "description": "The Unix timestamp, in seconds, when the credential was last updated."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "vault_id",
+ "name",
+ "auth",
+ "created_at",
+ "updated_at"
+ ],
+ "additionalProperties": false,
+ "description": "Metadata for a stored MCP server credential. Secret values are never returned."
+ },
+ "VaultCredentialListResource": {
+ "type": "object",
+ "properties": {
+ "object": {
+ "type": "string",
+ "enum": [
+ "list"
+ ],
+ "default": "list",
+ "x-stainless-const": true,
+ "description": "The object type, which is always `list`."
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/components/schemas/VaultCredentialResource"
+ },
+ "minItems": 0,
+ "maxItems": 2000,
+ "description": "The resources returned in this page, in the requested sort order."
+ },
+ "first_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the first resource in `data`, or `null` if the page is empty."
+ },
+ "last_id": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "description": "The ID of the last resource in `data`, or `null` if the page is empty. Pass this as `after` with the same order and filters."
+ },
+ "has_more": {
+ "type": "boolean",
+ "description": "Whether there are more resources to retrieve after this page."
+ }
+ },
+ "required": [
+ "object",
+ "data",
+ "first_id",
+ "last_id",
+ "has_more"
+ ],
+ "additionalProperties": false,
+ "description": "A page of Agents API resources, with IDs for retrieving additional pages."
+ },
+ "CreateMcpOauthTokenEndpointAuthParamNone": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "none"
+ ],
+ "default": "none",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `none`."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID without a client secret."
+ },
+ "CreateMcpOauthTokenEndpointAuthParamClientSecretBasic": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_basic"
+ ],
+ "default": "client_secret_basic",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_basic`."
+ },
+ "client_secret": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The OAuth client secret to store. Never returned in credential resources."
+ }
+ },
+ "required": [
+ "type",
+ "client_secret"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID and secret using HTTP Basic authentication."
+ },
+ "CreateMcpOauthTokenEndpointAuthParamClientSecretPost": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_post"
+ ],
+ "default": "client_secret_post",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_post`."
+ },
+ "client_secret": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The OAuth client secret to store. Never returned in credential resources."
+ }
+ },
+ "required": [
+ "type",
+ "client_secret"
+ ],
+ "additionalProperties": false,
+ "description": "Sends the client ID and secret in the token request body."
+ },
+ "CreateMcpOauthTokenEndpointAuthParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone"
+ },
+ {
+ "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic"
+ },
+ {
+ "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "none": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamNone",
+ "client_secret_basic": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretBasic",
+ "client_secret_post": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParamClientSecretPost"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "none",
+ "client_secret_basic",
+ "client_secret_post"
+ ],
+ "description": "Client authentication credentials for OAuth token refresh."
+ },
+ "CreateMcpOauthRefreshParam": {
+ "type": "object",
+ "properties": {
+ "token_endpoint": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The HTTPS OAuth token endpoint used to exchange the refresh token for a new access token."
+ },
+ "client_id": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The OAuth client ID used when requesting a new access token."
+ },
+ "resource": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The resource URI to send to the OAuth token endpoint during refresh, if required."
+ },
+ "scope": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Space-separated OAuth scopes to request during refresh, if required."
+ },
+ "refresh_token": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The refresh token to store. This secret is never returned in credential resources."
+ },
+ "token_endpoint_auth": {
+ "$ref": "#/components/schemas/CreateMcpOauthTokenEndpointAuthParam",
+ "description": "How the OAuth client authenticates to the token endpoint."
+ }
+ },
+ "required": [
+ "token_endpoint",
+ "client_id",
+ "refresh_token",
+ "token_endpoint_auth"
+ ],
+ "additionalProperties": false,
+ "description": "Configuration for refreshing the access token of an MCP OAuth credential."
+ },
+ "CreateVaultCredentialAuthParamMcpOauth": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp_oauth"
+ ],
+ "default": "mcp_oauth",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp_oauth`."
+ },
+ "mcp_server_url": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The HTTPS MCP server URL authorized by this credential."
+ },
+ "access_token": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A write-only OAuth access token; never returned by credential resources."
+ },
+ "expires_at": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "When the OAuth access token expires, as an RFC 3339 timestamp, if known."
+ },
+ "refresh": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/CreateMcpOauthRefreshParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional refresh configuration for an HTTPS OAuth token endpoint."
+ }
+ },
+ "required": [
+ "type",
+ "mcp_server_url",
+ "access_token"
+ ],
+ "additionalProperties": false,
+ "description": "An OAuth credential for an HTTPS MCP destination."
+ },
+ "CreateVaultCredentialAuthParamStaticBearer": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "static_bearer"
+ ],
+ "default": "static_bearer",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `static_bearer`."
+ },
+ "mcp_server_url": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The HTTPS MCP server URL authorized by this credential."
+ },
+ "token": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The bearer token to store. This secret is never returned in credential resources."
+ }
+ },
+ "required": [
+ "type",
+ "mcp_server_url",
+ "token"
+ ],
+ "additionalProperties": false,
+ "description": "A bearer token for an MCP server, without automatic OAuth refresh."
+ },
+ "CreateVaultCredentialAuthParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/CreateVaultCredentialAuthParamMcpOauth"
+ },
+ {
+ "$ref": "#/components/schemas/CreateVaultCredentialAuthParamStaticBearer"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "mcp_oauth": "#/components/schemas/CreateVaultCredentialAuthParamMcpOauth",
+ "static_bearer": "#/components/schemas/CreateVaultCredentialAuthParamStaticBearer"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "mcp_oauth",
+ "static_bearer"
+ ],
+ "description": "Authentication credentials for an MCP server used by agent tools."
+ },
+ "CreateVaultCredentialParams": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "minLength": 1,
+ "maxLength": 1048576,
+ "description": "The name is trimmed before storage. It must contain 1 to 256 UTF-8 bytes after trimming."
+ },
+ "auth": {
+ "$ref": "#/components/schemas/CreateVaultCredentialAuthParam",
+ "description": "The authentication method and secret values to store for the MCP server."
+ }
+ },
+ "required": [
+ "auth",
+ "name"
+ ],
+ "additionalProperties": false,
+ "description": "Parameters for storing a credential that authorizes access to an MCP server."
+ },
+ "RotateMcpOauthTokenEndpointAuthParamClientSecretBasic": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_basic"
+ ],
+ "default": "client_secret_basic",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_basic`."
+ },
+ "client_secret": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Updates credentials sent using HTTP Basic authentication."
+ },
+ "RotateMcpOauthTokenEndpointAuthParamClientSecretPost": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "client_secret_post"
+ ],
+ "default": "client_secret_post",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `client_secret_post`."
+ },
+ "client_secret": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The replacement OAuth client secret. Omit or pass `null` to keep the stored secret. This secret is never returned in resources."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Updates credentials sent in the token request body."
+ },
+ "RotateMcpOauthTokenEndpointAuthParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic"
+ },
+ {
+ "$ref": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "client_secret_basic": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretBasic",
+ "client_secret_post": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParamClientSecretPost"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "client_secret_basic",
+ "client_secret_post"
+ ],
+ "description": "Client-secret updates that preserve the credential's OAuth authentication method."
+ },
+ "RotateMcpOauthRefreshParam": {
+ "type": "object",
+ "properties": {
+ "refresh_token": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The replacement refresh token. Omit or pass `null` to keep the stored token. This secret is never returned in resources."
+ },
+ "scope": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "Replacement space-separated OAuth scopes for refresh requests. Omit to keep the scopes, or pass `null` to stop sending a scope parameter."
+ },
+ "token_endpoint_auth": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/RotateMcpOauthTokenEndpointAuthParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Client-secret updates for the existing token endpoint authentication method."
+ }
+ },
+ "additionalProperties": false,
+ "description": "Updates to an MCP credential's existing OAuth refresh configuration."
+ },
+ "RotateVaultCredentialAuthParamMcpOauth": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "mcp_oauth"
+ ],
+ "default": "mcp_oauth",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `mcp_oauth`."
+ },
+ "access_token": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "A write-only replacement OAuth access token."
+ },
+ "expires_at": {
+ "type": [
+ "string",
+ "null"
+ ],
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The replacement expiry as an RFC 3339 timestamp, or `null` to clear it. Omitting this field preserves the expiry unless a new access token is supplied, in which case the expiry is cleared."
+ },
+ "refresh": {
+ "anyOf": [
+ {
+ "$ref": "#/components/schemas/RotateMcpOauthRefreshParam"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional write-only refresh-token and client-secret updates."
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "additionalProperties": false,
+ "description": "Rotate an OAuth credential for an HTTPS MCP destination."
+ },
+ "RotateVaultCredentialAuthParamStaticBearer": {
+ "type": "object",
+ "properties": {
+ "type": {
+ "type": "string",
+ "enum": [
+ "static_bearer"
+ ],
+ "default": "static_bearer",
+ "x-stainless-const": true,
+ "description": "The type of the object. Always `static_bearer`."
+ },
+ "token": {
+ "type": "string",
+ "minLength": 0,
+ "maxLength": 1048576,
+ "description": "The replacement bearer token. This secret is never returned in credential resources."
+ }
+ },
+ "required": [
+ "type",
+ "token"
+ ],
+ "additionalProperties": false,
+ "description": "Replace the bearer token for the credential's MCP server."
+ },
+ "RotateVaultCredentialAuthParam": {
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/RotateVaultCredentialAuthParamMcpOauth"
+ },
+ {
+ "$ref": "#/components/schemas/RotateVaultCredentialAuthParamStaticBearer"
+ }
+ ],
+ "discriminator": {
+ "propertyName": "type",
+ "mapping": {
+ "mcp_oauth": "#/components/schemas/RotateVaultCredentialAuthParamMcpOauth",
+ "static_bearer": "#/components/schemas/RotateVaultCredentialAuthParamStaticBearer"
+ }
+ },
+ "x-oai-discriminator-values": [
+ "mcp_oauth",
+ "static_bearer"
+ ],
+ "description": "Updates to a vault credential without changing its authentication method or MCP server."
+ },
+ "RotateVaultCredentialParams": {
+ "type": "object",
+ "properties": {
+ "auth": {
+ "$ref": "#/components/schemas/RotateVaultCredentialAuthParam",
+ "description": "Replacement values for the credential's existing authentication method."
+ }
+ },
+ "required": [
+ "auth"
+ ],
+ "additionalProperties": false,
+ "description": "Secret, expiry, and OAuth refresh scope updates for an existing vault credential."
+ },
+ "DeletedVaultCredentialResource": {
+ "type": "object",
+ "properties": {
+ "id": {
+ "type": "string",
+ "minLength": 0,
+ "description": "The ID of the deleted credential."
+ },
+ "object": {
+ "type": "string",
+ "enum": [
+ "vault.credential.deleted"
+ ],
+ "default": "vault.credential.deleted",
+ "x-stainless-const": true,
+ "description": "The object type. Always `vault.credential.deleted`."
+ },
+ "deleted": {
+ "type": "boolean",
+ "description": "Whether the resource was deleted. Always `true`."
+ }
+ },
+ "required": [
+ "id",
+ "object",
+ "deleted"
+ ],
+ "additionalProperties": false,
+ "description": "Confirmation that a vault credential was deleted."
+ },
+ "v1.AgentsCore": {
+ "properties": {
+ "harness": {
+ "enum": [
+ "claude_sdk",
+ "codex",
+ "mcode"
+ ],
+ "type": "string"
+ },
+ "harness_config": {
+ "type": "object"
+ }
+ },
+ "type": "object"
+ },
+ "v1.EnvironmentInstallation": {
+ "properties": {
+ "commands": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ "expires_at": {
+ "type": "integer"
+ },
+ "message": {
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "available",
+ "unavailable"
+ ],
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "v1.ModelProviderInput": {
+ "properties": {
+ "api_key": {
+ "type": "string"
+ },
+ "base_url": {
+ "type": "string"
+ },
+ "context_window": {
+ "type": "integer"
+ },
+ "max_output_tokens": {
+ "type": "integer"
+ },
+ "protocol": {
+ "enum": [
+ "anthropic",
+ "responses",
+ "chat_completions"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "api_key",
+ "base_url",
+ "protocol"
+ ],
+ "type": "object"
+ },
+ "v1.ModelProviderView": {
+ "properties": {
+ "api_key_configured": {
+ "type": "boolean"
+ },
+ "base_url": {
+ "type": "string"
+ },
+ "context_window": {
+ "type": "integer"
+ },
+ "max_output_tokens": {
+ "type": "integer"
+ },
+ "protocol": {
+ "enum": [
+ "anthropic",
+ "responses",
+ "chat_completions"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "api_key_configured",
+ "base_url",
+ "protocol"
+ ],
+ "type": "object"
+ },
+ "v1.SavedAgentCore": {
+ "properties": {
+ "harness": {
+ "enum": [
+ "claude_sdk",
+ "codex",
+ "mcode"
+ ],
+ "type": "string"
+ },
+ "harness_config": {
+ "type": "object"
+ },
+ "model_provider": {
+ "$ref": "#/components/schemas/v1.ModelProviderView"
+ }
+ },
+ "type": "object"
+ },
+ "v1.SavedAgentCoreInput": {
+ "properties": {
+ "harness": {
+ "enum": [
+ "claude_sdk",
+ "codex",
+ "mcode"
+ ],
+ "type": "string"
+ },
+ "harness_config": {
+ "type": "object"
+ },
+ "model_provider": {
+ "anyOf": [
+ {
+ "allOf": [
+ {
+ "$ref": "#/components/schemas/v1.ModelProviderInput"
+ }
+ ]
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "v1.SessionCore": {
+ "properties": {
+ "installation": {
+ "$ref": "#/components/schemas/v1.EnvironmentInstallation"
+ }
+ },
+ "type": "object"
+ },
+ "v1.SessionExecutionInput": {
+ "properties": {
+ "environment": {
+ "description": "Environment supplies placement-independent preparation through the Core extension.",
+ "type": "object"
+ },
+ "harness_config": {
+ "type": "object"
+ },
+ "model_provider": {
+ "$ref": "#/components/schemas/v1.ModelProviderInput"
+ }
+ },
+ "type": "object"
+ }
+ },
+ "responses": {
+ "TooManyRequests": {
+ "description": "The request was rejected because a rate limit was exceeded.",
+ "headers": {
+ "Retry-After": {
+ "description": "The minimum number of seconds to wait before retrying. This header is returned when the server has computed a retry delay and may be omitted for 429 responses that require user action.",
+ "schema": {
+ "type": "integer",
+ "minimum": 1
+ }
+ }
+ },
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/ErrorResponse"
+ }
+ }
+ }
+ }
+ },
+ "securitySchemes": {
+ "ProjectKey": {
+ "type": "http",
+ "scheme": "bearer",
+ "description": "OpenAgentCore Project API key."
+ }
+ }
+ },
+ "x-oaiMeta": {
+ "navigationGroups": [
+ {
+ "id": "responses",
+ "title": "Responses API"
+ },
+ {
+ "id": "webhooks",
+ "title": "Webhooks"
+ },
+ {
+ "id": "endpoints",
+ "title": "Platform APIs"
+ },
+ {
+ "id": "vector_stores",
+ "title": "Vector stores"
+ },
+ {
+ "id": "chatkit",
+ "title": "ChatKit",
+ "beta": true
+ },
+ {
+ "id": "containers",
+ "title": "Containers"
+ },
+ {
+ "id": "live",
+ "title": "Live (alpha)"
+ },
+ {
+ "id": "realtime",
+ "title": "Realtime"
+ },
+ {
+ "id": "chat",
+ "title": "Chat Completions"
+ },
+ {
+ "id": "assistants",
+ "title": "Assistants",
+ "deprecated": true
+ },
+ {
+ "id": "administration",
+ "title": "Administration"
+ },
+ {
+ "id": "legacy",
+ "title": "Legacy"
+ }
+ ],
+ "groups": [
+ {
+ "id": "responses-streaming",
+ "title": "Streaming events",
+ "description": "When you [create a Response](https://developers.openai.com/api/reference/resources/responses/methods/create) with\n`stream` set to `true`, the server will emit server-sent events to the\nclient as the Response is generated. This section contains the events that\nare emitted by the server.\n\n[Learn more about streaming responses](https://developers.openai.com/api/docs/guides/streaming-responses).\n",
+ "navigationGroup": "responses",
+ "sections": [
+ {
+ "type": "object",
+ "key": "ResponseCreatedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseIncompleteEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputItemAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputItemDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseContentPartAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseContentPartDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseTextDeltaEvent",
+ "path": "response/output_text/delta"
+ },
+ {
+ "type": "object",
+ "key": "ResponseTextDoneEvent",
+ "path": "response/output_text/done"
+ },
+ {
+ "type": "object",
+ "key": "ResponseRefusalDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseRefusalDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFunctionCallArgumentsDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFunctionCallArgumentsDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallSearchingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallSearchingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryPartAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryPartDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryTextDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryTextDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningTextDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningTextDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallGeneratingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallPartialImageEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallArgumentsDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallArgumentsDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallInterpretingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCodeDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCodeDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputTextAnnotationAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseQueuedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCustomToolCallInputDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCustomToolCallInputDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseErrorEvent",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "responses-websocket-client-events",
+ "title": "Client events",
+ "description": "Events sent by the client over a Responses API WebSocket connection.\n",
+ "navigationGroup": "responses",
+ "sections": [
+ {
+ "type": "object",
+ "key": "ResponsesClientEventResponseCreate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseSteerEvent",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "responses-websocket-server-events",
+ "title": "Server events (WebSocket only)",
+ "description": "Events emitted only over a Responses API WebSocket connection.\n",
+ "navigationGroup": "responses",
+ "sections": [
+ {
+ "type": "object",
+ "key": "ResponseSteerAcceptedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseSteerPendingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseSteerFailedEvent",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "responses-websocket-shared-events",
+ "title": "Server events",
+ "description": "These events use the same payloads over WebSocket and\n[HTTP streaming](https://developers.openai.com/api/reference/resources/responses/streaming-events).\n",
+ "navigationGroup": "responses",
+ "sections": [
+ {
+ "type": "object",
+ "key": "ResponseCreatedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseIncompleteEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputItemAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputItemDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseContentPartAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseContentPartDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseTextDeltaEvent",
+ "path": "response/output_text/delta"
+ },
+ {
+ "type": "object",
+ "key": "ResponseTextDoneEvent",
+ "path": "response/output_text/done"
+ },
+ {
+ "type": "object",
+ "key": "ResponseRefusalDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseRefusalDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFunctionCallArgumentsDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFunctionCallArgumentsDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallSearchingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseFileSearchCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallSearchingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseWebSearchCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryPartAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryPartDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryTextDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningSummaryTextDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningTextDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseReasoningTextDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallGeneratingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseImageGenCallPartialImageEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallArgumentsDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallArgumentsDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsFailedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseMCPListToolsInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallInProgressEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallInterpretingEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCodeDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCodeInterpreterCallCodeDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseOutputTextAnnotationAddedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseQueuedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCustomToolCallInputDeltaEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseCustomToolCallInputDoneEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ResponseErrorEvent",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "safety-alerts",
+ "title": "Safety Alerts",
+ "description": "Retrieve approved safety alerts with an API key. Project keys require\n`api.safety.alerts.read` and can read alerts from their project.\n",
+ "navigationGroup": "endpoints",
+ "sections": [
+ {
+ "type": "endpoint",
+ "key": "Getprojectsafetyalert",
+ "path": "retrieve"
+ },
+ {
+ "type": "object",
+ "key": "SafetyAlertResource",
+ "path": "object"
+ }
+ ]
+ },
+ {
+ "id": "webhook-events",
+ "title": "Webhook Events",
+ "description": "Webhooks are HTTP requests sent by OpenAI to a URL you specify when certain\nevents happen during the course of API usage.\n\n[Learn more about webhooks](https://developers.openai.com/api/docs/guides/webhooks).\n",
+ "navigationGroup": "webhooks",
+ "sections": [
+ {
+ "type": "object",
+ "key": "WebhookResponseCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookResponseCancelled",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookResponseFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookResponseIncomplete",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookBatchCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookBatchCancelled",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookBatchExpired",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookBatchFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookFineTuningJobSucceeded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookFineTuningJobFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookFineTuningJobCancelled",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookEvalRunSucceeded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookEvalRunFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookEvalRunCanceled",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookRealtimeCallIncoming",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookLiveCallIncoming",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookLiveTransportIncoming",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookSafetyAlertCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "WebhookSafetyOrgAlertCreated",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "images-streaming",
+ "title": "Image Streaming",
+ "description": "Stream image generation and editing in real time with server-sent events.\n[Learn more about image streaming](https://developers.openai.com/api/docs/guides/image-generation).\n",
+ "navigationGroup": "endpoints",
+ "sections": [
+ {
+ "type": "object",
+ "key": "ImageGenPartialImageEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ImageGenCompletedEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ImageEditPartialImageEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "ImageEditCompletedEvent",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "realtime-client-events",
+ "title": "Client events",
+ "description": "These are events that the OpenAI Realtime WebSocket server will accept from the client.\n",
+ "navigationGroup": "realtime",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeClientEventSessionUpdate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventInputAudioBufferAppend",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventInputAudioBufferCommit",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventInputAudioBufferClear",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventConversationItemCreate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventConversationItemRetrieve",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventConversationItemTruncate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventConversationItemDelete",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventResponseCreate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventResponseCancel",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeClientEventOutputAudioBufferClear",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "realtime-server-events",
+ "title": "Server events",
+ "description": "These are events emitted from the OpenAI Realtime WebSocket server to the client.\n",
+ "navigationGroup": "realtime",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeServerEventError",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventSessionCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventSessionUpdated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemAdded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemRetrieved",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemInputAudioTranscriptionCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemInputAudioTranscriptionDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemInputAudioTranscriptionSegment",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemInputAudioTranscriptionFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemTruncated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventConversationItemDeleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferCommitted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferDtmfEventReceived",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferCleared",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferSpeechStarted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferSpeechStopped",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferTimeoutTriggered",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventOutputAudioBufferStarted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventOutputAudioBufferStopped",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventOutputAudioBufferCleared",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseOutputItemAdded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseOutputItemDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseContentPartAdded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseContentPartDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseTextDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseTextDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseAudioTranscriptDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseAudioTranscriptDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseAudioDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseAudioDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseFunctionCallArgumentsDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseFunctionCallArgumentsDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseMCPCallArgumentsDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseMCPCallArgumentsDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseMCPCallInProgress",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseMCPCallCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventResponseMCPCallFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventMCPListToolsInProgress",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventMCPListToolsCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventMCPListToolsFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventRateLimitsUpdated",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "realtime-translation-client-events",
+ "title": "Translation client events",
+ "description": "These are events that the OpenAI Realtime Translation WebSocket server will accept from the client.\n",
+ "navigationGroup": "realtime",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeTranslationClientEventSessionUpdate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationClientEventInputAudioBufferAppend",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationClientEventSessionClose",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "realtime-translation-server-events",
+ "title": "Translation server events",
+ "description": "These are events emitted from the OpenAI Realtime Translation WebSocket server to the client.\n",
+ "navigationGroup": "realtime",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeServerEventError",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionUpdated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionClosed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionInputTranscriptDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionOutputTranscriptDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeTranslationServerEventSessionOutputAudioDelta",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "chat-streaming",
+ "title": "Streaming",
+ "description": "Stream Chat Completions in real time. Receive chunks of completions\nreturned from the model using server-sent events.\n[Learn more](https://developers.openai.com/api/docs/guides/streaming-responses).\n",
+ "navigationGroup": "chat",
+ "sections": [
+ {
+ "type": "object",
+ "key": "CreateChatCompletionStreamResponse",
+ "path": "streaming"
+ }
+ ]
+ },
+ {
+ "id": "assistants-streaming",
+ "title": "Streaming",
+ "beta": true,
+ "description": "Stream the result of executing a Run or resuming a Run after submitting tool outputs.\nYou can stream events from the [Create Thread and Run](https://developers.openai.com/api/docs/assistants/migration),\n[Create Run](https://developers.openai.com/api/docs/assistants/migration), and [Submit Tool Outputs](https://developers.openai.com/api/docs/assistants/migration)\nendpoints by passing `\"stream\": true`. The response will be a [Server-Sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events) stream.\nOur Node and Python SDKs provide helpful utilities to make streaming easy. Reference the\n[Assistants API quickstart](https://developers.openai.com/api/docs/assistants/migration) to learn more.\n",
+ "navigationGroup": "assistants",
+ "sections": [
+ {
+ "type": "object",
+ "key": "AssistantStreamEvent",
+ "path": "events"
+ }
+ ]
+ },
+ {
+ "id": "realtime-beta-client-events",
+ "title": "Realtime Beta client events",
+ "description": "These are events that the OpenAI Realtime WebSocket server will accept from the client.\n",
+ "navigationGroup": "legacy",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventSessionUpdate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventInputAudioBufferAppend",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventInputAudioBufferCommit",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventInputAudioBufferClear",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventConversationItemCreate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventConversationItemRetrieve",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventConversationItemTruncate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventConversationItemDelete",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventResponseCreate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventResponseCancel",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventTranscriptionSessionUpdate",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaClientEventOutputAudioBufferClear",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "realtime-beta-server-events",
+ "title": "Realtime Beta server events",
+ "description": "These are events emitted from the OpenAI Realtime WebSocket server to the client.\n",
+ "navigationGroup": "legacy",
+ "sections": [
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventError",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventSessionCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventSessionUpdated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventTranscriptionSessionCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventTranscriptionSessionUpdated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemRetrieved",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionSegment",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemInputAudioTranscriptionFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemTruncated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventConversationItemDeleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventInputAudioBufferCommitted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventInputAudioBufferCleared",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventInputAudioBufferSpeechStarted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventInputAudioBufferSpeechStopped",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeServerEventInputAudioBufferTimeoutTriggered",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseCreated",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseOutputItemAdded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseOutputItemDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseContentPartAdded",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseContentPartDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseTextDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseTextDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseAudioTranscriptDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseAudioTranscriptDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseAudioDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseAudioDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseFunctionCallArgumentsDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseFunctionCallArgumentsDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseMCPCallArgumentsDelta",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseMCPCallArgumentsDone",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseMCPCallInProgress",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseMCPCallCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventResponseMCPCallFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventMCPListToolsInProgress",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventMCPListToolsCompleted",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventMCPListToolsFailed",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "RealtimeBetaServerEventRateLimitsUpdated",
+ "path": ""
+ }
+ ]
+ },
+ {
+ "id": "live-client-events",
+ "title": "Client events",
+ "description": "Initialize a primary WebSocket with session.start and wait for session.started before sending other events. WebRTC creation starts the session for you. Start with the [Live prompting guide](https://developers.openai.com/api/docs/guides/live-prompting) to design frontend instructions and delegation policy; see [backend prompting](https://developers.openai.com/api/docs/guides/live-delegation#start-with-your-existing-backend-prompt) for tools and business rules.",
+ "navigationGroup": "live",
+ "sections": [
+ {
+ "type": "object",
+ "key": "LiveSessionStartEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveForkSessionStartEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveSessionUpdateParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveInputAudioAppendEvent",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveInputAudioMuteParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveInputAudioUnmuteParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveInstructionsAppendParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveThinkingAppendParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveCommentaryAppendParam",
+ "path": ""
+ },
+ {
+ "type": "object",
+ "key": "LiveResponseItemCreateParam",
+ "path": "