diff --git a/.claude/skills/seclai-sdk-sync/SKILL.md b/.claude/skills/seclai-sdk-sync/SKILL.md index bfdad17..16818d9 100644 --- a/.claude/skills/seclai-sdk-sync/SKILL.md +++ b/.claude/skills/seclai-sdk-sync/SKILL.md @@ -100,6 +100,15 @@ for those two SDKs will not drop as typing improves. Check the façade before concluding an endpoint is untyped. seclai-javascript needs no façade (`unknown` to a concrete type is source compatible) and does report zero. +**`params` and `returns` follow one hop into a non-public helper, and no further.** +A public method with no request of its own that calls a non-public method of the +same client holding the verb and path literal (Go `c.thingsBody(`, C# `internal +…ResponseAsync`, Python `self._x(`, JS `private`/`#x`) is audited as that request, +with its own declared return type; both summaries then print how many methods +were resolved that way, so a drop in that number is a narrower audit, not a +cleaner SDK. A second hop, a helper that takes its verb or path as an argument, +and a call from another class (the façade's `_client.X(`) are still not followed. + **Dated versioning breaks the one-shape assumption.** Since `Seclai-Version` (2026-07-28) an operation can have two legal response bodies — a bare array by default, the canonical `{data, pagination}` envelope once the caller opts in — diff --git a/.claude/skills/seclai-sdk-sync/sdksync.py b/.claude/skills/seclai-sdk-sync/sdksync.py index 7d3b7ca..6a9d205 100755 --- a/.claude/skills/seclai-sdk-sync/sdksync.py +++ b/.claude/skills/seclai-sdk-sync/sdksync.py @@ -47,6 +47,11 @@ # "this method sends no params" — a silent false pass. # helpers — positional helper calls that expand to a fixed, ordered key list. # Expansion is arity-aware: only as many keys as arguments supplied. +# Endpoint helpers, used by `params` and `returns` (see `request_blocks`): +# helper_re — a NON-public method declaration on the client, name captured. +# helper_call — how the client calls one of its own methods; `{name}` is filled +# in. Receiver-qualified so `_client.X(` and `t.c.x(` — a typed +# façade calling in from another class — are not followed. LANGS = { "python": { "sig_re": r"\n (?:async )?def ([a-z]\w*)\(([^)]*)\)\s*->\s*([^:]+):", @@ -62,6 +67,8 @@ "return_re": r"\s*->\s*([^:\n]+):", "dict_at": [r"params\s*=\s*(?:_strip_none\()?\s*"], "dict_key_re": r'"([a-zA-Z_][a-zA-Z0-9_]*)"\s*:', + "helper_re": r"^[ \t]+(?:async )?def (_[a-z0-9][a-z0-9_]*)\(", + "helper_call": r"\bself\.{name}\(", "skip": {"request", "request_raw", "stream", "paginate"}, }, "javascript": { @@ -82,6 +89,11 @@ "return_re": r"\s*:\s*([^{\n]+?)\s*\{", "dict_at": [r"query:\s*"], "dict_key_re": r'["\']?([a-zA-Z_][a-zA-Z0-9_]*)["\']?\s*:', + # `private`/`protected`/`#name` members only. An unmodified `_name(` is + # matched by method_re and already audited as a block of its own. + "helper_re": (r"^ (?:(?:private|protected) (?:static )?(?:async )?\*?|(?:async )?\*?#)" + r"([a-zA-Z_][a-zA-Z0-9_]*)\s*[(<]"), + "helper_call": r"\bthis\.#?{name}\s*[(<]", "skip": {"request", "requestRaw", "uploadFile", "paginate"}, }, "go": { @@ -105,6 +117,10 @@ "dict_at": [r"map\[string\]string"], "dict_key_re": r'"([a-zA-Z_][a-zA-Z0-9_]*)"\s*:', "helpers": {"listQuery(": ["page", "limit"]}, + "helper_re": r"^func \(c \*Client\) ([a-z][A-Za-z0-9]*)\(", + "helper_call": r"(?,?\[\]. ]+ ([A-Z][A-Za-z0-9]*)\s*\("), + "helper_call": r"(? tuple[str, str] | None: return v.group(1).upper(), path +def strip_docs(text: str) -> str: + """Drop docstrings, block comments and whole-line comments. + + Helper detection reads through this: a docstring's `"GET"` and `"/sources"` + example made seclai-python's `_raise_for_openapi_response` look like the + request behind twenty methods that never issue one. + """ + text = re.sub(r'"""[\s\S]*?"""|\'\'\'[\s\S]*?\'\'\'|/\*[\s\S]*?\*/', "", text) + return re.sub(r"(?m)^[ \t]*(?://|#).*$", "", text) + + +def endpoint_helpers(text: str, cfg: dict) -> dict[str, str]: + """Non-public client method name -> body, for those that DEFINE a request. + + Defining one means holding a verb and a path literal. Transport plumbing + (`doBytes`, `SendRawResponseAsync`) takes both as arguments and holds neither, + which is what keeps it out of this index. + """ + if "helper_re" not in cfg: + return {} + ends = sorted({m.start() + for pat in (cfg["helper_re"], cfg["method_re"], cfg.get("boundary_re")) if pat + for m in re.finditer(pat, text, re.M)}) + out: dict[str, str] = {} + for m in re.finditer(cfg["helper_re"], text, re.M): + name = m.group(1) + if name in cfg.get("skip", ()) or name in out: + continue + end = next((e for e in ends if e > m.start()), len(text)) + body = strip_docs(text[m.start():end]) + if block_call(body, cfg["verb_re"]): + out[name] = body + return out + + +def helper_called(body: str, cfg: dict, helpers: dict[str, str]) -> str | None: + """Name of the first endpoint helper a method body calls, if any.""" + code = strip_docs(body) # a comment naming a helper is not a call to it + first: tuple[int, str] | None = None + for name in helpers: + m = re.search(cfg["helper_call"].replace("{name}", re.escape(name)), code) + if m and (first is None or m.start() < first[0]): + first = (m.start(), name) + return first[1] if first else None + + +def request_blocks(texts: list[str], cfg: dict): + """Yield (name, body, call, request_body, helper) per public method with a request. + + A method with no request call of its own that calls a non-public method + defining one is read through that helper — ONE hop. `body` stays the public + method's, so its declared return type is what `returns` compares; + `request_body` is where query keys are read. `helper` is None for own requests. + """ + shared: dict[str, str] = {} + if cfg.get("helper_scope") == "package": + for text in texts: + for k, v in endpoint_helpers(text, cfg).items(): + shared.setdefault(k, v) + for text in texts: + helpers = shared or endpoint_helpers(text, cfg) + for mname, body in method_blocks(text, cfg["method_re"], cfg.get("boundary_re")): + if mname in cfg.get("skip", ()): + continue + call = block_call(body, cfg["verb_re"]) + if call: + yield mname, body, call, body, None + continue + helper = helper_called(body, cfg, helpers) + if helper: + hbody = helpers[helper] + yield mname, body, block_call(hbody, cfg["verb_re"]), body + "\n" + hbody, helper + + +def via_helper_line(n: int) -> str: + return (f" {n} of the methods read were resolved through a non-public helper" + f" holding the request (one hop)") + + def block_query_keys(body: str, cfg: dict) -> tuple[set[str], bool]: """(keys, parsed_ok). parsed_ok is False when a construction site was found but could not be read — reported as an error, never as "sends nothing".""" @@ -367,32 +465,30 @@ def cmd_params(args) -> int: undeclared, not_in_spec, unparsed, exposed = set(), set(), set(), {} missing_required: set[tuple[str, str, str]] = set() - for f in files: - text = f.read_text(errors="replace") - for mname, body in method_blocks(text, cfg["method_re"], cfg.get("boundary_re")): - if mname in cfg.get("skip", ()): - continue - call = block_call(body, cfg["verb_re"]) - if not call: - continue - keys, ok = block_query_keys(body, cfg) - if not ok: - unparsed.add((mname, f"{call[0]} {call[1]}")) - if call not in index: - not_in_spec.add((mname, f"{call[0]} {call[1]}")) - continue - raw, declared, required = index[call] - exposed.setdefault((call[0], raw), set()).update(keys) - if ok: - # Only trust this when the query construction parsed: an - # unreadable site would otherwise look like "sends nothing". - for k in sorted(required - keys): - missing_required.add((mname, f"{call[0]} {raw}", k)) - for k in sorted(keys - declared): - undeclared.add((mname, f"{call[0]} {raw}", k, tuple(sorted(declared)))) + via_helper = 0 + texts = [f.read_text(errors="replace") for f in files] + for mname, _body, call, request_body, helper in request_blocks(texts, cfg): + via_helper += helper is not None + keys, ok = block_query_keys(request_body, cfg) + if not ok: + unparsed.add((mname, f"{call[0]} {call[1]}")) + if call not in index: + not_in_spec.add((mname, f"{call[0]} {call[1]}")) + continue + raw, declared, required = index[call] + exposed.setdefault((call[0], raw), set()).update(keys) + if ok: + # Only trust this when the query construction parsed: an + # unreadable site would otherwise look like "sends nothing". + for k in sorted(required - keys): + missing_required.add((mname, f"{call[0]} {raw}", k)) + for k in sorted(keys - declared): + undeclared.add((mname, f"{call[0]} {raw}", k, tuple(sorted(declared)))) print(f"{name} [{lang}] — {len(files)} client file(s), " f"{len(index)} spec operations") + if via_helper: + print(via_helper_line(via_helper)) if undeclared: print(f"\nUNDECLARED ({len(undeclared)}) — sent but the endpoint does not accept it:") @@ -845,47 +941,46 @@ def cmd_returns(args) -> int: _schema_label(_json_schema(op, "response", code))) break - mismatched, renamed, untyped, n = [], [], [], 0 - for path in files: - text = path.read_text(encoding="utf-8", errors="replace") - for mname, body in method_blocks(text, cfg["method_re"], cfg.get("boundary_re")): - if mname in cfg.get("skip", set()): - continue - call = block_call(body, cfg["verb_re"]) - if not call or call not in want: - continue - declared = block_return(body, cfg) - if declared is None: - continue - n += 1 - got, expect = normalise_type(declared, lang), want[call] - if expect in ("object", "none", "unknown", "?"): - continue # the spec itself declares nothing to match - if got == expect or strip_generated_prefix(got) == expect: - continue - # Separate the two failure modes. A list where the API returns an - # envelope throws at deserialization; a type NAMED differently from - # its schema is only cosmetic, and the SDKs rename by convention — - # all four drop the spec's `Model` and `Api` affixes. Ranking those - # equally buried the one real finding under eleven harmless ones. - # A wholly untyped return (`JsonElement`, `unknown`, `JSONValue`) - # commits to no shape at all and deserializes anything, so it is a - # coverage warning, never a shape error. - if got == "?": - untyped.append((mname, call, expect, declared)) - # Shape next. `list[dict[str, Any]]` IS a commitment to a list and is - # also untyped; testing untyped-ness first classified seclai-python's - # list_evaluation_criteria as a soft warning and reported the repo - # clean, when it is exactly as broken as the Go and JS ones. - elif got.startswith("array<") != expect.startswith("array<"): - mismatched.append((mname, call, expect, declared)) - elif "?" in got: - untyped.append((mname, call, expect, declared)) - else: - renamed.append((mname, call, expect, declared)) + mismatched, renamed, untyped, n, via_helper = [], [], [], 0, 0 + texts = [path.read_text(encoding="utf-8", errors="replace") for path in files] + for mname, body, call, _request_body, helper in request_blocks(texts, cfg): + if call not in want: + continue + declared = block_return(body, cfg) + if declared is None: + continue + n += 1 + via_helper += helper is not None + got, expect = normalise_type(declared, lang), want[call] + if expect in ("object", "none", "unknown", "?"): + continue # the spec itself declares nothing to match + if got == expect or strip_generated_prefix(got) == expect: + continue + # Separate the two failure modes. A list where the API returns an + # envelope throws at deserialization; a type NAMED differently from + # its schema is only cosmetic, and the SDKs rename by convention — + # all four drop the spec's `Model` and `Api` affixes. Ranking those + # equally buried the one real finding under eleven harmless ones. + # A wholly untyped return (`JsonElement`, `unknown`, `JSONValue`) + # commits to no shape at all and deserializes anything, so it is a + # coverage warning, never a shape error. + if got == "?": + untyped.append((mname, call, expect, declared)) + # Shape next. `list[dict[str, Any]]` IS a commitment to a list and is + # also untyped; testing untyped-ness first classified seclai-python's + # list_evaluation_criteria as a soft warning and reported the repo + # clean, when it is exactly as broken as the Go and JS ones. + elif got.startswith("array<") != expect.startswith("array<"): + mismatched.append((mname, call, expect, declared)) + elif "?" in got: + untyped.append((mname, call, expect, declared)) + else: + renamed.append((mname, call, expect, declared)) print(f"{repo.name} [{lang}] — {n} method(s) with both a declared return type " f"and a named response schema") + if via_helper: + print(via_helper_line(via_helper)) if mismatched: print(f"\nSHAPE MISMATCH ({len(mismatched)}) — list vs object; this fails at deserialization:") diff --git a/CHANGELOG.md b/CHANGELOG.md index bf553ab..8358b0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## [1.7.0] - 2026-10-21 + +### Changed + +- **Breaking:** Type `score` and `passed` on `TestDraftEvaluationResponse` as `number | null` and `boolean | null` when `status` is `error`. From `apiVersion` `2026-10-21`, which an account created after it ships gets even without setting `apiVersion`, an evaluator that returns no verdict sends them as `null`. Under `strictNullChecks`, code that reads them without first checking `status` no longer compiles: check `result.status !== "error"` before reading them, after which they are `number` and `boolean` again. See [Upgrading to 1.7](https://github.com/seclai/seclai-javascript#upgrading-to-17) +- Sync the bundled OpenAPI spec and regenerate the types. Existing responses gain properties: `email_address`, `email_allowed_senders`, `feed_attachments`, `document_images` and the `cloud_drive_*` settings on `SourceResponse`, `trigger_id` on `AgentSummaryResponse`, `accepted_attachments` on `AgentAttachmentRefsApiResponse`, `email_run_on_attachment_mismatch` on `EmailTriggerConfigResponse`, `held_for_review` on `SourceContentStatusResponse`, `skipped_attachments` on `ContentDetailResponse`, `error` on `NonManualEvaluationSummaryResponse` and `NonManualEvaluationModeStatResponse`, and `status` on `TestDraftEvaluationResponse` +- Move `SeclaiApiVersion.Latest` to `2026-10-21`. Nothing is sent unless `apiVersion` is set, so a client that passes `SeclaiApiVersion.Latest` now opts into the six versions added below: `2026-10-05` reports an item held for review by a governance policy as `content_status` `completed` instead of `failed`, so code that looks for holds among failed items must read `held_for_review`; `2026-10-13` rejects a `media_types` value other than `images` or `video`, or any value on a source that is not a website or RSS feed, on `createSource()` and `updateSource()` with a 400 where it was dropped; `2026-10-16` accepts an upload of any type as `ready` at once and stops writing its extracted text into a run's `input`; `2026-10-18` defaults a source's `document_images` to `true` on a text-only embedder; `2026-10-19` rejects `polling_max_items` on `createSource()` for any source but an RSS feed with a 400 where it was stored; and `2026-10-21` leaves an evaluation result whose evaluator returned no verdict (`error`) out of `failed` and the rates in `getNonManualEvaluationSummary()` and out of `average_score` in `getEvaluationCriteriaSummary()`, and returns its `score` and `passed` from `testDraftEvaluation()` as `null` instead of 0.5 and `false` + +### Added + +- Add `setAcceptedAttachments()` to declare the named input attachments a trigger accepts, and `accepted_attachments` on `createAgent()` and `updateAgentDefinition()`. A slot's server-defaulted `min` can be omitted: the slots are typed `AcceptedAttachmentSlotInput`, and the request `SetAcceptedAttachmentsInput` +- Add `listContentAttachments()`, `getContentAttachment()`, `listContentAttachmentEmbeddings()` and `downloadContentAttachment()` for the files attached to a content item, with their indexing status, text and embeddings. `downloadContentAttachment()` takes a `signal` +- Add `listEmailSourceRejections()` for the mail an email source refused +- Add `include_reasoning` to the `runStreamingAgent()` request, to receive `stream_reasoning` events. It stays optional although the schema gives it a default. `runStreamingAgentAndWait()`, which returns no such events, does not take it and does not send one passed anyway +- Accept the new source settings on `createSource()` and `updateSource()`: `email_allowed_senders`, `feed_attachments`, `document_images` and `cloud_drive_connection_id`, `cloud_drive_folder_path`, `cloud_drive_path_pattern`, `cloud_drive_content_types` and `cloud_drive_max_file_mb`, and `run_on_attachment_mismatch` on `setEmailTriggerConfig()` +- Add the `SeclaiApiVersion` constants `V2026_10_05`, `V2026_10_13`, `V2026_10_16`, `V2026_10_18`, `V2026_10_19` and `V2026_10_21`, so those versions are accepted as `apiVersion`. The README lists what each one changes +- Accept a `signal` on `downloadSourceExport()` and `downloadAgentRunAttachment()` +- Add the type exports `AcceptedAttachmentSlot`, `AcceptedAttachmentSlotInput`, `AcceptedAttachmentsResponse`, `SetAcceptedAttachmentsRequest`, `SetAcceptedAttachmentsInput`, `ContentAttachmentResponse`, `ContentAttachmentsListResponse`, `ContentAttachmentDetailResponse`, `SkippedAttachmentResponse`, `SkippedAttachmentReason`, `EmailSourceRejectionResponse` and `EmailSourceRejectionListResponse` + +### Fixed + +- Correct `InsufficientCreditsResponse` and `InsufficientCreditsDetail` to the 402 body the API sends: the detail is under `error`, not `detail`, and its machine-readable code is `code`, not `error`. Code that cast a 402 body to this type and read `body.detail.error` threw on every real 402; read `body.error.code` instead + ## [1.6.1] - 2026-10-05 ### Changed @@ -223,6 +246,7 @@ _Stable release. No functional changes since 0.0.1._ _Initial release._ +[1.7.0]: https://github.com/seclai/seclai-javascript/releases/tag/1.7.0 [1.6.1]: https://github.com/seclai/seclai-javascript/releases/tag/1.6.1 [1.6.0]: https://github.com/seclai/seclai-javascript/releases/tag/1.6.0 [1.5.0]: https://github.com/seclai/seclai-javascript/releases/tag/1.5.0 diff --git a/README.md b/README.md index 9add5a4..183a515 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ Leave `apiVersion` unset and the header is omitted, so the account's pinned baseline applies and responses keep their current shapes. Upgrading this package alone never changes the wire contract. -Known versions are on `SeclaiApiVersion` (`V2026_07_01` through `V2026_10_03`, +Known versions are on `SeclaiApiVersion` (`V2026_07_01` through `V2026_10_21`, plus `Default` and `Latest`), imported from `@seclai/sdk`. A version this release was **not** built against throws at construction: a newer version can reshape responses, and this client would decode them incorrectly rather than reject them. @@ -173,9 +173,21 @@ default, so the same call can return fewer rows: - `setAutoBlockMode()` reports the account's full `total` by default, and the number of rows it returned after you opt in. -**Later versions.** Each is cumulative. None changes a response shape this -client decodes, but `2026-09-30` changes what a string you may be parsing -contains: +**Later versions.** Each is cumulative. Some change a value you may be reading, +a request that used to succeed, or (from `2026-10-21`) which fields can be +`null`: + +- `2026-09-30` and `2026-10-16` change what a string you may be parsing + contains — a run's `output`, and a run's `input` when it has uploads. +- `2026-10-05` changes a value you may branch on: an item held for review + reports `content_status` `completed` instead of `failed`, so code that looks + for governance holds among `failed` items stops finding them. Check + `held_for_review` instead. +- `2026-10-13` and `2026-10-19` reject with a 400 source settings that were + accepted before. +- `2026-10-21` changes evaluation numbers you may be reading: an `error` result + no longer counts as `failed` or toward the rates, and `testDraftEvaluation()` + returns `null` `score` and `passed` for one. | Version | What it changes | | --- | --- | @@ -184,12 +196,50 @@ contains: | `2026-09-28` | Agent-definition writes use the current file-list grammar: an omitted `attachments` keeps the stored list and `[]` means no files | | `2026-09-30` | **Breaks code that parses `output`.** A run's and a step's `output`, and a step's `input`, are the plain text; below this version an output that has files is a JSON manifest string (`{schema, text, attachments}`). Read files from `attachments`, which is populated on every version | | `2026-10-03` | A new LLM step written without `attachments` takes its parent's files, and a new retrieval step's matched media are its files | +| `2026-10-05` | An item held for review by an Enforce governance policy reports `content_status` `completed` (with `held_for_review: true`) from `listSourceContents()` and `getSourceContentStatus()`. Below it the item reports `failed` with the hold as the `error` | +| `2026-10-13` | `createSource()` and `updateSource()` reject a `media_types` value other than `images` or `video`, or any value on a source that is not a website or RSS feed, with a 400. Below it an unknown value is dropped | +| `2026-10-16` | `uploadAgentInput()` accepts a file of any type and it is `ready` at once. Each step receives the file itself when its model reads that type, and its text otherwise; a run's `input` carries only a `# filename` heading per file. Below it only a fixed list of extensions is accepted and each file's extracted text is written into `input`, so poll `getAgentInputUploadStatus()` before running | +| `2026-10-18` | A source's `document_images` defaults to `true` on every embedder. Below it it defaults to `false` on a text-only embedder | +| `2026-10-19` | `createSource()` rejects `polling_max_items` on any source type but an RSS feed with a 400. Below it the value is stored | +| `2026-10-21` | An evaluation result whose evaluator returned no verdict (`error`) is left out of `failed` and of `pass_rate` / `failure_rate` in `getNonManualEvaluationSummary()`, and `getEvaluationCriteriaSummary()` averages `average_score` over passed and failed results only. `testDraftEvaluation()` returns `score` and `passed` as `null` for an `error` result. Below it the summary counts `error` results in `failed` and the rates, `average_score` includes their stored scores, and the test draft returns `score` 0.5 and `passed: false`. The summary's `error` count is returned on every version | **`Latest` moves with the SDK.** `SeclaiApiVersion.Latest` is the newest version the installed release knows, so upgrading the package can opt a client that passes it into every version added since — `1.6.0` moved it from `2026-07-27` to -`2026-10-03`, across the `2026-09-30` output change. Pass a dated constant such -as `SeclaiApiVersion.V2026_07_27` to keep behaviour fixed across upgrades. +`2026-10-03`, across the `2026-09-30` output change, and `1.7.0` moves it to +`2026-10-21`, across the `2026-10-05` status change, the `2026-10-13` and +`2026-10-19` source-setting rejections, the `2026-10-16` input change and the +`2026-10-21` evaluation change. Pass a +dated constant such as `SeclaiApiVersion.V2026_07_27` to keep behaviour fixed +across upgrades. + +## Upgrading to 1.7 + +Two type changes can stop existing code compiling. If you pass +`SeclaiApiVersion.Latest`, it now sends `2026-10-21`; the table above lists +what each version changes. + +**`testDraftEvaluation()` can return `null` scores.** When the evaluator +returns no verdict, `status` is `error`. From API version `2026-10-21`, `score` +and `passed` are then `null`. An account created after `2026-10-21` ships gets +that version even without setting `apiVersion`. Check `status` before reading +them, in JavaScript too; under `strictNullChecks` the type enforces it: + + +```ts +const result = await client.testDraftEvaluation("agent_id", { step_output: "...", pass_threshold: 0.7 }); + +// 1.6 and earlier: console.log(result.score.toFixed(2), result.passed); +if (result.status === "error") { + console.log("No verdict:", result.explanation); +} else { + console.log(result.score.toFixed(2), result.passed); // number and boolean here +} +``` + +**`InsufficientCreditsResponse` matches the 402 body.** Read the code at +`error.code`, not `detail.error`. Code that cast a 402 body to this type threw +on every real 402 before, so this only fixes it. ## Resources @@ -294,6 +344,21 @@ for await (const event of client.runStreamingAgent( } ``` +Pass `include_reasoning: true` to also receive `stream_reasoning` events carrying +the model's reasoning while it thinks. They are sent only for a +`streaming_result` step whose author enabled `show_reasoning`, and reasoning is +never part of `output`: + + +```ts +for await (const event of client.runStreamingAgent("agent_id", { + input: "Hello", + include_reasoning: true, +})) { + if (event.event === "stream_reasoning") console.log(event.data); +} +``` + ### Polling For environments where SSE is not practical, poll for a completed run: @@ -308,6 +373,7 @@ const result = await client.runAgentAndPoll( ### Agent input uploads + ```ts // Discover which files (if any) the agent expects before staging uploads const refs = await client.getAgentAttachmentReferences("agent_id"); @@ -316,14 +382,26 @@ if (refs.requires_uploads) { } const upload = await client.uploadAgentInput("agent_id", { - file: new Uint8Array([...]), + file: new Uint8Array([/* file bytes */]), fileName: "input.pdf", }); -const status = await client.getAgentInputUploadStatus("agent_id", upload.upload_id); +// From API version 2026-10-16 the upload is `ready` at once. Below it, poll +// until `status` is `ready` before running. +let status = await client.getAgentInputUploadStatus("agent_id", upload.id); +while (status.status !== "ready") { + if (status.status === "failed") throw new Error(`Upload failed: ${status.error}`); + await new Promise((resolve) => setTimeout(resolve, 1_000)); + status = await client.getAgentInputUploadStatus("agent_id", upload.id); +} +const run = await client.runAgent("agent_id", { input_upload_id: upload.id, priority: false }); ``` +Only a `dynamic_input` agent takes uploads; any other agent rejects one with a +400. + ### Agent run attachments + ```ts // Download a file emitted by a step in an agent run. The attachment_id is the // URL-safe-base64 storage_key surfaced in run output manifests / webhooks. @@ -347,6 +425,31 @@ const config = await client.setEmailTriggerConfig("agent_id", "trigger_id", { console.log(config.email_addresses); // ["support.@agent.seclai.com", ...] ``` +Set `run_on_attachment_mismatch: true` to run an email whose attachments do not +fit what the agent accepts: files it cannot take are left out and the problems +are listed in the run's `email_attachment_issues` metadata. By default the run fails. + +### Accepted attachments + +Declare the input attachments a trigger accepts. A run's files are each assigned +to one named slot before any step runs, and steps reference a slot as +`{{agent.attachments.}}`. The call replaces the whole declaration, and is +refused with a 400 when the agent references a slot it leaves out. `min` defaults +to 0. The same slots can be set as `accepted_attachments` on `createAgent()` and +`updateAgentDefinition()`. + + +```ts +const agent = await client.getAgent("agent_id"); +const { accepted_attachments } = await client.setAcceptedAttachments("agent_id", agent.trigger_id!, { + accepted_attachments: [ + { name: "invoice", content_types: ["application/pdf"], min: 1, max: 1 }, + { name: "photos", content_types: ["image/*"], label: "Photos of the damage" }, + ], +}); +console.log(accepted_attachments.map((slot) => `${slot.name}: ${slot.min}..${slot.max ?? "any"}`)); +``` + ### Agent email governance ```ts @@ -394,8 +497,10 @@ const detail = await client.getEvaluationCriteria("criteria_id"); await client.updateEvaluationCriteria("criteria_id", { ... }); await client.deleteEvaluationCriteria("criteria_id"); -// Test a draft -await client.testDraftEvaluation("agent_id", { criteria: { ... }, run_id: "..." }); +// Test a draft. Check status first: an "error" result has no verdict, and its +// score and passed can be null. +const draft = await client.testDraftEvaluation("agent_id", { step_output: "...", pass_threshold: 0.7 }); +if (draft.status !== "error") console.log(draft.score, draft.passed); // Results by criteria const results = await client.listEvaluationResults("criteria_id"); @@ -474,9 +579,40 @@ const batch = await client.listSourceContents("source_id", { console.log(batch.pagination.total, failed.data.map((item) => item.error)); const one = await client.getSourceContentStatus("source_id", "cv_1"); -console.log(one.content_status); +console.log(one.content_status, one.held_for_review); ``` +An item an Enforce governance policy blocked at import is held for review: +`held_for_review` is `true` until a reviewer releases it. Its `content_status` is +`completed` from API version `2026-10-05`, and `failed` with the hold as the +`error` below it. + +An email source stores mail from `email_allowed_senders` only, and lists what it +refused. Each entry names the sender and the reason, never the subject or body; +adding a refused sender to `email_allowed_senders` helps only when `authenticated` +is `true`. Listing rejections requires an account owner or administrator. + + +```ts +const inbox = await client.createSource({ + name: "Newsletters", + source_type: "email", + email_allowed_senders: ["news@example.com", "example.org"], +}); +console.log(inbox.email_address); // send mail here + +const rejections = await client.listEmailSourceRejections(inbox.id, { page: 1, limit: 50 }); +for (const r of rejections.data) console.log(r.from_address, r.reason, r.authenticated); + +// Index the images inside documents, and an RSS feed's enclosures +await client.updateSource("source_id", { document_images: true, feed_attachments: ["enclosures"] }); +``` + +A `cloud_drive` source takes `cloud_drive_connection_id` (from `listCloudDrives()`) +on create, and `cloud_drive_folder_path`, `cloud_drive_path_pattern`, +`cloud_drive_content_types` and `cloud_drive_max_file_mb` to choose which files +it indexes. + ### Cloud drives @@ -567,6 +703,28 @@ await client.uploadFileToContent("content_id", { }); ``` +A content item's attachments are the files an agent step, an email, a feed, a +web page's media or a document's images added to it. Each says whether it is +indexed for search and, if indexing failed, why. An email item's +`skipped_attachments` (on `getContentDetail()`) lists the parts that were not +stored, with the reason. + + +```ts +const attachments = await client.listContentAttachments("content_id", { limit: 50 }); +for (const att of attachments.data) { + console.log(att.id, att.content_type, att.indexed, att.indexing_error); +} + +const att = await client.getContentAttachment("content_id", "attachment_id", { start: 0, end: 2000 }); +console.log(att.text_content, att.file_withheld); +const vectors = await client.listContentAttachmentEmbeddings("content_id", "attachment_id"); + +// Raw Response; 403 while the file is withheld (see `file_withheld`). +const file = await client.downloadContentAttachment("content_id", "attachment_id"); +const bytes = new Uint8Array(await file.arrayBuffer()); +``` + ### Solutions ```ts diff --git a/openapi/seclai.openapi.json b/openapi/seclai.openapi.json index 058d09e..0ca4052 100644 --- a/openapi/seclai.openapi.json +++ b/openapi/seclai.openapi.json @@ -23,6 +23,99 @@ } }, "schemas": { + "AcceptedAttachmentSlot": { + "additionalProperties": false, + "properties": { + "content_types": { + "description": "Accepted types, e.g. ``application/pdf`` or ``image/*``; empty accepts any type.", + "items": { + "type": "string" + }, + "title": "Content Types", + "type": "array" + }, + "label": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Shown to people.", + "title": "Label" + }, + "max": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "Most files a run may include; empty is no limit.", + "title": "Max" + }, + "min": { + "default": 0, + "description": "Fewest files a run must include; fewer refuses the run, except on an email trigger set to run anyway, which lists the shortfall.", + "title": "Min", + "type": "integer" + }, + "name": { + "description": "Lowercase letters, digits and underscores, starting with a letter. Steps reference the files as ``{{agent.attachments.}}``.", + "title": "Name", + "type": "string" + }, + "name_pattern": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Filename glob a file must also match, ignoring case.", + "title": "Name Pattern" + } + }, + "required": [ + "name" + ], + "title": "AcceptedAttachmentSlot", + "type": "object" + }, + "AcceptedAttachmentsResponse": { + "properties": { + "accepted_attachments": { + "items": { + "$ref": "#/components/schemas/AcceptedAttachmentSlot" + }, + "title": "Accepted Attachments", + "type": "array" + }, + "agent_id": { + "format": "uuid", + "title": "Agent Id", + "type": "string" + }, + "trigger_id": { + "format": "uuid", + "title": "Trigger Id", + "type": "string" + } + }, + "required": [ + "trigger_id", + "agent_id", + "accepted_attachments" + ], + "title": "AcceptedAttachmentsResponse", + "type": "object" + }, "AddConversationTurnRequest": { "properties": { "actions_taken": { @@ -89,14 +182,22 @@ "type": "object" }, "AgentAttachmentRefsApiResponse": { - "description": "Static attachment-reference contract for an agent.\n\nMirrors the MCP ``get_agent_attachment_references`` tool: returns\nwhat files (if any) an agent's templates expect on a run so API\nconsumers can stage uploads correctly before calling\n``POST /agents/{id}/runs``.", + "description": "The input attachments an agent's trigger declares.\n\nMirrors the MCP ``get_agent_attachment_references`` tool, so API\nconsumers can stage uploads that fit before calling\n``POST /agents/{id}/runs``.", "properties": { + "accepted_attachments": { + "description": "The attachments the agent's trigger declares. A run's files are each assigned to one; a file none accepts, or an attachment with fewer files than its ``min``, rejects the run with HTTP 400. Steps reference one as ``{{agent.attachments.}}``.", + "items": { + "$ref": "#/components/schemas/AcceptedAttachmentSlot" + }, + "title": "Accepted Attachments", + "type": "array" + }, "agent": { "$ref": "#/components/schemas/AttachmentRefsSourceApiSummary", - "description": "Aggregated selector summary across all consumer steps. ``exact_names`` entries must each appear in the upload batch; ``indexes_max+1`` is the minimum file count; every ``patterns`` glob must match at least one upload." + "description": "Aggregated summary of the agent-file references in the steps. Informational: which files a run accepts is ``accepted_attachments``." }, "requires_uploads": { - "description": "When ``false`` the agent's definition does NOT reference any uploaded attachments \u2014 ``POST /agents/{id}/upload-input`` will reject with HTTP 400. When ``true`` the ``agent`` block lists the specific selectors a run-time batch must satisfy.", + "description": "When ``false`` the agent takes no files through the API \u2014 it has no ``dynamic_input`` trigger, or that trigger declares no attachments \u2014 and ``POST /agents/{id}/upload-input`` will reject with HTTP 400. When ``true`` ``accepted_attachments`` lists what a run's files must fit.", "title": "Requires Uploads", "type": "boolean" } @@ -569,7 +670,7 @@ "type": "null" } ], - "description": "ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` \u2014 use that field to attach multiple files. May be combined with ``input``: the prompt text leads and the file's extracted text follows under a ``# {filename}`` heading.\n\n**Attachment visibility:** a step only sees the upload when its template references the input \u2014 via ``{{input}}`` / ``{{agent.input}}`` / ``{{step..input|output}}`` (implicit, all attachments) or the ``{{attachments[\u2026]}}`` family (explicit narrowing \u2014 e.g. ``{{attachments[0]}}``, ``{{attachments[*.pdf]}}``).\n\n**Per-batch validation:** every selector the agent's definition declares must be satisfied or the run is rejected with HTTP 400. Exact-name selectors require that filename to be present; indexed selectors require at least N+1 files; glob patterns require at least one matching filename.", + "description": "ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` \u2014 use that field to attach multiple files. May be combined with ``input``: the prompt text leads and the file follows under a ``# {filename}`` heading (before ``Seclai-Version: 2026-10-16``, followed by its extracted text).\n\n**Which steps receive it:** a step that sends or stores files takes the files its ``attachments`` field selects. An LLM step (``prompt_call``, ``extract_data``, ``evaluate_step``) takes the files its ``attachments`` field names, or else the files its plain-text templates reference: ``{{agent.attachments.}}`` for one attachment the trigger declares, or ``{{agent.input}}`` for every upload unless a template also names an agent attachment.\n\n**Per-batch validation:** the batch must fit the trigger's ``accepted_attachments`` \u2014 every file fits one declared attachment and each attachment gets at least its ``min`` files \u2014 or the run is rejected with HTTP 400.", "title": "Input Upload Id" }, "input_upload_ids": { @@ -586,7 +687,7 @@ "type": "null" } ], - "description": "IDs of multiple previously uploaded files. Each upload's extracted text is concatenated under a heading; each upload's binary is surfaced as a separate ``MediaAttachment`` so multi-modal prompt steps reason over all files at once. Steps narrow visibility via ``{{attachments[\u2026]}}`` selectors (by index, filename, or fnmatch glob). The batch must satisfy every selector the agent declares \u2014 exact names, indexed references (length must exceed the highest index), and glob patterns (each pattern needs at least one match). Mismatches return HTTP 400 with the unmet requirements listed. Mutually exclusive with ``input_upload_id`` (two spellings of the same batch), but may be combined with ``input`` \u2014 the prompt text leads and the per-file sections follow, so \"a photo plus a sentence about it\" needs no synthetic text upload. Max 20 uploads per run.", + "description": "IDs of multiple previously uploaded files. Each upload gets a heading in ``input`` (before ``Seclai-Version: 2026-10-16``, followed by its extracted text); each upload reaches steps as a separate file (before ``Seclai-Version: 2026-10-16``, a text upload in the open ``files`` attachment is written into ``input`` instead). Steps choose files as described under ``input_upload_id``. The batch must fit the trigger's ``accepted_attachments``; a mismatch returns HTTP 400 listing what does not fit. Mutually exclusive with ``input_upload_id`` (two spellings of the same batch), but may be combined with ``input`` \u2014 the prompt text leads and the per-file sections follow, so \"a photo plus a sentence about it\" needs no synthetic text upload. Max 20 uploads per run.", "title": "Input Upload Ids" }, "metadata": { @@ -620,7 +721,7 @@ "type": "null" } ], - "description": "Re-run this agent reusing a prior run's uploaded input files. The files are re-resolved server-side from the source run (which must belong to this account and agent) \u2014 you do not re-upload them. Combine with ``input`` to change the text while keeping the files. A fresh upload batch (``input_upload_id(s)``) takes precedence and disables replay. Binaries swept by retention fall back to their extracted text.", + "description": "Re-run this agent reusing a prior run's uploaded input files. The files are re-resolved server-side from the source run (which must belong to this account and agent) \u2014 you do not re-upload them. Combine with ``input`` to change the text while keeping the files. A fresh upload batch (``input_upload_id(s)``) takes precedence and disables replay. Binaries swept by retention fall back to their extracted text. Files the trigger's ``accepted_attachments`` no longer accepts are left out.", "title": "Replay Of Run Id" } }, @@ -747,7 +848,7 @@ "type": "null" } ], - "description": "The run's output text; its files are in `attachments`. Below `Seclai-Version: 2026-09-30` an output that has files is instead the manifest JSON `{schema, text, attachments: [{storage_key, mime, name, label, bytes}]}`; `bytes` is absent on runs made before that version shipped.", + "description": "The run's output text; its files are in `attachments`. Below `Seclai-Version: 2026-09-30` an output that has files is instead the manifest JSON `{schema, text, attachments: [{storage_key, mime, name, label, bytes}]}`; `bytes` can be `null` on runs made before that version shipped.", "title": "Output" }, "output_content_type": { @@ -813,7 +914,7 @@ "type": "null" } ], - "description": "When this run's trace content was deleted under the account's agent-trace retention window. Non-null means `input`, `output` and every step's and tool call's I/O are null **by design** and will never be available again \u2014 the run aged out, it did not fail. Branch on this rather than on a null `output`: a run that genuinely produced nothing looks identical. Status, timing and credits remain accurate.", + "description": "When this run's trace content was deleted under the account's agent-trace retention window. Non-null means `input`, `output` and every step's and tool call's I/O are null **by design** and will never be available again \u2014 the run aged out, it did not fail. A tool call's `error` may be null as well, so a failed tool call can report its status without a message. Branch on this rather than on a null `output`: a run that genuinely produced nothing looks identical. Status, timing and credits remain accurate.", "title": "Trace Purged At" }, "wait_ms": { @@ -963,7 +1064,7 @@ "type": "null" } ], - "description": "Authoring problems the step ran into, whether or not it then failed, such as a file name selector that matched none of its source's files.", + "description": "Problems the step ran into, whether or not it then failed, such as a file name selector that matched none of its source's files, or a model that returned no answer.", "title": "Warnings" } }, @@ -984,6 +1085,12 @@ }, "AgentRunStreamRequest": { "properties": { + "include_reasoning": { + "default": false, + "description": "Receive `stream_reasoning` events carrying the model's reasoning while it thinks. They are sent only for a `streaming_result` step whose author enabled `show_reasoning`, and never when a governance policy redacts that step.", + "title": "Include Reasoning", + "type": "boolean" + }, "input": { "anyOf": [ { @@ -1006,7 +1113,7 @@ "type": "null" } ], - "description": "ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` \u2014 use that field to attach multiple files. May be combined with ``input``. Subject to the same per-batch attachment-selector validation as the non-streaming endpoint.", + "description": "ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` \u2014 use that field to attach multiple files. May be combined with ``input``. Must fit the trigger's ``accepted_attachments``, as on the non-streaming endpoint.", "title": "Input Upload Id" }, "input_upload_ids": { @@ -1023,7 +1130,7 @@ "type": "null" } ], - "description": "IDs of multiple previously uploaded files. See the non-streaming endpoint for full semantics, including per-batch selector validation (exact names, indexed references, and glob patterns must all be satisfied or the run is rejected with HTTP 400) and combining the batch with ``input`` prompt text. Max 20.", + "description": "IDs of multiple previously uploaded files. See the non-streaming endpoint for full semantics, including fitting the trigger's ``accepted_attachments`` (else HTTP 400) and combining the batch with ``input`` prompt text. Max 20.", "title": "Input Upload Ids" }, "metadata": { @@ -1051,7 +1158,7 @@ "type": "null" } ], - "description": "Re-run reusing a prior run's uploaded input files (re-resolved server-side from the source run, which must belong to this account and agent). A fresh upload batch takes precedence.", + "description": "Re-run reusing a prior run's uploaded input files (re-resolved server-side from the source run, which must belong to this account and agent). A fresh upload batch takes precedence. Files the trigger's ``accepted_attachments`` no longer accepts are left out.", "title": "Replay Of Run Id" } }, @@ -1319,6 +1426,18 @@ "description": "Sampling configuration for sample_and_flag mode.", "title": "Sampling Config" }, + "trigger_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "ID of the agent's trigger, for the `/agents/{agent_id}/triggers/{trigger_id}/\u2026` endpoints such as `accepted-attachments` and `email-config`.", + "title": "Trigger Id" + }, "trigger_type": { "anyOf": [ { @@ -2910,6 +3029,90 @@ "title": "CompatibleRunResponse", "type": "object" }, + "ContentAttachmentResponse": { + "description": "A file attached to a content item.", + "properties": { + "content_type": { + "description": "MIME type of the attached file.", + "title": "Content Type", + "type": "string" + }, + "created_at": { + "description": "When the file was first attached.", + "title": "Created At", + "type": "string" + }, + "id": { + "description": "The attachment's id, which the single-attachment endpoints take.", + "title": "Id", + "type": "string" + }, + "indexed": { + "description": "Whether indexing the file for search was asked for.", + "title": "Indexed", + "type": "boolean" + }, + "indexing_error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why the file was not indexed, when `indexing_status` is `failed`.", + "title": "Indexing Error" + }, + "indexing_status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "`pending`, `completed` or `failed`; null when indexing was not asked for. Search finds the file only when `completed`.", + "title": "Indexing Status" + }, + "key": { + "description": "The attachment's key, unique within the item.", + "title": "Key", + "type": "string" + }, + "metadata": { + "additionalProperties": true, + "description": "What is known about the file beyond its bytes. An image extracted from a PDF carries its `page_number`, and `page_render: true` when it is a render of the whole page. An image or video from a web page carries `source_url` (the address it was fetched from), `position` (its place among the media the page listed, from 0) and, when the page gave one, `alt_text`. Empty for most files. A retrieval metadata filter matches these keys, except `alt_text`, which is indexed as the attachment's text.", + "title": "Metadata", + "type": "object" + }, + "size_bytes": { + "description": "Size of the attached file in bytes.", + "title": "Size Bytes", + "type": "integer" + }, + "updated_at": { + "description": "When the attachment last changed.", + "title": "Updated At", + "type": "string" + } + }, + "required": [ + "id", + "key", + "content_type", + "size_bytes", + "indexed", + "indexing_status", + "indexing_error", + "created_at", + "updated_at", + "metadata" + ], + "title": "ContentAttachmentResponse", + "type": "object" + }, "ContentEmbeddingResponse": { "description": "Response model for content embedding.", "properties": { @@ -3560,6 +3763,66 @@ "description": "Chunk size for content processing.", "title": "Chunk Size" }, + "cloud_drive_connection_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Required for a cloud_drive source, and ignored on any other: the id of a connected drive, from GET /cloud-drives.", + "title": "Cloud Drive Connection Id" + }, + "cloud_drive_content_types": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: comma-separated MIME types a file must have to be indexed. Omit for no filter.", + "title": "Cloud Drive Content Types" + }, + "cloud_drive_folder_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the folder to index, as a path inside the drive. Omit to index the connected drive's own folder.", + "title": "Cloud Drive Folder Path" + }, + "cloud_drive_max_file_mb": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: files larger than this many megabytes are skipped. Omit for no limit of the source's own.", + "title": "Cloud Drive Max File Mb" + }, + "cloud_drive_path_pattern": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: a glob a file's path must match to be indexed, such as `**/*.pdf` or `/reports/*`. Omit for no filter.", + "title": "Cloud Drive Path Pattern" + }, "content_filter": { "anyOf": [ { @@ -3585,6 +3848,33 @@ "description": "Embedding dimensions override.", "title": "Dimensions" }, + "document_images": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "description": "Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a text-only embedder, by the text in each image. Applies to documents added after it changes. Defaults to true; below Seclai-Version 2026-10-18 it defaults to false on a text-only embedder. On a website or RSS source it is ignored: `media_types` decides.", + "title": "Document Images" + }, + "email_allowed_senders": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "Required for an email source, and only valid there: the senders whose mail is stored. Each entry is a full address (news@example.com) or a bare domain (example.com), which also matches its sub-domains. Matched against the message's From address, which must pass DMARC.", + "title": "Email Allowed Senders" + }, "embedding_model": { "anyOf": [ { @@ -3597,6 +3887,21 @@ "description": "Embedding model override \u2014 a `model_type` from `GET /models/embedders`, which also reports each embedder's `supported_input_media`. Defaults to the platform embedder (`default_model_type` on that endpoint) when omitted. Indexing images or video requires an embedder that lists that modality.", "title": "Embedding Model" }, + "feed_attachments": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "Kinds of file listed beside a feed item's content to attach to the item and index, on an RSS source. Subset of ['enclosures', 'item_image', 'media_rss']; any other value is refused. None are attached unless chosen.", + "title": "Feed Attachments" + }, "index_mode": { "anyOf": [ { @@ -3620,7 +3925,7 @@ "type": "null" } ], - "description": "Media kinds to extract from indexed content and embed as multi-modal KB chunks. Subset of ['images', 'video']. Only kinds the source's embedder can index are honored (see `supported_input_media` on GET /models/embedders); unsupported values are dropped. Omit / [] for text-only.", + "description": "Media kinds in a web page's main content to attach to the page's item and index, on a website or RSS source. Subset of ['images', 'video']. From `Seclai-Version: 2026-10-13` any other value, and any kind on another source type, is refused with a 400; older versions drop an unknown value and store the rest. A kind the source's embedder cannot index is stored and not indexed (see `supported_input_media` on GET /models/embedders). 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files. Applies to pages and documents added after it is set.", "title": "Media Types" }, "name": { @@ -3664,7 +3969,7 @@ "type": "null" } ], - "description": "Max items per poll.", + "description": "The most new feed items a scheduled poll takes. Read for RSS feeds only: from Seclai-Version 2026-10-19 any other source type rejects it with 400. Earlier versions store it there. An email source rejects it at every version.", "title": "Polling Max Items" }, "retention": { @@ -3681,7 +3986,7 @@ "title": "Retention" }, "source_type": { - "description": "Source type: rss, website, or custom_index. The legacy value 'file_uploads' is accepted as an alias for custom_index.", + "description": "Source type: rss_feed, website, custom_index, cloud_drive or email. The legacy value 'file_uploads' is accepted as an alias for custom_index.", "title": "Source Type", "type": "string" }, @@ -4161,42 +4466,141 @@ "title": "EmailDomainsListResponse", "type": "object" }, - "EmailTriggerConfigResponse": { - "description": "An EMAIL_RECEIVED trigger's resolved address(es) and config.", + "EmailSourceRejectionListResponse": { + "description": "A page of mail an email content source refused.", "properties": { - "agent_id": { - "format": "uuid", - "title": "Agent Id", - "type": "string" - }, - "email_addresses": { + "data": { "items": { - "type": "string" + "$ref": "#/components/schemas/EmailSourceRejectionResponse" }, - "title": "Email Addresses", + "title": "Data", "type": "array" }, - "email_alias": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Email Alias" - }, - "email_allowed_senders": { - "anyOf": [ - { - "items": { - "type": "string" - }, - "type": "array" - }, - { - "type": "null" + "pagination": { + "$ref": "#/components/schemas/PaginationResponse" + } + }, + "required": [ + "data", + "pagination" + ], + "title": "EmailSourceRejectionListResponse", + "type": "object" + }, + "EmailSourceRejectionResponse": { + "description": "Mail an email content source refused: who sent it and why, never what\nit said.", + "properties": { + "auth_verdicts": { + "additionalProperties": { + "type": "string" + }, + "description": "The SPF, DKIM and DMARC verdicts reported for the message.", + "title": "Auth Verdicts", + "type": "object" + }, + "authenticated": { + "description": "Whether the message passed DMARC, which is what authenticates its From address. Adding an unauthenticated sender to the allowed senders does not let its mail in.", + "title": "Authenticated", + "type": "boolean" + }, + "created_at": { + "description": "When the mail was refused.", + "title": "Created At", + "type": "string" + }, + "from_address": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The address in the message's From line, which the source's allowed senders are matched against. Null when no single From address could be read from the message unambiguously.", + "title": "From Address" + }, + "id": { + "description": "Unique identifier of the refusal.", + "title": "Id", + "type": "string" + }, + "reason": { + "description": "Why it was refused: sender_not_allowed, unauthenticated_sender, unreadable_from, sender_blocked, spam, virus, unsafe_content, rate_limited, account_not_chargeable or empty_message; or, for a message the source received before, what became of the earlier one: repeat_stored, repeat_held, repeat_deleted or repeat_in_progress.", + "title": "Reason", + "type": "string" + }, + "recipient": { + "description": "The source address it was sent to.", + "title": "Recipient", + "type": "string" + }, + "sender": { + "description": "The envelope sender. For bulk mail this is the delivery provider's bounce address, not the From address.", + "title": "Sender", + "type": "string" + }, + "sender_ip": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "IP address the mail came from.", + "title": "Sender Ip" + } + }, + "required": [ + "id", + "created_at", + "recipient", + "sender", + "sender_ip", + "reason", + "authenticated" + ], + "title": "EmailSourceRejectionResponse", + "type": "object" + }, + "EmailTriggerConfigResponse": { + "description": "An EMAIL_RECEIVED trigger's resolved address(es) and config.", + "properties": { + "agent_id": { + "format": "uuid", + "title": "Agent Id", + "type": "string" + }, + "email_addresses": { + "items": { + "type": "string" + }, + "title": "Email Addresses", + "type": "array" + }, + "email_alias": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Email Alias" + }, + "email_allowed_senders": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" } ], "title": "Email Allowed Senders" @@ -4216,6 +4620,11 @@ "title": "Email Require Sender Auth", "type": "boolean" }, + "email_run_on_attachment_mismatch": { + "default": false, + "title": "Email Run On Attachment Mismatch", + "type": "boolean" + }, "trigger_id": { "format": "uuid", "title": "Trigger Id", @@ -4779,7 +5188,7 @@ "type": "null" } ], - "description": "Mean score across all evaluated results, or null if none.", + "description": "Mean score of the final passed and failed results, or null if none. On /api before Seclai-Version 2026-10-21 it averages every final result's stored score, `error` included.", "title": "Average Score" }, "error": { @@ -5491,7 +5900,7 @@ "type": "null" } ], - "description": "Suggested agent-level configuration, if any.", + "description": "Suggested agent-level configuration, if any. For an email_received agent it may carry `email_run_on_attachment_mismatch`, which the caller applies through the trigger's email-config endpoint. For a dynamic_input or email_received agent it may carry `accepted_attachments`, which the caller passes with the steps to `PUT /agents/{agent_id}/definition` so both save together.", "title": "Agent Config" }, "conversation_id": { @@ -6123,17 +6532,17 @@ "type": "object" }, "InsufficientCreditsDetail": { - "description": "``detail`` body for a 402 ``insufficient_credits`` response.", + "description": "``error`` body of a 402 ``insufficient_credits`` response.", "properties": { "account_id": { "description": "UUID of the account that ran out of credits.", "title": "Account Id", "type": "string" }, - "error": { + "code": { "const": "insufficient_credits", "description": "Stable machine-readable error code.", - "title": "Error", + "title": "Code", "type": "string" }, "message": { @@ -6143,7 +6552,7 @@ } }, "required": [ - "error", + "code", "message", "account_id" ], @@ -6151,14 +6560,14 @@ "type": "object" }, "InsufficientCreditsResponse": { - "description": "402 envelope returned when the account has exhausted its credits.", + "description": "402 envelope returned when the account has exhausted its credits.\n\nThe wire shape ``http_exception_handler`` and ``insufficient_credits_exception_handler`` send.", "properties": { - "detail": { + "error": { "$ref": "#/components/schemas/InsufficientCreditsDetail" } }, "required": [ - "detail" + "error" ], "title": "InsufficientCreditsResponse", "type": "object" @@ -7405,6 +7814,30 @@ "title": "ServiceUnavailableError", "type": "object" }, + "SetAcceptedAttachmentsRequest": { + "properties": { + "accepted_attachments": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/AcceptedAttachmentSlot" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "The input attachments the trigger accepts; ``null`` accepts any files (one attachment named ``files``). Only ``dynamic_input`` and ``email_received`` triggers take files.", + "title": "Accepted Attachments" + } + }, + "required": [ + "accepted_attachments" + ], + "title": "SetAcceptedAttachmentsRequest", + "type": "object" + }, "SetAutoBlockModeRequest": { "description": "Set the account's governance auto-block mode (shared REST request).", "properties": { @@ -7419,6 +7852,62 @@ "title": "SetAutoBlockModeRequest", "type": "object" }, + "SkippedAttachmentReason": { + "enum": [ + "displayed_in_body", + "over_cap", + "no_filename", + "undecodable" + ], + "title": "SkippedAttachmentReason", + "type": "string" + }, + "SkippedAttachmentResponse": { + "description": "A part of an email that was not stored as an attachment.", + "properties": { + "content_type": { + "description": "The part's declared media type.", + "title": "Content Type", + "type": "string" + }, + "filename": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The file name the part is listed under; null when it had none.", + "title": "Filename" + }, + "reason": { + "$ref": "#/components/schemas/SkippedAttachmentReason", + "description": "Why the part was not stored." + }, + "size_bytes": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "Decoded size in bytes.", + "title": "Size Bytes" + } + }, + "required": [ + "filename", + "content_type", + "size_bytes", + "reason" + ], + "title": "SkippedAttachmentResponse", + "type": "object" + }, "SolutionSourceConnectionResponse": { "properties": { "id": { @@ -7642,7 +8131,7 @@ }, "extracted_media_capped": { "default": false, - "description": "True when extraction stopped with media still unread, so the item references more media than was indexed and media search will not match anything past the cut. Two causes: a web page that ran out of the budget for fetching remote assets, or a container that could not be read to the end (a truncated or hostile archive). An uploaded document that reads cleanly is never capped, however much media it holds \u2014 there is no limit on that.", + "description": "True when extraction stopped with media still unread, so the item references more media than was attached and media search will not match anything past the cut. The cause is a web page that ran out of the budget for fetching remote assets or listed more media than is recorded, or a web page or document that could not be read to the end.", "title": "Extracted Media Capped", "type": "boolean" }, @@ -7655,7 +8144,7 @@ "type": "null" } ], - "description": "Number of embedded images / videos extracted from inside this item and indexed as their own chunks. There is no limit on this \u2014 a document contributes as many as it holds. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container, or found nothing. Treat null as 'unknown', never as zero.", + "description": "Number of images / videos in this web page's main content, or of images inside this PDF or Office document, that were attached to the item on this source; a file over the per-file size limit, listed as a failed attachment, is not counted. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container or this source's settings, or found nothing. Treat null as 'unknown', never as zero.", "title": "Extracted Media Count" }, "extracted_media_limit": { @@ -7667,9 +8156,15 @@ "type": "null" } ], - "description": "The bound that was reached, when extracted_media_capped is true and the stop was a bound \u2014 a number of fetch attempts, or a number of seconds. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired.", + "description": "The bound that was reached, when extracted_media_capped is true and the stop was a bound \u2014 a number of fetch attempts, of seconds, of bytes, or of media listed. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired.", "title": "Extracted Media Limit" }, + "held_for_review": { + "default": false, + "description": "An ENFORCE governance policy blocked this item at import. It is held for review and is not retrievable: resolving its blocking evaluations releases it into the source, and it is purged when the hold window ends.", + "title": "Held For Review", + "type": "boolean" + }, "indexed_at": { "anyOf": [ { @@ -8002,6 +8497,66 @@ "description": "Chunk size for content processing.", "title": "Chunk Size" }, + "cloud_drive_connection_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the id of the connected drive it indexes. Null for every other source type.", + "title": "Cloud Drive Connection Id" + }, + "cloud_drive_content_types": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the comma-separated MIME types a file must have to be indexed. Null when there is no filter.", + "title": "Cloud Drive Content Types" + }, + "cloud_drive_folder_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the folder it indexes. Null when it indexes the connected drive's own folder.", + "title": "Cloud Drive Folder Path" + }, + "cloud_drive_max_file_mb": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the size in megabytes above which a file is skipped. Null when the source sets no limit of its own.", + "title": "Cloud Drive Max File Mb" + }, + "cloud_drive_path_pattern": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the glob a file's path must match to be indexed. Null when there is none.", + "title": "Cloud Drive Path Pattern" + }, "content_count": { "default": 0, "description": "Number of content items associated with the source connection.", @@ -8030,6 +8585,39 @@ "description": "Dimensions of the embedding model.", "title": "Dimensions" }, + "document_images": { + "default": true, + "description": "Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a source that follows no web pages and has a text-only embedder, by the text in each image. Applies to documents added after it changes. On a website or RSS source it reports whether `media_types` holds 'images', and the images are attached only when the source's embedder indexes images.", + "title": "Document Images", + "type": "boolean" + }, + "email_address": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For an email source: the address to send mail to. Null for every other source type.", + "title": "Email Address" + }, + "email_allowed_senders": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "For an email source: the addresses and domains whose mail is stored. Null for every other source type.", + "title": "Email Allowed Senders" + }, "embedding_model": { "anyOf": [ { @@ -8054,6 +8642,14 @@ "description": "Type of the embedding model.", "title": "Embedding Model Type" }, + "feed_attachments": { + "description": "Kinds of file listed beside a feed item's content that an RSS source attaches to the item and indexes (subset of ['enclosures', 'item_image', 'media_rss']).", + "items": { + "type": "string" + }, + "title": "Feed Attachments", + "type": "array" + }, "free_retention_days": { "anyOf": [ { @@ -8089,7 +8685,7 @@ "description": "Index mode for custom_index sources: fast_and_cheap, balanced, slow_and_thorough, or custom." }, "media_types": { - "description": "Media kinds extracted from indexed content and embedded as multi-modal KB chunks (subset of ['images', 'video']). Empty = text-only.", + "description": "Media kinds in a web page's main content that are attached to the page's item and indexed (subset of ['images', 'video']). On a website or RSS source 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files.", "items": { "type": "string" }, @@ -8146,7 +8742,7 @@ "type": "null" } ], - "description": "Maximum items to poll for the source connection.", + "description": "The most new feed items a scheduled poll takes. Read for RSS feeds only.", "title": "Polling Max Items" }, "pulled_at": { @@ -8549,9 +9145,14 @@ "score": { "title": "Score", "type": "number" + }, + "status": { + "$ref": "#/components/schemas/EvaluationStatus", + "description": "`passed`, `failed`, or `error` when the evaluator returned no verdict." } }, "required": [ + "status", "score", "passed", "explanation" @@ -8593,11 +9194,26 @@ }, "UpdateAgentDefinitionRequest": { "properties": { - "definition": { - "additionalProperties": true, - "description": "The full agent definition (name, description, tags, steps). Steps form a tree workflow. Each step has a `step_type`, `id`, `name`, and type-specific config. Content enrichment steps (write_metadata, write_content_attachment, load_content_attachment, load_content) require content-triggered agents.", - "title": "Definition", - "type": "object" + "accepted_attachments": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/AcceptedAttachmentSlot" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "When given, declared on the main branch's file-taking triggers in the same save, so the steps may read its slots as `{{agent.attachments.}}`; omitted, the triggers keep theirs.", + "title": "Accepted Attachments" + }, + "definition": { + "additionalProperties": true, + "description": "The full agent definition (name, description, tags, steps). Steps form a tree workflow. Each step has a `step_type`, `id`, `name`, and type-specific config. Content enrichment steps (write_metadata, write_content_attachment, load_content_attachment, load_content) require content-triggered agents.", + "title": "Definition", + "type": "object" }, "expected_change_id": { "description": "The change_id from the last GET, for optimistic locking.", @@ -9033,6 +9649,96 @@ "UpdateSourceBody": { "description": "Request body for updating a content source.", "properties": { + "cloud_drive_content_types": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: comma-separated MIME types a file must have to be indexed. Send an empty string to clear it; omit to leave it unchanged.", + "title": "Cloud Drive Content Types" + }, + "cloud_drive_folder_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: the folder to index, as a path inside the drive. Send an empty string to index the connected drive's own folder; omit to leave it unchanged.", + "title": "Cloud Drive Folder Path" + }, + "cloud_drive_max_file_mb": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: files larger than this many megabytes are skipped. Send 0 to clear the source's own limit; omit to leave it unchanged.", + "title": "Cloud Drive Max File Mb" + }, + "cloud_drive_path_pattern": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "For a cloud_drive source: a glob a file's path must match to be indexed, such as `**/*.pdf` or `/reports/*`. Send an empty string to clear it; omit to leave it unchanged.", + "title": "Cloud Drive Path Pattern" + }, + "document_images": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "description": "Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a text-only embedder, by the text in each image. Applies to documents added after it changes. Omit the field to leave it unchanged. On a website or RSS source it is ignored: `media_types` decides.", + "title": "Document Images" + }, + "email_allowed_senders": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "For an email source: replaces the allowed senders. Each entry is a full address or a bare domain. The list cannot be emptied. Omit to leave it unchanged.", + "title": "Email Allowed Senders" + }, + "feed_attachments": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "Kinds of file listed beside a feed item's content to attach to the item and index, on an RSS source. Subset of ['enclosures', 'item_image', 'media_rss']; any other value is refused. [] attaches none. Applies to items added after it changes. Omit the field to leave it unchanged.", + "title": "Feed Attachments" + }, "media_types": { "anyOf": [ { @@ -9045,7 +9751,7 @@ "type": "null" } ], - "description": "Media kinds to extract from indexed content and embed as multi-modal KB chunks. Subset of ['images', 'video']. Only kinds the source's embedder can index are honored (see `supported_input_media` on GET /models/embedders); unsupported values are dropped. [] disables media extraction (text-only).", + "description": "Media kinds in a web page's main content to attach to the page's item and index, on a website or RSS source. Subset of ['images', 'video']. From `Seclai-Version: 2026-10-13` any other value, and any kind on another source type, is refused with a 400; older versions drop an unknown value and store the rest. A kind the source's embedder cannot index is stored and not indexed (see `supported_input_media` on GET /models/embedders). [] attaches no media from web pages. 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files. Applies to pages and documents added after it changes.", "title": "Media Types" }, "name": { @@ -9582,6 +10288,21 @@ }, "routers__api__agents__CreateAgentRequest": { "properties": { + "accepted_attachments": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/AcceptedAttachmentSlot" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "description": "The input attachments the trigger accepts. Omitted, the ``agent_definition`` trigger's declaration is kept when the export carries one and both trigger types take files; otherwise a dynamic_input or email_received trigger accepts any files (one attachment named ``files``), and any other trigger none.", + "title": "Accepted Attachments" + }, "agent_definition": { "anyOf": [ { @@ -9745,6 +10466,18 @@ ], "description": "When true (default for new triggers), the envelope sender must pass SPF or DMARC even on an open inbox (no allowlist); unauthenticated, spoofable mail is rejected. Set false to accept fully unauthenticated mail on an open inbox.", "title": "Require Sender Auth" + }, + "run_on_attachment_mismatch": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "description": "When true (default false), an email whose attachments don't fit what the agent expects still runs: files the agent can't take are left out and the problems are listed in the `email_attachment_issues` run metadata. When false, the run fails.", + "title": "Run On Attachment Mismatch" } }, "title": "SetEmailTriggerConfigRequest", @@ -10384,6 +11117,152 @@ "title": "UpdateOrganizationAlertPreferenceRequest", "type": "object" }, + "routers__api__contents__ContentAttachmentDetailResponse": { + "description": "One attached file, with the text indexed from it.", + "properties": { + "content_type": { + "description": "MIME type of the attached file.", + "title": "Content Type", + "type": "string" + }, + "created_at": { + "description": "When the file was first attached.", + "title": "Created At", + "type": "string" + }, + "file_withheld": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why the file's bytes are not served, or null when they are: `blocked_by_governance_policy`, `redacted_by_governance_policy` (any text below is the redacted text), or `pending_screening`.", + "title": "File Withheld" + }, + "id": { + "description": "The attachment's id, which the single-attachment endpoints take.", + "title": "Id", + "type": "string" + }, + "indexed": { + "description": "Whether indexing the file for search was asked for.", + "title": "Indexed", + "type": "boolean" + }, + "indexing_error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Why the file was not indexed, when `indexing_status` is `failed`.", + "title": "Indexing Error" + }, + "indexing_status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "`pending`, `completed` or `failed`; null when indexing was not asked for. Search finds the file only when `completed`.", + "title": "Indexing Status" + }, + "key": { + "description": "The attachment's key, unique within the item.", + "title": "Key", + "type": "string" + }, + "metadata": { + "additionalProperties": true, + "description": "What is known about the file beyond its bytes. An image extracted from a PDF carries its `page_number`, and `page_render: true` when it is a render of the whole page. An image or video from a web page carries `source_url` (the address it was fetched from), `position` (its place among the media the page listed, from 0) and, when the page gave one, `alt_text`. Empty for most files. A retrieval metadata filter matches these keys, except `alt_text`, which is indexed as the attachment's text.", + "title": "Metadata", + "type": "object" + }, + "size_bytes": { + "description": "Size of the attached file in bytes.", + "title": "Size Bytes", + "type": "integer" + }, + "text_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "The requested range of the text the file is indexed by; null when the file has no completed index or was indexed without text.", + "title": "Text Content" + }, + "text_content_end": { + "title": "Text Content End", + "type": "integer" + }, + "text_content_start": { + "title": "Text Content Start", + "type": "integer" + }, + "text_content_total_length": { + "title": "Text Content Total Length", + "type": "integer" + }, + "updated_at": { + "description": "When the attachment last changed.", + "title": "Updated At", + "type": "string" + } + }, + "required": [ + "id", + "key", + "content_type", + "size_bytes", + "indexed", + "indexing_status", + "indexing_error", + "created_at", + "updated_at", + "metadata", + "file_withheld", + "text_content", + "text_content_start", + "text_content_end", + "text_content_total_length" + ], + "title": "ContentAttachmentDetailResponse", + "type": "object" + }, + "routers__api__contents__ContentAttachmentsListResponse": { + "description": "Response model for a content item's attachments.", + "properties": { + "data": { + "items": { + "$ref": "#/components/schemas/ContentAttachmentResponse" + }, + "title": "Data", + "type": "array" + }, + "pagination": { + "$ref": "#/components/schemas/PaginationResponse" + } + }, + "required": [ + "data", + "pagination" + ], + "title": "ContentAttachmentsListResponse", + "type": "object" + }, "routers__api__contents__ContentDetailResponse": { "description": "Response model for content detail.", "properties": { @@ -10469,7 +11348,7 @@ }, "extracted_media_capped": { "default": false, - "description": "True when extraction stopped with media still unread, so the item references more media than was indexed and media search will not match anything past the cut. Two causes: a web page that ran out of the budget for fetching remote assets, or a container that could not be read to the end (a truncated or hostile archive). An uploaded document that reads cleanly is never capped, however much media it holds \u2014 there is no limit on that.", + "description": "True when extraction stopped with media still unread, so the item references more media than was attached and media search will not match anything past the cut. The cause is a web page that ran out of the budget for fetching remote assets or listed more media than is recorded, or a web page or document that could not be read to the end.", "title": "Extracted Media Capped", "type": "boolean" }, @@ -10482,7 +11361,7 @@ "type": "null" } ], - "description": "Number of embedded images / videos extracted from inside this item and indexed as their own chunks. There is no limit on this \u2014 a document contributes as many as it holds. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container, or found nothing. Treat null as 'unknown', never as zero.", + "description": "Number of images / videos in this web page's main content, or of images inside this PDF or Office document, that were attached to the item on this source; a file over the per-file size limit, listed as a failed attachment, is not counted. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container or this source's settings, or found nothing. Treat null as 'unknown', never as zero.", "title": "Extracted Media Count" }, "extracted_media_limit": { @@ -10494,7 +11373,7 @@ "type": "null" } ], - "description": "The bound that was reached, when extracted_media_capped is true and the stop was a bound \u2014 a number of fetch attempts, or a number of seconds. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired.", + "description": "The bound that was reached, when extracted_media_capped is true and the stop was a bound \u2014 a number of fetch attempts, of seconds, of bytes, or of media listed. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired.", "title": "Extracted Media Limit" }, "id": { @@ -10537,6 +11416,14 @@ "title": "Pulled At", "type": "string" }, + "skipped_attachments": { + "description": "Parts of an email delivered to an email content source that were not stored as attachments of this item, each with the reason: displayed_in_body (an image the message body shows, such as a signature logo), over_cap (beyond the per-message attachment limit), no_filename, or undecodable. size_bytes is null for a part that was never decoded. Empty for every other item.", + "items": { + "$ref": "#/components/schemas/SkippedAttachmentResponse" + }, + "title": "Skipped Attachments", + "type": "array" + }, "source_connection_content_version_id": { "description": "ID of the source connection content version.", "title": "Source Connection Content Version Id", @@ -12024,7 +12911,7 @@ "type": "null" } ], - "description": "Set when the file is non-text but the source's embedder is text-only \u2014 indexing will rely on OCR / transcription and may produce a FAILED row if no text can be extracted.", + "description": "Set when a file that is not text is indexed from its extracted text alone rather than embedded whole: the item is FAILED if no text can be extracted. Says so when the images inside a document are attached to the item and indexed as well.", "title": "Embedder Warning" }, "filename": { @@ -12568,6 +13455,11 @@ "schemas__v1__agent_evaluations__NonManualEvaluationModeStatResponse": { "description": "Per-mode rollup for evaluation activity.", "properties": { + "error": { + "description": "Results whose evaluator returned no verdict.", + "title": "Error", + "type": "integer" + }, "failed": { "title": "Failed", "type": "integer" @@ -12602,6 +13494,7 @@ "total", "passed", "failed", + "error", "flagged", "pass_rate", "failure_rate" @@ -12619,6 +13512,11 @@ "title": "By Mode", "type": "array" }, + "error": { + "description": "Results whose evaluator returned no verdict.", + "title": "Error", + "type": "integer" + }, "failed": { "title": "Failed", "type": "integer" @@ -12648,6 +13546,7 @@ "total", "passed", "failed", + "error", "flagged", "pass_rate", "failure_rate", @@ -12764,7 +13663,7 @@ ] }, "post": { - "description": "Create a new agent.\n\nTrigger types:\n- `dynamic_input`: triggered via API with user-provided input\n- `template_input`: triggered via API with a predefined template\n- `schedule`: triggered on a schedule\n- `new_content`: triggered when new content arrives\n- `email_received`: a virtual email inbox; runs when mail arrives at the agent's address. Configure the alias/allowlist with `PUT /agents/{agent_id}/triggers/{trigger_id}/email-config`.\n\nTemplates: `blank`, `retrieval_example`, `simple_qa`, `summarizer`, `json_extractor`, `content_change_notifier`, `scheduled_report`, `webhook_pipeline`\n\nImporting an existing agent:\n- Pass `agent_definition` with the JSON shape produced by `GET /agents/{id}/export`. The full extras suite (alert_configs, evaluation_criteria, governance_policies, schedules, solutions) is applied; items that don't resolve in this account are reported in the response's `import_warnings` array.\n- Use `POST /agents/preview-import` first to surface `unresolved_refs` (workflow refs to KBs, memory banks, source connections, sub-agents that don't exist here). Then pass `entity_remap: {source_uuid: target_uuid}` on this call to substitute them before save.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. Agent is created in the caller's account.", + "description": "Create a new agent.\n\nTrigger types:\n- `dynamic_input`: triggered via API with user-provided input\n- `template_input`: triggered via API with a predefined template\n- `schedule`: triggered on a schedule\n- `new_content`: triggered when new content arrives\n- `email_received`: a virtual email inbox; runs when mail arrives at the agent's address. Configure the alias/allowlist with `PUT /agents/{agent_id}/triggers/{trigger_id}/email-config`, using the `trigger_id` this response returns.\n\nTemplates: `blank`, `retrieval_example`, `simple_qa`, `summarizer`, `json_extractor`, `content_change_notifier`, `scheduled_report`, `webhook_pipeline`\n\nImporting an existing agent:\n- Pass `agent_definition` with the JSON shape produced by `GET /agents/{id}/export`. The full extras suite (alert_configs, evaluation_criteria, governance_policies, schedules, solutions) is applied; items that don't resolve in this account are reported in the response's `import_warnings` array.\n- Use `POST /agents/preview-import` first to surface `unresolved_refs` (workflow refs to KBs, memory banks, source connections, sub-agents that don't exist here). Then pass `entity_remap: {source_uuid: target_uuid}` on this call to substitute them before save.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. Agent is created in the caller's account.", "operationId": "create_agent_api_agents_post", "parameters": [ { @@ -13799,7 +14698,7 @@ }, "/agents/evaluation-criteria/{criteria_id}/summary": { "get": { - "description": "Get an aggregated summary of evaluation results for a criteria.\n\nReturns total, passed, failed, error, and flagged counts alongside the\naverage score, giving a quick overview of how the criteria is performing.", + "description": "Get an aggregated summary of evaluation results for a criteria.\n\nReturns total, passed, failed, error, and flagged counts alongside the\naverage score, giving a quick overview of how the criteria is performing.\nWith ``2026-10-21`` or later, ``average_score`` averages only passed and failed\nresults; earlier versions average every stored score, ``error`` included.", "operationId": "get_evaluation_summary_api_agents_evaluation_criteria__criteria_id__summary_get", "parameters": [ { @@ -13866,7 +14765,7 @@ }, "/agents/evaluation-results/non-manual-summary": { "get": { - "description": "Get an evaluation summary for API key clients.\n\nReturns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, sample_and_flag).\n\nThe ``agent_id`` scoping parameter is part of the ``2026-07-27`` changeset\n(opt in via the ``Seclai-Version`` header). Clients on the legacy baseline\nalways receive the account-wide rollup; ``agent_id`` is ignored for them so\nthe endpoint's behavior is frozen. With ``2026-07-27`` or later, the summary\nis scoped to ``agent_id`` when supplied (and returns 404 if it doesn't exist).", + "description": "Get an evaluation summary for API key clients.\n\nReturns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, sample_and_flag).\n\nWith ``2026-10-21`` or later, ``error`` results (the evaluator returned no\nverdict) are left out of ``failed``, and the rates are over passed and\nfailed results. Earlier versions count them in ``failed`` and rate over\nevery result. ``error`` is returned on every version.\n\nThe ``agent_id`` scoping parameter is part of the ``2026-07-27`` changeset\n(opt in via the ``Seclai-Version`` header). Clients on the legacy baseline\nalways receive the account-wide rollup; ``agent_id`` is ignored for them so\nthe endpoint's behavior is frozen. With ``2026-07-27`` or later, the summary\nis scoped to ``agent_id`` when supplied (and returns 404 if it doesn't exist).", "operationId": "get_non_manual_evaluation_summary_api_agents_evaluation_results_non_manual_summary_get", "parameters": [ { @@ -15065,7 +15964,7 @@ }, "/agents/{agent_id}/attachment-references": { "get": { - "description": "Return the static attachment-reference contract for an agent \u2014 what files the agent's definition expects on a run.\n\nCall this BEFORE staging uploads so you know whether the agent accepts files at all (``requires_uploads``), and which specific filenames/indexes/patterns the templates reference. Mismatched batches are rejected at run time with HTTP 400.", + "description": "Return the input attachments the agent's dynamic_input trigger declares \u2014 the files a run may carry.\n\nCall this BEFORE staging uploads so you know whether the agent accepts files at all (``requires_uploads``), and which attachments its trigger declares (``accepted_attachments``). Batches that do not fit them are rejected at run time with HTTP 400.", "operationId": "api_get_agent_attachment_references_api_agents__agent_id__attachment_references_get", "parameters": [ { @@ -15648,7 +16547,7 @@ }, "/agents/{agent_id}/evaluation-criteria/test-draft": { "post": { - "description": "Run an ephemeral evaluation against provided step output without persisting results.\n\nUse this to interactively test evaluation prompts and expectation\nconfigurations while editing criteria. The evaluation is a billed LLM\ncall; only its result goes unrecorded.", + "description": "Run an ephemeral evaluation against provided step output without persisting results.\n\nUse this to interactively test evaluation prompts and expectation\nconfigurations while editing criteria. The evaluation is a billed LLM\ncall; only its result goes unrecorded.\n\n``status`` is ``error`` when the evaluator returned no verdict. With\n``Seclai-Version: 2026-10-21`` or later, ``score`` and ``passed`` are then\n``null``; earlier versions return ``score`` 0.5 and ``passed`` false.", "operationId": "test_draft_evaluation_api_agents__agent_id__evaluation_criteria_test_draft_post", "parameters": [ { @@ -16308,7 +17207,7 @@ ] }, "post": { - "description": "Start an agent run.\n\nAn *agent* is an automated workflow that can monitor content from your sources, process it with AI, and trigger actions. This endpoint creates a new run and returns a `run_id` you can poll to retrieve status and output.\n\nWhen to use:\n- Use this endpoint for request/response style integrations where polling is acceptable.\n- Use `POST /agents/{agent_id}/runs/stream` if you need real-time progress via SSE.\n\nKey fields:\n- `input`: text input for agents with a `dynamic_input` trigger.\n- `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file's extracted text follows); only the two upload fields are mutually exclusive with each other.\n- `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming.\n- `metadata`: a JSON object that becomes available to agent steps for string substitution.\n\nAfter starting:\n- Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`.\n- Use `include_step_outputs=true` to include per-step outputs, timing, and credits.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", + "description": "Start an agent run.\n\nAn *agent* is an automated workflow that can monitor content from your sources, process it with AI, and trigger actions. This endpoint creates a new run and returns a `run_id` you can poll to retrieve status and output.\n\nWhen to use:\n- Use this endpoint for request/response style integrations where polling is acceptable.\n- Use `POST /agents/{agent_id}/runs/stream` if you need real-time progress via SSE.\n\nKey fields:\n- `input`: text input for agents with a `dynamic_input` trigger.\n- `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file follows under its heading); only the two upload fields are mutually exclusive with each other.\n- `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming.\n- `metadata`: a JSON object that becomes available to agent steps for string substitution.\n\nAfter starting:\n- Poll `GET /agents/runs/{run_id}` until `status` is `completed` or `failed`.\n- Use `include_step_outputs=true` to include per-step outputs, timing, and credits.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", "operationId": "run_agent_api_agents__agent_id__runs_post", "parameters": [ { @@ -16395,7 +17294,7 @@ }, "/agents/{agent_id}/runs/stream": { "post": { - "description": "Start a **priority** agent run and stream run events using Server-Sent Events (SSE).\n\nThis is the best option for interactive UIs where you want progress updates as the run executes.\n\nHow it works:\n- The first `init` event contains an `AgentRunResponse` snapshot, including the `run_id`.\n- Subsequent events are forwarded from the run event stream (status changes, step events, etc).\n- If the agent contains a `streaming_result` step, `stream_token` events deliver individual LLM tokens (with a `token` field) and a `stream_end` event signals completion.\n- The final `done` event contains the terminal snapshot (including `output` and `credits` when available).\n\nInput options (for `dynamic_input` triggers):\n- `input`: text input passed directly.\n- `input_upload_id` / `input_upload_ids`: reference one or more files uploaded via `POST /agents/{agent_id}/upload-input`. Combine either with `input` to send prompt text alongside the files; only the two upload fields are mutually exclusive with each other.\n\nClient guidance:\n- Keep the connection open and handle keepalive comments.\n- On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`.\n- `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a progress channel \u2014 render tokens live, but read the result from `done`. Check `done.status` first: the streamed text is already the run's output when the stream ends, so a run that FAILED its validation step still carries that raw text in `output`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", + "description": "Start a **priority** agent run and stream run events using Server-Sent Events (SSE).\n\nThis is the best option for interactive UIs where you want progress updates as the run executes.\n\nHow it works:\n- The first `init` event contains an `AgentRunResponse` snapshot, including the `run_id`.\n- Subsequent events are forwarded from the run event stream (status changes, step events, etc).\n- If the agent contains a `streaming_result` step, `stream_token` events deliver individual LLM tokens (with a `token` field) and a `stream_end` event signals completion.\n- With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`.\n- The final `done` event contains the terminal snapshot (including `output` and `credits` when available).\n\nInput options (for `dynamic_input` triggers):\n- `input`: text input passed directly.\n- `input_upload_id` / `input_upload_ids`: reference one or more files uploaded via `POST /agents/{agent_id}/upload-input`. Combine either with `input` to send prompt text alongside the files; only the two upload fields are mutually exclusive with each other.\n\nClient guidance:\n- Keep the connection open and handle keepalive comments.\n- On `timeout` or `error`, the payload includes `run_id` so clients can resume by polling `GET /agents/runs/{run_id}`.\n- `stream_token` events carry the model's raw output. When the agent pairs `streaming_result` with a sibling `extract_content`/`display_result` branch, that branch's `display_result` takes precedence over the stream, so the `done` snapshot's `output` is the validated payload and the tokens are a progress channel \u2014 render tokens live, but read the result from `done`. Check `done.status` first: the streamed text is already the run's output when the stream ends, so a run that FAILED its validation step still carries that raw text in `output`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", "operationId": "run_streaming_agent_api_agents__agent_id__runs_stream_post", "parameters": [ { @@ -16587,10 +17486,10 @@ ] } }, - "/agents/{agent_id}/triggers/{trigger_id}/email-config": { + "/agents/{agent_id}/triggers/{trigger_id}/accepted-attachments": { "put": { - "description": "Set the custom alias, sender allowlist, and inbound-handling flags (`ignore_auto_generated`, `require_sender_auth`, `queue_on_quota`) on an agent's EMAIL_RECEIVED trigger, and return its computed email address(es). Omitted fields are left unchanged.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.", - "operationId": "set_email_trigger_config_api_api_agents__agent_id__triggers__trigger_id__email_config_put", + "description": "Replace the input attachments a trigger accepts. A run's files are each assigned to one declared attachment before any step runs; steps reference one as ``{{agent.attachments.}}``. Rejected with HTTP 400 when the agent references an attachment the new declaration leaves out. `trigger_id` is the one `GET /agents/{agent_id}` returns.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.", + "operationId": "set_accepted_attachments_api_api_agents__agent_id__triggers__trigger_id__accepted_attachments_put", "parameters": [ { "in": "path", @@ -16621,7 +17520,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/routers__api__agents__SetEmailTriggerConfigRequest" + "$ref": "#/components/schemas/SetAcceptedAttachmentsRequest" } } }, @@ -16632,7 +17531,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EmailTriggerConfigResponse" + "$ref": "#/components/schemas/AcceptedAttachmentsResponse" } } }, @@ -16667,16 +17566,16 @@ } } }, - "summary": "Configure an EMAIL_RECEIVED trigger", + "summary": "Declare the input attachments a trigger accepts", "tags": [ "agents" ] } }, - "/agents/{agent_id}/upload-input": { - "post": { - "description": "Upload a file to use as input for a `dynamic_input` agent run.\n\nSupports the same file types as content source uploads: text, PDF, DOCX, audio, video, images, etc. Text and document files are processed synchronously; audio/video are submitted for asynchronous transcription.\n\n**Size limit:** 200 MB per file.\n\n**Supported extensions:** txt, html, md, csv, xml, json, pdf, msg, docx, doc, pptx, ppt, xlsx, xls, zip, epub, png, jpg, gif, bmp, tiff, webp, mp3, wav, m4a, flac, ogg, mp4, mov, avi.\n\nAfter uploading, poll `GET /agents/{agent_id}/input-uploads/{upload_id}` until `status` is `ready`, then pass `input_upload_id` to `POST /agents/{agent_id}/runs`.\n\n**Multi-modal routing:** non-text uploads (image, audio, video, PDF) are surfaced natively to multi-modal-capable prompt steps; text-only models fall back to the OCR / transcript text counterpart. Audio originals are preserved past transcription so audio-capable models (Gemini 2.5/3, GPT-5 audio) read them directly; the agent-input-binary janitor sweeps originals once they pass your account's agent-trace retention (the agent-traces source's retention period; free default 7 days).\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", - "operationId": "api_upload_agent_input_api_agents__agent_id__upload_input_post", + "/agents/{agent_id}/triggers/{trigger_id}/email-config": { + "put": { + "description": "Set the custom alias, sender allowlist, and inbound-handling flags (`ignore_auto_generated`, `require_sender_auth`, `queue_on_quota`, `run_on_attachment_mismatch`) on an agent's EMAIL_RECEIVED trigger, and return its computed email address(es). `trigger_id` is the one `GET /agents/{agent_id}` returns. Omitted fields are left unchanged.\n\nAuth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account.", + "operationId": "set_email_trigger_config_api_api_agents__agent_id__triggers__trigger_id__email_config_put", "parameters": [ { "in": "path", @@ -16687,6 +17586,15 @@ "type": "string" } }, + { + "in": "path", + "name": "trigger_id", + "required": true, + "schema": { + "title": "Trigger Id", + "type": "string" + } + }, { "$ref": "#/components/parameters/X-Account-Id" }, @@ -16694,11 +17602,88 @@ "$ref": "#/components/parameters/Seclai-Version" } ], - "responses": { - "202": { - "content": { - "application/json": { - "schema": { + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/routers__api__agents__SetEmailTriggerConfigRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailTriggerConfigResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Configure an EMAIL_RECEIVED trigger", + "tags": [ + "agents" + ] + } + }, + "/agents/{agent_id}/upload-input": { + "post": { + "description": "Upload a file to use as input for a `dynamic_input` agent run. Any other agent rejects the upload with HTTP 400.\n\n**Size limit:** 200 MB per file.\n\nFrom `Seclai-Version: 2026-10-16` a file of any type is accepted and is `ready` at once: pass `input_upload_id` to `POST /agents/{agent_id}/runs`. Each step receives the file itself when its model reads that type, and otherwise its text (OCR, extraction or transcript), made once for the steps that need it; a type nothing reads or converts is passed on as a file only. `input` carries a `# filename` heading per file.\n\nEarlier versions accept only these extensions: avi, bmp, csv, docx, epub, flac, gif, html, jpg, json, m4a, markdown, md, mov, mp3, mp4, msg, ogg, pdf, png, ppt, pptx, svg, tiff, txt, wav, webp, xls, xlsx, xml, zip. They write each file's text into `input`, so poll `GET /agents/{agent_id}/input-uploads/{upload_id}` until `status` is `ready` before running.\n\nThe agent-input-binary janitor sweeps originals once they pass your account's agent-trace retention (the agent-traces source's retention period; free default 7 days).\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account.", + "operationId": "api_upload_agent_input_api_agents__agent_id__upload_input_post", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "title": "Agent Id", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UploadAgentInputApiResponse" } } @@ -18969,9 +19954,326 @@ "name": "limit", "required": false, "schema": { - "default": 50, - "maximum": 200, - "minimum": 1, + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/CloudDriveRejectionResponseModel" + }, + "title": "Response List Cloud Drive Rejections Api Api Cloud Drives Connection Id Rejections Get", + "type": "array" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "List files this connection did not process", + "tags": [ + "cloud_drives" + ] + } + }, + "/contents/{source_connection_content_version}": { + "delete": { + "description": "Delete a content item (a `SourceConnectionContentVersion`).\n\nUse this to remove an uploaded or indexed item from your account. Deleting content can affect agents and knowledge base workflows that reference this item.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only delete content belonging to your account.\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.", + "operationId": "delete_content_api_contents__source_connection_content_version__delete", + "parameters": [ + { + "in": "path", + "name": "source_connection_content_version", + "required": true, + "schema": { + "title": "Source Connection Content Version", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "403": { + "description": "The key's user is a member of the account but not an owner or administrator (`error.code` is `permission_denied`)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Delete content", + "tags": [ + "contents" + ] + }, + "get": { + "description": "Get detailed information about a specific content item (a `SourceConnectionContentVersion`).\n\nThis is useful when you want to:\n- Inspect the extracted text for debugging or review.\n- Display content details in a UI.\n\nText range:\n- `start` and `end` control the character range returned in `text_content` so clients can page through large documents.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access content belonging to your account.", + "operationId": "get_content_detail_api_contents__source_connection_content_version__get", + "parameters": [ + { + "in": "path", + "name": "source_connection_content_version", + "required": true, + "schema": { + "title": "Source Connection Content Version", + "type": "string" + } + }, + { + "in": "query", + "name": "start", + "required": false, + "schema": { + "default": 0, + "title": "Start", + "type": "integer" + } + }, + { + "in": "query", + "name": "end", + "required": false, + "schema": { + "default": 5000, + "title": "End", + "type": "integer" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/routers__api__contents__ContentDetailResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Get content details", + "tags": [ + "contents" + ] + }, + "put": { + "description": "Replace a content version using a small inline text payload.\n\n**Maximum payload size:** 8192 bytes (UTF-8).\n\n**Supported content types:**\n- `application/json`\n- `application/xml`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- Use this endpoint for small text payloads; larger files should use `/upload`.\n- `title` is merged into `metadata.title` when not already present.\n- The replacement is indexed in the background. This `SourceConnectionContentVersion` ID keeps working, and reads return the previous content until indexing finishes; poll `list_source_content_status` to follow it. The returned `content_version_id` is the new version.", + "operationId": "replace_content_with_inline_text_api_contents__source_connection_content_version__put", + "parameters": [ + { + "in": "path", + "name": "source_connection_content_version", + "required": true, + "schema": { + "title": "Source Connection Content Version", + "type": "string" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InlineTextReplaceRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/routers__api__contents__FileUploadResponse" + } + } + }, + "description": "Successful Response" + }, + "403": { + "description": "The key's user is not an owner or administrator of the account (`error.code` is `permission_denied`), or the account is suspended (`suspended_account`)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "Replace a content version with inline text", + "tags": [ + "contents" + ] + } + }, + "/contents/{source_connection_content_version}/attachments": { + "get": { + "description": "List the files attached to a content item, with pagination.\n\nAn agent's `write_content_attachment` step attaches a file, and an email content source attaches the files sent with a message. An RSS source attaches the kinds of feed file chosen in its `feed_attachments`. The images and video in a web page's main content are attached on a source with media indexing on. The images inside a PDF, DOCX, PPTX or XLSX item or attachment are attached too, on a source that indexes document images. Each entry says whether the file is indexed for search and, when indexing failed, why.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account.", + "operationId": "list_content_attachments_api_contents__source_connection_content_version__attachments_get", + "parameters": [ + { + "in": "path", + "name": "source_connection_content_version", + "required": true, + "schema": { + "title": "Source Connection Content Version", + "type": "string" + } + }, + { + "in": "query", + "name": "page", + "required": false, + "schema": { + "default": 1, + "title": "Page", + "type": "integer" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 20, "title": "Limit", "type": "integer" } @@ -18988,11 +20290,7 @@ "content": { "application/json": { "schema": { - "items": { - "$ref": "#/components/schemas/CloudDriveRejectionResponseModel" - }, - "title": "Response List Cloud Drive Rejections Api Api Cloud Drives Connection Id Rejections Get", - "type": "array" + "$ref": "#/components/schemas/routers__api__contents__ContentAttachmentsListResponse" } } }, @@ -19027,26 +20325,59 @@ } } }, - "summary": "List files this connection did not process", + "summary": "List content attachments", "tags": [ - "cloud_drives" + "contents" ] } }, - "/contents/{source_connection_content_version}": { - "delete": { - "description": "Delete a content item (a `SourceConnectionContentVersion`).\n\nUse this to remove an uploaded or indexed item from your account. Deleting content can affect agents and knowledge base workflows that reference this item.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only delete content belonging to your account.\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.", - "operationId": "delete_content_api_contents__source_connection_content_version__delete", + "/contents/{source_connection_content_version}/attachments/{attachment_id}": { + "get": { + "description": "Get one file attached to a content item: its indexing status and reason, its metadata, and the text it is indexed by.\n\n`attachment_id` is the `id` of an entry in the item's attachment list. Use `start` and `end` to page through long text. A file that was not indexed has no text.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account.", + "operationId": "get_content_attachment_api_contents__source_connection_content_version__attachments__attachment_id__get", "parameters": [ { "in": "path", "name": "source_connection_content_version", "required": true, "schema": { + "format": "uuid", "title": "Source Connection Content Version", "type": "string" } }, + { + "in": "path", + "name": "attachment_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Attachment Id", + "type": "string" + } + }, + { + "in": "query", + "name": "start", + "required": false, + "schema": { + "default": 0, + "minimum": 0, + "title": "Start", + "type": "integer" + } + }, + { + "in": "query", + "name": "end", + "required": false, + "schema": { + "default": 5000, + "minimum": 0, + "title": "End", + "type": "integer" + } + }, { "$ref": "#/components/parameters/X-Account-Id" }, @@ -19055,11 +20386,18 @@ } ], "responses": { - "204": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/routers__api__contents__ContentAttachmentDetailResponse" + } + } + }, "description": "Successful Response" }, - "403": { - "description": "The key's user is a member of the account but not an owner or administrator (`error.code` is `permission_denied`)." + "402": { + "description": "The account has no credits left (`error.code` is `insufficient_credits`)." }, "422": { "content": { @@ -19090,41 +20428,57 @@ } } }, - "summary": "Delete content", + "summary": "Get a content attachment", "tags": [ "contents" ] - }, + } + }, + "/contents/{source_connection_content_version}/attachments/{attachment_id}/embeddings": { "get": { - "description": "Get detailed information about a specific content item (a `SourceConnectionContentVersion`).\n\nThis is useful when you want to:\n- Inspect the extracted text for debugging or review.\n- Display content details in a UI.\n\nText range:\n- `start` and `end` control the character range returned in `text_content` so clients can page through large documents.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access content belonging to your account.", - "operationId": "get_content_detail_api_contents__source_connection_content_version__get", + "description": "List the embeddings (chunk vectors) an attached file is indexed by, with pagination. The list is empty for a file that has no completed index.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account.", + "operationId": "list_content_attachment_embeddings_api_contents__source_connection_content_version__attachments__attachment_id__embeddings_get", "parameters": [ { "in": "path", "name": "source_connection_content_version", "required": true, "schema": { + "format": "uuid", "title": "Source Connection Content Version", "type": "string" } }, + { + "in": "path", + "name": "attachment_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Attachment Id", + "type": "string" + } + }, { "in": "query", - "name": "start", + "name": "page", "required": false, "schema": { - "default": 0, - "title": "Start", + "default": 1, + "minimum": 1, + "title": "Page", "type": "integer" } }, { "in": "query", - "name": "end", + "name": "limit", "required": false, "schema": { - "default": 5000, - "title": "End", + "default": 20, + "maximum": 100, + "minimum": 1, + "title": "Limit", "type": "integer" } }, @@ -19140,12 +20494,15 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/routers__api__contents__ContentDetailResponse" + "$ref": "#/components/schemas/routers__api__contents__ContentEmbeddingsListResponse" } } }, "description": "Successful Response" }, + "402": { + "description": "The account has no credits left (`error.code` is `insufficient_credits`)." + }, "422": { "content": { "application/json": { @@ -19175,24 +20532,37 @@ } } }, - "summary": "Get content details", + "summary": "List a content attachment's embeddings", "tags": [ "contents" ] - }, - "put": { - "description": "Replace a content version using a small inline text payload.\n\n**Maximum payload size:** 8192 bytes (UTF-8).\n\n**Supported content types:**\n- `application/json`\n- `application/xml`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- Use this endpoint for small text payloads; larger files should use `/upload`.\n- `title` is merged into `metadata.title` when not already present.\n- The replacement is indexed in the background. This `SourceConnectionContentVersion` ID keeps working, and reads return the previous content until indexing finishes; poll `list_source_content_status` to follow it. The returned `content_version_id` is the new version.", - "operationId": "replace_content_with_inline_text_api_contents__source_connection_content_version__put", + } + }, + "/contents/{source_connection_content_version}/attachments/{attachment_id}/file": { + "get": { + "description": "Download an attached file's bytes.\n\nImages, audio, video, PDF and plain text are served with their own type; an SVG that cannot be sanitized, and anything else, is served as `application/octet-stream`.\n\nAnswers 403 when the file is withheld: a governance policy blocked or redacted it, or it arrived from outside and is still being indexed. The attachment's `file_withheld` field says which before you ask.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account.", + "operationId": "get_content_attachment_file_api_contents__source_connection_content_version__attachments__attachment_id__file_get", "parameters": [ { "in": "path", "name": "source_connection_content_version", "required": true, "schema": { + "format": "uuid", "title": "Source Connection Content Version", "type": "string" } }, + { + "in": "path", + "name": "attachment_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Attachment Id", + "type": "string" + } + }, { "$ref": "#/components/parameters/X-Account-Id" }, @@ -19200,29 +20570,53 @@ "$ref": "#/components/parameters/Seclai-Version" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/InlineTextReplaceRequest" - } - } - }, - "required": true - }, "responses": { "200": { "content": { - "application/json": { + "application/octet-stream": { "schema": { - "$ref": "#/components/schemas/routers__api__contents__FileUploadResponse" + "format": "binary", + "type": "string" + } + }, + "application/pdf": { + "schema": { + "format": "binary", + "type": "string" + } + }, + "audio/*": { + "schema": { + "format": "binary", + "type": "string" + } + }, + "image/*": { + "schema": { + "format": "binary", + "type": "string" + } + }, + "text/plain": { + "schema": { + "format": "binary", + "type": "string" + } + }, + "video/*": { + "schema": { + "format": "binary", + "type": "string" } } }, - "description": "Successful Response" + "description": "The file's bytes." + }, + "402": { + "description": "The account has no credits left (`error.code` is `insufficient_credits`)." }, "403": { - "description": "The key's user is not an owner or administrator of the account (`error.code` is `permission_denied`), or the account is suspended (`suspended_account`)." + "description": "The file is withheld; `error.code` says why." }, "422": { "content": { @@ -19253,7 +20647,7 @@ } } }, - "summary": "Replace a content version with inline text", + "summary": "Download a content attachment", "tags": [ "contents" ] @@ -19348,7 +20742,7 @@ }, "/contents/{source_connection_content_version}/upload": { "post": { - "description": "Upload a new file and replace the content backing an existing `SourceConnectionContentVersion`.\n\nThis behaves like a source file upload, but it targets an existing content version ID. This is useful when you want to correct or update an uploaded document while keeping references stable.\n\n**Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored).\n\n**Supported MIME types:**\n- `application/epub+zip`\n- `application/json`\n- `application/pdf`\n- `application/vnd.ms-excel`\n- `application/vnd.ms-outlook`\n- `application/vnd.ms-powerpoint`\n- `application/vnd.openxmlformats-officedocument.presentationml.presentation`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `application/xml`\n- `application/zip`\n- `audio/flac`\n- `audio/mp4`\n- `audio/mpeg`\n- `audio/ogg`\n- `audio/wav`\n- `image/bmp`\n- `image/gif`\n- `image/jpeg`\n- `image/png`\n- `image/svg+xml`\n- `image/tiff`\n- `image/webp`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n- `video/mp4`\n- `video/quicktime`\n- `video/x-msvideo`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- The replacement is indexed in the background. This `SourceConnectionContentVersion` ID keeps working, and reads return the previous content until indexing finishes; poll `list_source_content_status` to follow it. The returned `content_version_id` is the new version.\n- If the uploaded file's content type is `application/octet-stream`, the server attempts to infer the type from the file extension.\n- Use `metadata` to attach an arbitrary JSON object of metadata (for example `metadata={\"category\":\"docs\"}`).\n- `title` is a convenience field and is merged into the metadata as `metadata.title` (it does not override an existing `metadata.title`).\n- For backwards compatibility, you can also pass form fields named `metadata_` (for example `metadata_author=...`). These override keys from `metadata`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only replace content belonging to your account.", + "description": "Upload a new file and replace the content backing an existing `SourceConnectionContentVersion`.\n\nThis behaves like a source file upload, but it targets an existing content version ID. This is useful when you want to correct or update an uploaded document while keeping references stable.\n\n**Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored).\n\n**Supported MIME types:**\n- `application/atom+xml`\n- `application/epub+zip`\n- `application/json`\n- `application/pdf`\n- `application/rss+xml`\n- `application/rtf`\n- `application/vnd.ms-excel`\n- `application/vnd.ms-outlook`\n- `application/vnd.ms-powerpoint`\n- `application/vnd.openxmlformats-officedocument.presentationml.presentation`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `application/x-ipynb+json`\n- `application/xhtml+xml`\n- `application/xml`\n- `application/zip`\n- `audio/aac`\n- `audio/amr`\n- `audio/flac`\n- `audio/mp4`\n- `audio/mpeg`\n- `audio/ogg`\n- `audio/opus`\n- `audio/wav`\n- `audio/webm`\n- `image/bmp`\n- `image/gif`\n- `image/jpeg`\n- `image/png`\n- `image/svg+xml`\n- `image/tiff`\n- `image/webp`\n- `message/rfc822`\n- `text/calendar`\n- `text/csv`\n- `text/html`\n- `text/javascript`\n- `text/markdown`\n- `text/plain`\n- `text/tab-separated-values`\n- `text/vcard`\n- `text/vtt`\n- `text/x-c`\n- `text/x-c++`\n- `text/x-csharp`\n- `text/x-go`\n- `text/x-ini`\n- `text/x-java`\n- `text/x-log`\n- `text/x-markdown`\n- `text/x-php`\n- `text/x-python`\n- `text/x-ruby`\n- `text/x-rust`\n- `text/x-shellscript`\n- `text/x-sql`\n- `text/x-subrip`\n- `text/x-tex`\n- `text/x-toml`\n- `text/x-typescript`\n- `text/xml`\n- `text/yaml`\n- `video/3gpp`\n- `video/mp2t`\n- `video/mp4`\n- `video/mpeg`\n- `video/quicktime`\n- `video/webm`\n- `video/x-matroska`\n- `video/x-msvideo`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- The replacement is indexed in the background. This `SourceConnectionContentVersion` ID keeps working, and reads return the previous content until indexing finishes; poll `list_source_content_status` to follow it. The returned `content_version_id` is the new version.\n- If the uploaded file's content type is `application/octet-stream`, the server attempts to infer the type from the file extension.\n- Use `metadata` to attach an arbitrary JSON object of metadata (for example `metadata={\"category\":\"docs\"}`).\n- `title` is a convenience field and is merged into the metadata as `metadata.title` (it does not override an existing `metadata.title`).\n- For backwards compatibility, you can also pass form fields named `metadata_` (for example `metadata_author=...`). These override keys from `metadata`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only replace content belonging to your account.", "operationId": "upload_file_to_content_api_contents__source_connection_content_version__upload_post", "parameters": [ { @@ -22312,7 +23706,7 @@ }, "/models/embedders": { "get": { - "description": "List the embedding models a source can be created with.\n\nEach entry carries the `model_type` to pass as `embedding_model` when creating a source, the `dimensions` it supports, and \u2014 most importantly for multi-modal indexing \u2014 `supported_input_media`: the modalities that embedder can actually index. A source only honours a `media_types` entry its embedder lists here; unsupported kinds are dropped at save time with an `embedder_warning`, so check this before choosing an embedder for a knowledge base of images or video.\n\nText-only embedders report `supported_input_media` as null. Pricing is reported as `credits` (per ~1,000 English words of text) plus `per_modality_rates` for the non-text modalities a multi-modal embedder bills differently.\n\nAn embedder whose credit rate has not been published yet is omitted, so you are never offered one that cannot be billed.\n\nOptional query parameters:\n- `supports_input_media`: keep only embedders that can index this modality (`text`/`image`/`video`/`audio` or a full MIME)\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. The catalog is global reference data, identical for every account.", + "description": "List the embedding models a source can be created with.\n\nEach entry carries the `model_type` to pass as `embedding_model` when creating a source, the `dimensions` it supports, and \u2014 most importantly for multi-modal indexing \u2014 `supported_input_media`: the modalities that embedder can actually index. A source only honours a `media_types` entry its embedder lists here; a kind it does not list is stored and not indexed, so check this before choosing an embedder for a knowledge base of images or video.\n\nText-only embedders report `supported_input_media` as null. Pricing is reported as `credits` (per ~1,000 English words of text) plus `per_modality_rates` for the non-text modalities a multi-modal embedder bills differently.\n\nAn embedder whose credit rate has not been published yet is omitted, so you are never offered one that cannot be billed.\n\nOptional query parameters:\n- `supports_input_media`: keep only embedders that can index this modality (`text`/`image`/`video`/`audio` or a full MIME)\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. The catalog is global reference data, identical for every account.", "operationId": "list_embedding_models_api_models_embedders_get", "parameters": [ { @@ -22766,7 +24160,7 @@ }, "/models/playground/experiments/{experiment_id}/cancel": { "post": { - "description": "Cancel a running or pending model playground experiment.\n\nSignals running model calls to abort and marks the experiment as canceled.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. The experiment must belong to the caller's account and, when the credential is bound to a user, to that user; otherwise 404.", + "description": "Cancel a running or pending model playground experiment.\n\nMarks the experiment as canceled. An experiment that has not started never runs. One that is running starts no further model calls, and records each model it did not call with the error `Canceled`. A model call or evaluation already in progress is not interrupted by the cancel: it continues and is billed, and its result is recorded on the canceled experiment. Canceling may therefore not shorten the run or reduce its cost.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. The experiment must belong to the caller's account and, when the credential is bound to a user, to that user; otherwise 404.", "operationId": "cancel_experiment_endpoint_api_models_playground_experiments__experiment_id__cancel_post", "parameters": [ { @@ -24818,7 +26212,7 @@ ] }, "post": { - "description": "Create a new content source.\n\nSource types: `rss`, `website`, `custom_index`.\n\nFor RSS and website sources, provide the URL. For custom index sources, the URL is created automatically.\n\nFor custom_index sources, you can optionally specify an `index_mode`: `fast_and_cheap` (default), `balanced`, `slow_and_thorough`, or `custom`. The legacy `file_uploads` source type is accepted as an alias for `custom_index` with `index_mode=fast_and_cheap`.", + "description": "Create a new content source.\n\nSource types: `rss_feed`, `website`, `custom_index`, `cloud_drive`, `email`.\n\nFor RSS and website sources, provide the URL. For custom index sources, the URL is created automatically.\n\nAn `email` source takes no URL and requires `email_allowed_senders`; the response's `email_address` is where to send mail.\n\nA `cloud_drive` source takes no URL and requires `cloud_drive_connection_id`, the id of a drive connected in the app (`GET /cloud-drives` lists them).\n\nFor custom_index sources, you can optionally specify an `index_mode`: `fast_and_cheap` (default), `balanced`, `slow_and_thorough`, or `custom`. The legacy `file_uploads` source type is accepted as an alias for `custom_index` with `index_mode=fast_and_cheap`.", "operationId": "create_source_api_sources_post", "parameters": [ { @@ -25014,7 +26408,7 @@ ] }, "post": { - "description": "Upload a small text payload to a content source (no multipart/form-data required).\n\n**Maximum payload size:** 8192 bytes (UTF-8).\n\n**Supported content types:**\n- `application/json`\n- `application/xml`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- Use this endpoint for small text payloads; larger files should use `/upload`.\n- `title` is merged into `metadata.title` when not already present.\n\nTracking indexing progress:\n- **Which id you get back depends on `status`, and they are not interchangeable:**\n - `uploaded` \u2014 a new item. `content_version_id` is set and `source_connection_content_version_id` is `null`. Indexing continues in the background after this call returns.\n - `duplicate` \u2014 this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll.\n- For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=\u2026&content_version_id=\u2026` for a whole batch, to follow each item through to `completed` or `failed`.\n- On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes.", + "description": "Upload a small text payload to a content source (no multipart/form-data required).\n\n**Maximum payload size:** 8192 bytes (UTF-8).\n\n**Supported content types:**\n- `application/json`\n- `application/xml`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- Use this endpoint for small text payloads; larger files should use `/upload`.\n- `title` is merged into `metadata.title` when not already present.\n\nTracking indexing progress:\n- **Which id you get back depends on `status`, and they are not interchangeable:**\n - `uploaded` \u2014 a new item. `content_version_id` is set and `source_connection_content_version_id` is `null`. Indexing continues in the background after this call returns.\n - `duplicate` \u2014 this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll.\n- For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=\u2026&content_version_id=\u2026` for a whole batch, to follow each item through to `completed` or `failed`.\n- On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes.\n- An item that reports `held_for_review: true` was blocked by an Enforce governance policy. It is not in the source and its id stays `null` unless a reviewer releases it, so stop polling.", "operationId": "upload_inline_text_to_source_api_sources__source_connection_id__post", "parameters": [ { @@ -25171,7 +26565,7 @@ }, "/sources/{source_connection_id}/contents": { "get": { - "description": "List every content item this source has attempted to index, with the status of each.\n\nUnlike the source's `content_count`, which only counts finished items, this listing includes items that are still processing and items that failed \u2014 so a bulk upload can report per-item progress and point at the specific items that did not make it.\n\nCorrelating with an upload:\n- Each item is keyed by `content_version_id`, which is what the upload endpoints return. Pass those ids as repeated `content_version_id` query parameters to poll exactly the items you uploaded.\n- `source_connection_content_version_id` is `null` until an item finishes indexing; once set, it is the id `GET /contents/{id}` takes.\n- `content_status` reaches `completed` on success and `failed` on error, with the reason in `error`. The intermediate values are `pending`, `fetching`, `transcribing`, `scanning`, and `indexing`.\n\nParameters:\n- Pagination: `page` and `limit`.\n- Sorting: `sort` (created_at/title/status) and `order` (asc/desc). `created_at` sorts on when the item was uploaded or pulled.\n- Filtering: `status` and repeatable `content_version_id`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only list content for sources belonging to your account.", + "description": "List every content item this source has attempted to index, with the status of each.\n\nUnlike the source's `content_count`, which only counts finished items, this listing includes items that are still processing and items that failed \u2014 so a bulk upload can report per-item progress and point at the specific items that did not make it.\n\nCorrelating with an upload:\n- Each item is keyed by `content_version_id`, which is what the upload endpoints return. Pass those ids as repeated `content_version_id` query parameters to poll exactly the items you uploaded.\n- `source_connection_content_version_id` is `null` until an item finishes indexing; once set, it is the id `GET /contents/{id}` takes.\n- `content_status` reaches `completed` on success and `failed` on error, with the reason in `error`. The intermediate values are `pending`, `fetching`, `transcribing`, `scanning`, and `indexing`.\n- An item an Enforce governance policy blocked at import is held for review: `held_for_review` is `true` and `source_connection_content_version_id` stays `null` until a reviewer releases it. With `Seclai-Version: 2026-10-05` or later it reports `completed`; earlier versions report it as `failed` with the hold as the `error`. The `status` filter matches the item under `completed` on every version.\n\nParameters:\n- Pagination: `page` and `limit`.\n- Sorting: `sort` (created_at/title/status) and `order` (asc/desc). `created_at` sorts on when the item was uploaded or pulled.\n- Filtering: `status` and repeatable `content_version_id`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only list content for sources belonging to your account.", "operationId": "list_source_contents_api_sources__source_connection_id__contents_get", "parameters": [ { @@ -25331,7 +26725,7 @@ }, "/sources/{source_connection_id}/contents/{content_version_id}": { "get": { - "description": "Get the indexing status of a single content item, addressed by the `content_version_id` the upload endpoints return.\n\nUse this to follow one uploaded file through indexing. To follow many at once, use `GET /sources/{id}/contents` with repeated `content_version_id` parameters instead of polling this endpoint per item.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access content belonging to your account.", + "description": "Get the indexing status of a single content item, addressed by the `content_version_id` the upload endpoints return.\n\nUse this to follow one uploaded file through indexing. To follow many at once, use `GET /sources/{id}/contents` with repeated `content_version_id` parameters instead of polling this endpoint per item.\n\nAn item held for review by an Enforce governance policy reports `held_for_review: true`. With `Seclai-Version: 2026-10-05` or later its `content_status` is `completed`; earlier versions report `failed` with the hold as the `error`.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token. You can only access content belonging to your account.", "operationId": "get_source_content_status_endpoint_api_sources__source_connection_id__contents__content_version_id__get", "parameters": [ { @@ -25407,6 +26801,101 @@ ] } }, + "/sources/{source_connection_id}/email-rejections": { + "get": { + "description": "List mail that an email content source refused, newest first. Each entry says who sent the message and why it was refused, never its subject or body. A message refused as `unsafe_content` also has a prompt-scan record, which keeps the scanned text.\n\nTo accept a refused sender, add its `from_address` or that address's domain to the source's `email_allowed_senders`. That only helps when `authenticated` is true. A `repeat_*` reason marks a message the source received before; allowing its sender does not store it.\n\nRequires an account owner or administrator: a key or token bound to another member gets 403. Returns 404 for a source that is not an email source.", + "operationId": "list_email_source_rejections_api_api_sources__source_connection_id__email_rejections_get", + "parameters": [ + { + "in": "path", + "name": "source_connection_id", + "required": true, + "schema": { + "format": "uuid", + "title": "Source Connection Id", + "type": "string" + } + }, + { + "description": "Page number.", + "in": "query", + "name": "page", + "required": false, + "schema": { + "default": 1, + "description": "Page number.", + "minimum": 1, + "title": "Page", + "type": "integer" + } + }, + { + "description": "Items per page.", + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 20, + "description": "Items per page.", + "maximum": 100, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "$ref": "#/components/parameters/X-Account-Id" + }, + { + "$ref": "#/components/parameters/Seclai-Version" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EmailSourceRejectionListResponse" + } + } + }, + "description": "Successful Response" + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceUnavailableError" + } + } + }, + "description": "A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator.", + "headers": { + "Retry-After": { + "description": "Seconds to wait before retrying. Sent only with `database_unavailable`.", + "schema": { + "type": "integer" + } + } + } + } + }, + "summary": "List mail an email source refused", + "tags": [ + "sources" + ] + } + }, "/sources/{source_connection_id}/embedding-migration": { "get": { "description": "Get the latest embedding migration status for a custom-index source.\n\nReturns `null` when no migration has ever been started for this source.", @@ -26187,7 +27676,7 @@ }, "/sources/{source_connection_id}/upload": { "post": { - "description": "Upload a file to a content source.\n\n**Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored).\n\n**Supported MIME types:**\n- `application/epub+zip`\n- `application/json`\n- `application/pdf`\n- `application/vnd.ms-excel`\n- `application/vnd.ms-outlook`\n- `application/vnd.ms-powerpoint`\n- `application/vnd.openxmlformats-officedocument.presentationml.presentation`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `application/xml`\n- `application/zip`\n- `audio/flac`\n- `audio/mp4`\n- `audio/mpeg`\n- `audio/ogg`\n- `audio/wav`\n- `image/bmp`\n- `image/gif`\n- `image/jpeg`\n- `image/png`\n- `image/svg+xml`\n- `image/tiff`\n- `image/webp`\n- `text/csv`\n- `text/html`\n- `text/markdown`\n- `text/plain`\n- `text/x-markdown`\n- `text/xml`\n- `video/mp4`\n- `video/quicktime`\n- `video/x-msvideo`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- If the uploaded file's content type is `application/octet-stream`, the server attempts to infer the type from the file extension.\n- Use `metadata` to attach an arbitrary JSON object of metadata (for example `metadata={\"author\":\"Ada\",\"category\":\"docs\"}`).\n- `title` is a convenience field and is merged into the metadata as `metadata.title` (it does not override an existing `metadata.title`).\n- For backwards compatibility, you can also pass form fields named `metadata_` (for example `metadata_author=...`). These override keys from `metadata`.\n\nResponse:\n- `status` is `uploaded` for a new upload, or `duplicate` when the same file already exists for this source.\n\nTracking indexing progress:\n- **Which id you get back depends on `status`, and they are not interchangeable:**\n - `uploaded` \u2014 a new item. `content_version_id` is set and `source_connection_content_version_id` is `null`. Indexing continues in the background after this call returns.\n - `duplicate` \u2014 this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll.\n- For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=\u2026&content_version_id=\u2026` for a whole batch, to follow each item through to `completed` or `failed`.\n- On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes.", + "description": "Upload a file to a content source.\n\n**Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored).\n\n**Supported MIME types:**\n- `application/atom+xml`\n- `application/epub+zip`\n- `application/json`\n- `application/pdf`\n- `application/rss+xml`\n- `application/rtf`\n- `application/vnd.ms-excel`\n- `application/vnd.ms-outlook`\n- `application/vnd.ms-powerpoint`\n- `application/vnd.openxmlformats-officedocument.presentationml.presentation`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `application/x-ipynb+json`\n- `application/xhtml+xml`\n- `application/xml`\n- `application/zip`\n- `audio/aac`\n- `audio/amr`\n- `audio/flac`\n- `audio/mp4`\n- `audio/mpeg`\n- `audio/ogg`\n- `audio/opus`\n- `audio/wav`\n- `audio/webm`\n- `image/bmp`\n- `image/gif`\n- `image/jpeg`\n- `image/png`\n- `image/svg+xml`\n- `image/tiff`\n- `image/webp`\n- `message/rfc822`\n- `text/calendar`\n- `text/csv`\n- `text/html`\n- `text/javascript`\n- `text/markdown`\n- `text/plain`\n- `text/tab-separated-values`\n- `text/vcard`\n- `text/vtt`\n- `text/x-c`\n- `text/x-c++`\n- `text/x-csharp`\n- `text/x-go`\n- `text/x-ini`\n- `text/x-java`\n- `text/x-log`\n- `text/x-markdown`\n- `text/x-php`\n- `text/x-python`\n- `text/x-ruby`\n- `text/x-rust`\n- `text/x-shellscript`\n- `text/x-sql`\n- `text/x-subrip`\n- `text/x-tex`\n- `text/x-toml`\n- `text/x-typescript`\n- `text/xml`\n- `text/yaml`\n- `video/3gpp`\n- `video/mp2t`\n- `video/mp4`\n- `video/mpeg`\n- `video/quicktime`\n- `video/webm`\n- `video/x-matroska`\n- `video/x-msvideo`\n\nNotes:\n- A key bound to a user must belong to an owner or administrator of the account; a viewer's key is refused with 403 `permission_denied`. Account-scoped keys carry no user and are unaffected.\n- If the uploaded file's content type is `application/octet-stream`, the server attempts to infer the type from the file extension.\n- Use `metadata` to attach an arbitrary JSON object of metadata (for example `metadata={\"author\":\"Ada\",\"category\":\"docs\"}`).\n- `title` is a convenience field and is merged into the metadata as `metadata.title` (it does not override an existing `metadata.title`).\n- For backwards compatibility, you can also pass form fields named `metadata_` (for example `metadata_author=...`). These override keys from `metadata`.\n\nResponse:\n- `status` is `uploaded` for a new upload, or `duplicate` when the same file already exists for this source.\n\nTracking indexing progress:\n- **Which id you get back depends on `status`, and they are not interchangeable:**\n - `uploaded` \u2014 a new item. `content_version_id` is set and `source_connection_content_version_id` is `null`. Indexing continues in the background after this call returns.\n - `duplicate` \u2014 this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll.\n- For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=\u2026&content_version_id=\u2026` for a whole batch, to follow each item through to `completed` or `failed`.\n- On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes.\n- An item that reports `held_for_review: true` was blocked by an Enforce governance policy. It is not in the source and its id stays `null` unless a reviewer releases it, so stop polling.", "operationId": "upload_file_to_source_api_sources__source_connection_id__upload_post", "parameters": [ { @@ -26267,7 +27756,7 @@ }, "/v2/agent-runs/{run_id}/attachments/{attachment_id}": { "get": { - "description": "Streams the bytes of an attachment emitted by a step in the given agent run. ``attachment_id`` is the ``id`` of an entry in the run's or a step's ``attachments``, or the URL-safe-base64-encoded storage key, which webhook and email links carry.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token.\n- The calling account must own ``run_id``; lookup failures (missing run, cross-account run, soft-deleted agent, a run whose trace was purged, a file not in the run) all collapse to a single 404 to prevent cross-tenant existence enumeration.\n\nMIME handling:\n- Inline-safe MIMEs (image/*, audio/*, video/*, application/pdf, text/plain, application/vnd.seclai.manifest+json) are served with their declared type.\n- Everything else is served as ``application/octet-stream`` with an attachment disposition to prevent stored-XSS.", + "description": "Streams the bytes of a file of the given agent run: one a step emitted, or one the run started with. ``attachment_id`` is the ``id`` of an entry in the run's or a step's ``attachments``, or the URL-safe-base64-encoded storage key, which webhook and email links carry.\n\nAuth & scoping:\n- Requires `X-API-Key` header or OAuth Bearer token.\n- The calling account must own ``run_id``; lookup failures (missing run, cross-account run, soft-deleted agent, a run whose trace was purged, a file not in the run) all collapse to a single 404 to prevent cross-tenant existence enumeration.\n\nMIME handling:\n- Inline-safe MIMEs (image/*, audio/*, video/*, application/pdf, text/plain, application/vnd.seclai.manifest+json) are served with their declared type.\n- Everything else is served as ``application/octet-stream`` with an attachment disposition to prevent stored-XSS.", "operationId": "serve_agent_run_attachment_api_v2_agent_runs__run_id__attachments__attachment_id__get", "parameters": [ { @@ -26528,8 +28017,14 @@ "2026-08-21", "2026-09-28", "2026-09-30", - "2026-10-03" + "2026-10-03", + "2026-10-05", + "2026-10-13", + "2026-10-16", + "2026-10-18", + "2026-10-19", + "2026-10-21" ], - "latest": "2026-10-03" + "latest": "2026-10-21" } } diff --git a/src/client.ts b/src/client.ts index b95b11c..038541c 100644 --- a/src/client.ts +++ b/src/client.ts @@ -23,6 +23,11 @@ import type { AgentRunEvent, AddEmailDomainInput, AgentAttachmentRefsApiResponse, + AcceptedAttachmentsResponse, + SetAcceptedAttachmentsInput, + ContentAttachmentsListResponse, + ContentAttachmentDetailResponse, + EmailSourceRejectionListResponse, AgentCallerApiResponse, AgentDefinitionImportErrorResponse, AgentDefinitionResponse, @@ -739,7 +744,7 @@ export class Seclai { query?: Record; json?: unknown; headers?: Record; - signal?: AbortSignal; + signal?: AbortSignal | undefined; } ): Promise { const url = buildURL(this.baseUrl, path, opts?.query); @@ -1154,19 +1159,23 @@ export class Seclai { * Run an agent in streaming mode (SSE) and wait for the final result. * * Consumes the entire SSE stream and returns only the terminal `done` payload. - * For real-time event access, use {@link runStreamingAgent} instead. + * For real-time event access, use {@link runStreamingAgent} instead. The body + * takes no `include_reasoning`, and one passed anyway is not sent: this method + * returns no `stream_reasoning` events. * * @param agentId - Agent identifier. - * @param body - Streaming run request payload. + * @param body - Streaming run request payload, without `include_reasoning`. * @param opts - Timeout and abort signal options. * @returns Final agent run payload from the `done` event. * @throws {@link SeclaiStreamingError} If the stream ends before a `done` event. */ async runStreamingAgentAndWait( agentId: string, - body: AgentRunStreamRequest, + body: Omit, opts?: { timeoutMs?: number; signal?: AbortSignal }, ): Promise { + // Not sent even from untyped callers: the reasoning events are discarded here. + const { include_reasoning: _ignored, ...runBody } = body as AgentRunStreamRequest; const url = buildURL(this.baseUrl, `/agents/${agentId}/runs/stream`); const authHdrs = await this.authHeaders(); @@ -1189,7 +1198,7 @@ export class Seclai { let lastSeen: AgentRunResponse | undefined; try { - const init: RequestInit = { method: "POST", headers, body: JSON.stringify(body) }; + const init: RequestInit = { method: "POST", headers, body: JSON.stringify(runBody) }; if (signal) init.signal = signal; const response = await this.fetcher(url, init); @@ -1491,10 +1500,14 @@ export class Seclai { // ═══════════════════════════════════════════════════════════════════════════ /** - * Upload a file to use as input for a `dynamic_input` agent run. + * Upload a file to use as input for a `dynamic_input` agent run. Any other + * agent rejects the upload with HTTP 400. Files are limited to 200 MB. * - * After uploading, poll {@link getAgentInputUploadStatus} until `status` is `ready`, - * then pass `input_upload_id` to {@link runAgent}. + * From API version `2026-10-16` a file of any type is accepted and is `ready` + * at once: pass its `id` as `input_upload_id` to {@link runAgent}. + * Earlier versions accept only a fixed list of extensions and write each + * file's extracted text into the run's `input`, so poll + * {@link getAgentInputUploadStatus} until `status` is `ready` before running. * * @param agentId - Agent identifier. * @param opts - File payload and optional metadata. @@ -1546,16 +1559,20 @@ export class Seclai { * @param runId - Run identifier. * @param attachmentId - URL-safe-base64-encoded `storage_key` of the attachment * (as surfaced in run output manifests and webhook/email payloads). - * @param opts - Optional `downloadName` filename hint for the download disposition. + * @param opts - Optional `downloadName` filename hint for the download + * disposition, and `signal`, which cancels the request; with a standard `fetch` this + * includes reading the body, so `AbortSignal.timeout(ms)` bounds the whole + * transfer. * @returns Raw response with the attachment bytes. */ async downloadAgentRunAttachment( runId: string, attachmentId: string, - opts: { downloadName?: string } = {}, + opts: { downloadName?: string; signal?: AbortSignal } = {}, ): Promise { return await this.requestRaw("GET", `/v2/agent-runs/${runId}/attachments/${attachmentId}`, { query: { download_name: opts.downloadName }, + signal: opts.signal, }); } @@ -1838,6 +1855,29 @@ export class Seclai { })) as EmailTriggerConfigResponse; } + /** + * Replace the input attachments a trigger accepts. + * + * A run's files are each assigned to one declared attachment before any step + * runs, and steps reference one as `{{agent.attachments.}}`. The API + * answers 400 when the agent references an attachment the new declaration + * leaves out. + * + * @param agentId - Agent identifier. + * @param triggerId - Trigger identifier, as `getAgent()` returns it. + * @param body - The full list of accepted attachments; a slot's `min` defaults to 0. + * @returns The trigger's accepted attachments. + */ + async setAcceptedAttachments( + agentId: string, + triggerId: string, + body: SetAcceptedAttachmentsInput, + ): Promise { + return (await this.request("PUT", `/agents/${agentId}/triggers/${triggerId}/accepted-attachments`, { + json: body, + })) as AcceptedAttachmentsResponse; + } + // ═══════════════════════════════════════════════════════════════════════════ // Agent Email Governance // ═══════════════════════════════════════════════════════════════════════════ @@ -2351,6 +2391,28 @@ export class Seclai { )) as SourceContentStatusResponse; } + /** + * List mail an email content source refused, newest first. + * + * Each entry says who sent the message and why it was refused, never its + * subject or body. To accept a refused sender, add its `from_address` or that + * address's domain to the source's `email_allowed_senders` — which only helps + * when `authenticated` is true. Requires an account owner or administrator; + * the API answers 404 for a source that is not an email source. + * + * @param sourceId - Source connection identifier. + * @param opts - Pagination options (`limit` 1-100). + * @returns The rejections under `data` with `pagination`. + */ + async listEmailSourceRejections( + sourceId: string, + opts: ListOptions = {}, + ): Promise { + return (await this.request("GET", `/sources/${sourceId}/email-rejections`, { + query: { page: opts.page, limit: opts.limit }, + })) as EmailSourceRejectionListResponse; + } + // ─── Source Exports ──────────────────────────────────────────────────────── /** @@ -2405,10 +2467,19 @@ export class Seclai { * * @param sourceId - Source connection identifier. * @param exportId - Export identifier. + * @param opts - Optional `signal`, which cancels the request; with a standard `fetch` this + * includes reading the body, so `AbortSignal.timeout(ms)` bounds the whole + * transfer. * @returns Raw response with the export file. */ - async downloadSourceExport(sourceId: string, exportId: string): Promise { - return await this.requestRaw("GET", `/sources/${sourceId}/exports/${exportId}/download`); + async downloadSourceExport( + sourceId: string, + exportId: string, + opts: { signal?: AbortSignal } = {}, + ): Promise { + return await this.requestRaw("GET", `/sources/${sourceId}/exports/${exportId}/download`, { + signal: opts.signal, + }); } /** @@ -2520,6 +2591,98 @@ export class Seclai { })) as ContentEmbeddingsListResponse; } + /** + * List the files attached to a content item. + * + * Files arrive from an agent's `write_content_attachment` step, with an email + * message, from an RSS feed's `feed_attachments`, from a web page's media, or + * as the images inside a document. Each entry says whether it is indexed for + * search and, when indexing failed, why. + * + * @param contentVersionId - Content version identifier. + * @param opts - Pagination options. + * @returns The attachments under `data` with `pagination`. + */ + async listContentAttachments( + contentVersionId: string, + opts: ListOptions = {}, + ): Promise { + return (await this.request("GET", `/contents/${contentVersionId}/attachments`, { + query: { page: opts.page, limit: opts.limit }, + })) as ContentAttachmentsListResponse; + } + + /** + * Get one file attached to a content item: its indexing status and reason, + * its metadata, and the text it is indexed by. + * + * @param contentVersionId - Content version identifier. + * @param attachmentId - The `id` of an entry from {@link listContentAttachments}. + * @param opts - `start` and `end` character offsets for paging through long text + * (server defaults 0 and 5000). Both are sent as given, so `end: 0` asks for + * the metadata without any text. A file that was not indexed has no text. + * @returns The attachment with the requested range of its text. + * @throws {SeclaiAPIStatusError} 402 when the account has no credits left + * (`error.code` `insufficient_credits`). + */ + async getContentAttachment( + contentVersionId: string, + attachmentId: string, + opts: { start?: number; end?: number } = {}, + ): Promise { + return (await this.request("GET", `/contents/${contentVersionId}/attachments/${attachmentId}`, { + query: { start: opts.start, end: opts.end }, + })) as ContentAttachmentDetailResponse; + } + + /** + * List the embeddings (chunk vectors) a content attachment is indexed by. + * The list is empty for a file that has no completed index. + * + * @param contentVersionId - Content version identifier. + * @param attachmentId - Attachment identifier. + * @param opts - Pagination options (`limit` 1-100). + * @returns Paginated list of embeddings. + * @throws {SeclaiAPIStatusError} 402 when the account has no credits left + * (`error.code` `insufficient_credits`). + */ + async listContentAttachmentEmbeddings( + contentVersionId: string, + attachmentId: string, + opts: ListOptions = {}, + ): Promise { + return (await this.request("GET", `/contents/${contentVersionId}/attachments/${attachmentId}/embeddings`, { + query: { page: opts.page, limit: opts.limit }, + })) as ContentEmbeddingsListResponse; + } + + /** + * Download a content attachment's bytes. + * + * Returns the raw `Response` so you can stream or save the binary data. The + * API answers 403 when the file is withheld — blocked or redacted by a + * governance policy, or still being indexed after arriving from outside; the + * attachment's `file_withheld` field says which before you ask. + * + * @param contentVersionId - Content version identifier. + * @param attachmentId - Attachment identifier. + * @param opts - Optional `signal`, which cancels the request; with a standard `fetch` this + * includes reading the body, so `AbortSignal.timeout(ms)` bounds the whole + * transfer. + * @returns Raw response with the attachment bytes. + * @throws {SeclaiAPIStatusError} 403 when the file is withheld, and 402 when + * the account has no credits left (`error.code` `insufficient_credits`). + */ + async downloadContentAttachment( + contentVersionId: string, + attachmentId: string, + opts: { signal?: AbortSignal } = {}, + ): Promise { + return await this.requestRaw("GET", `/contents/${contentVersionId}/attachments/${attachmentId}/file`, { + signal: opts.signal, + }); + } + /** * Upload a file to replace content for an existing content version. * diff --git a/src/index.ts b/src/index.ts index 25d2014..e8ae7ea 100644 --- a/src/index.ts +++ b/src/index.ts @@ -105,6 +105,8 @@ export type { BlockedEmailSenderListResponse, SetAutoBlockModeRequest, InboundEmailRejectionResponse, + EmailSourceRejectionResponse, + EmailSourceRejectionListResponse, InboundEmailStatusResponse, CancelQueuedRunsResponse, ResumeInboundResponse, @@ -126,6 +128,11 @@ export type { // Agent Input Uploads UploadAgentInputApiResponse, AgentAttachmentRefsApiResponse, + AcceptedAttachmentSlot, + AcceptedAttachmentSlotInput, + AcceptedAttachmentsResponse, + SetAcceptedAttachmentsRequest, + SetAcceptedAttachmentsInput, AttachmentRefsSourceApiSummary, // Agent AI Assistant @@ -241,6 +248,11 @@ export type { ContentDetailResponse, ContentEmbeddingsListResponse, ContentEmbeddingResponse, + ContentAttachmentResponse, + ContentAttachmentsListResponse, + ContentAttachmentDetailResponse, + SkippedAttachmentResponse, + SkippedAttachmentReason, ContentFileUploadResponse, // Solutions diff --git a/src/openapi.ts b/src/openapi.ts index 1d6bbe6..b08e65c 100644 --- a/src/openapi.ts +++ b/src/openapi.ts @@ -29,7 +29,7 @@ export interface paths { * - `template_input`: triggered via API with a predefined template * - `schedule`: triggered on a schedule * - `new_content`: triggered when new content arrives - * - `email_received`: a virtual email inbox; runs when mail arrives at the agent's address. Configure the alias/allowlist with `PUT /agents/{agent_id}/triggers/{trigger_id}/email-config`. + * - `email_received`: a virtual email inbox; runs when mail arrives at the agent's address. Configure the alias/allowlist with `PUT /agents/{agent_id}/triggers/{trigger_id}/email-config`, using the `trigger_id` this response returns. * * Templates: `blank`, `retrieval_example`, `simple_qa`, `summarizer`, `json_extractor`, `content_change_notifier`, `scheduled_report`, `webhook_pipeline` * @@ -269,6 +269,8 @@ export interface paths { * * Returns total, passed, failed, error, and flagged counts alongside the * average score, giving a quick overview of how the criteria is performing. + * With ``2026-10-21`` or later, ``average_score`` averages only passed and failed + * results; earlier versions average every stored score, ``error`` included. */ get: operations["get_evaluation_summary_api_agents_evaluation_criteria__criteria_id__summary_get"]; put?: never; @@ -292,6 +294,11 @@ export interface paths { * * Returns aggregated pass/fail/flagged counts and pass rates for each evaluation mode (eval_and_retry, sample_and_flag). * + * With ``2026-10-21`` or later, ``error`` results (the evaluator returned no + * verdict) are left out of ``failed``, and the rates are over passed and + * failed results. Earlier versions count them in ``failed`` and rate over + * every result. ``error`` is returned on every version. + * * The ``agent_id`` scoping parameter is part of the ``2026-07-27`` changeset * (opt in via the ``Seclai-Version`` header). Clients on the legacy baseline * always receive the account-wide rollup; ``agent_id`` is ignored for them so @@ -641,9 +648,9 @@ export interface paths { }; /** * Get agent attachment-reference contract - * @description Return the static attachment-reference contract for an agent — what files the agent's definition expects on a run. + * @description Return the input attachments the agent's dynamic_input trigger declares — the files a run may carry. * - * Call this BEFORE staging uploads so you know whether the agent accepts files at all (``requires_uploads``), and which specific filenames/indexes/patterns the templates reference. Mismatched batches are rejected at run time with HTTP 400. + * Call this BEFORE staging uploads so you know whether the agent accepts files at all (``requires_uploads``), and which attachments its trigger declares (``accepted_attachments``). Batches that do not fit them are rejected at run time with HTTP 400. */ get: operations["api_get_agent_attachment_references_api_agents__agent_id__attachment_references_get"]; put?: never; @@ -847,6 +854,10 @@ export interface paths { * Use this to interactively test evaluation prompts and expectation * configurations while editing criteria. The evaluation is a billed LLM * call; only its result goes unrecorded. + * + * ``status`` is ``error`` when the evaluator returned no verdict. With + * ``Seclai-Version: 2026-10-21`` or later, ``score`` and ``passed`` are then + * ``null``; earlier versions return ``score`` 0.5 and ``passed`` false. */ post: operations["test_draft_evaluation_api_agents__agent_id__evaluation_criteria_test_draft_post"]; delete?: never; @@ -998,7 +1009,7 @@ export interface paths { * * Key fields: * - `input`: text input for agents with a `dynamic_input` trigger. - * - `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file's extracted text follows); only the two upload fields are mutually exclusive with each other. + * - `input_upload_id` / `input_upload_ids`: reference one or more files previously uploaded via `POST /agents/{agent_id}/upload-input`. Send them **with** `input` to pair prompt text with the files (the text leads, each file follows under its heading); only the two upload fields are mutually exclusive with each other. * - `priority`: set true for latency-sensitive, user-facing work. For agents with a `streaming_result` step, set `priority=true` to enable real-time token streaming; otherwise the run still proceeds, but without live token streaming. * - `metadata`: a JSON object that becomes available to agent steps for string substitution. * @@ -1035,6 +1046,7 @@ export interface paths { * - The first `init` event contains an `AgentRunResponse` snapshot, including the `run_id`. * - Subsequent events are forwarded from the run event stream (status changes, step events, etc). * - If the agent contains a `streaming_result` step, `stream_token` events deliver individual LLM tokens (with a `token` field) and a `stream_end` event signals completion. + * - With `include_reasoning=true`, `stream_reasoning` events (with a `text` field) carry the model's reasoning while it thinks, when the `streaming_result` step's author enabled `show_reasoning`. Reasoning is never part of `output`. * - The final `done` event contains the terminal snapshot (including `output` and `credits` when available). * * Input options (for `dynamic_input` triggers): @@ -1087,6 +1099,28 @@ export interface paths { patch?: never; trace?: never; }; + "/agents/{agent_id}/triggers/{trigger_id}/accepted-attachments": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + /** + * Declare the input attachments a trigger accepts + * @description Replace the input attachments a trigger accepts. A run's files are each assigned to one declared attachment before any step runs; steps reference one as ``{{agent.attachments.}}``. Rejected with HTTP 400 when the agent references an attachment the new declaration leaves out. `trigger_id` is the one `GET /agents/{agent_id}` returns. + * + * Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account. + */ + put: operations["set_accepted_attachments_api_api_agents__agent_id__triggers__trigger_id__accepted_attachments_put"]; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/agents/{agent_id}/triggers/{trigger_id}/email-config": { parameters: { query?: never; @@ -1097,7 +1131,7 @@ export interface paths { get?: never; /** * Configure an EMAIL_RECEIVED trigger - * @description Set the custom alias, sender allowlist, and inbound-handling flags (`ignore_auto_generated`, `require_sender_auth`, `queue_on_quota`) on an agent's EMAIL_RECEIVED trigger, and return its computed email address(es). Omitted fields are left unchanged. + * @description Set the custom alias, sender allowlist, and inbound-handling flags (`ignore_auto_generated`, `require_sender_auth`, `queue_on_quota`, `run_on_attachment_mismatch`) on an agent's EMAIL_RECEIVED trigger, and return its computed email address(es). `trigger_id` is the one `GET /agents/{agent_id}` returns. Omitted fields are left unchanged. * * Auth & scoping: requires `X-API-Key` header or OAuth Bearer token; the trigger must belong to an agent in the key's account. */ @@ -1120,17 +1154,15 @@ export interface paths { put?: never; /** * Upload file input - * @description Upload a file to use as input for a `dynamic_input` agent run. - * - * Supports the same file types as content source uploads: text, PDF, DOCX, audio, video, images, etc. Text and document files are processed synchronously; audio/video are submitted for asynchronous transcription. + * @description Upload a file to use as input for a `dynamic_input` agent run. Any other agent rejects the upload with HTTP 400. * * **Size limit:** 200 MB per file. * - * **Supported extensions:** txt, html, md, csv, xml, json, pdf, msg, docx, doc, pptx, ppt, xlsx, xls, zip, epub, png, jpg, gif, bmp, tiff, webp, mp3, wav, m4a, flac, ogg, mp4, mov, avi. + * From `Seclai-Version: 2026-10-16` a file of any type is accepted and is `ready` at once: pass `input_upload_id` to `POST /agents/{agent_id}/runs`. Each step receives the file itself when its model reads that type, and otherwise its text (OCR, extraction or transcript), made once for the steps that need it; a type nothing reads or converts is passed on as a file only. `input` carries a `# filename` heading per file. * - * After uploading, poll `GET /agents/{agent_id}/input-uploads/{upload_id}` until `status` is `ready`, then pass `input_upload_id` to `POST /agents/{agent_id}/runs`. + * Earlier versions accept only these extensions: avi, bmp, csv, docx, epub, flac, gif, html, jpg, json, m4a, markdown, md, mov, mp3, mp4, msg, ogg, pdf, png, ppt, pptx, svg, tiff, txt, wav, webp, xls, xlsx, xml, zip. They write each file's text into `input`, so poll `GET /agents/{agent_id}/input-uploads/{upload_id}` until `status` is `ready` before running. * - * **Multi-modal routing:** non-text uploads (image, audio, video, PDF) are surfaced natively to multi-modal-capable prompt steps; text-only models fall back to the OCR / transcript text counterpart. Audio originals are preserved past transcription so audio-capable models (Gemini 2.5/3, GPT-5 audio) read them directly; the agent-input-binary janitor sweeps originals once they pass your account's agent-trace retention (the agent-traces source's retention period; free default 7 days). + * The agent-input-binary janitor sweeps originals once they pass your account's agent-trace retention (the agent-traces source's retention period; free default 7 days). * * Auth & scoping: * - Requires `X-API-Key` header or OAuth Bearer token. All resources are scoped to the caller's account. @@ -1826,6 +1858,106 @@ export interface paths { patch?: never; trace?: never; }; + "/contents/{source_connection_content_version}/attachments": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List content attachments + * @description List the files attached to a content item, with pagination. + * + * An agent's `write_content_attachment` step attaches a file, and an email content source attaches the files sent with a message. An RSS source attaches the kinds of feed file chosen in its `feed_attachments`. The images and video in a web page's main content are attached on a source with media indexing on. The images inside a PDF, DOCX, PPTX or XLSX item or attachment are attached too, on a source that indexes document images. Each entry says whether the file is indexed for search and, when indexing failed, why. + * + * Auth & scoping: + * - Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account. + */ + get: operations["list_content_attachments_api_contents__source_connection_content_version__attachments_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/contents/{source_connection_content_version}/attachments/{attachment_id}": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get a content attachment + * @description Get one file attached to a content item: its indexing status and reason, its metadata, and the text it is indexed by. + * + * `attachment_id` is the `id` of an entry in the item's attachment list. Use `start` and `end` to page through long text. A file that was not indexed has no text. + * + * Auth & scoping: + * - Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account. + */ + get: operations["get_content_attachment_api_contents__source_connection_content_version__attachments__attachment_id__get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/contents/{source_connection_content_version}/attachments/{attachment_id}/embeddings": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List a content attachment's embeddings + * @description List the embeddings (chunk vectors) an attached file is indexed by, with pagination. The list is empty for a file that has no completed index. + * + * Auth & scoping: + * - Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account. + */ + get: operations["list_content_attachment_embeddings_api_contents__source_connection_content_version__attachments__attachment_id__embeddings_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/contents/{source_connection_content_version}/attachments/{attachment_id}/file": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Download a content attachment + * @description Download an attached file's bytes. + * + * Images, audio, video, PDF and plain text are served with their own type; an SVG that cannot be sanitized, and anything else, is served as `application/octet-stream`. + * + * Answers 403 when the file is withheld: a governance policy blocked or redacted it, or it arrived from outside and is still being indexed. The attachment's `file_withheld` field says which before you ask. + * + * Auth & scoping: + * - Requires `X-API-Key` header or OAuth Bearer token. You can only access attachments of content belonging to your account. + */ + get: operations["get_content_attachment_file_api_contents__source_connection_content_version__attachments__attachment_id__file_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/contents/{source_connection_content_version}/embeddings": { parameters: { query?: never; @@ -1869,22 +2001,31 @@ export interface paths { * **Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored). * * **Supported MIME types:** + * - `application/atom+xml` * - `application/epub+zip` * - `application/json` * - `application/pdf` + * - `application/rss+xml` + * - `application/rtf` * - `application/vnd.ms-excel` * - `application/vnd.ms-outlook` * - `application/vnd.ms-powerpoint` * - `application/vnd.openxmlformats-officedocument.presentationml.presentation` * - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` * - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` + * - `application/x-ipynb+json` + * - `application/xhtml+xml` * - `application/xml` * - `application/zip` + * - `audio/aac` + * - `audio/amr` * - `audio/flac` * - `audio/mp4` * - `audio/mpeg` * - `audio/ogg` + * - `audio/opus` * - `audio/wav` + * - `audio/webm` * - `image/bmp` * - `image/gif` * - `image/jpeg` @@ -1892,14 +2033,43 @@ export interface paths { * - `image/svg+xml` * - `image/tiff` * - `image/webp` + * - `message/rfc822` + * - `text/calendar` * - `text/csv` * - `text/html` + * - `text/javascript` * - `text/markdown` * - `text/plain` + * - `text/tab-separated-values` + * - `text/vcard` + * - `text/vtt` + * - `text/x-c` + * - `text/x-c++` + * - `text/x-csharp` + * - `text/x-go` + * - `text/x-ini` + * - `text/x-java` + * - `text/x-log` * - `text/x-markdown` + * - `text/x-php` + * - `text/x-python` + * - `text/x-ruby` + * - `text/x-rust` + * - `text/x-shellscript` + * - `text/x-sql` + * - `text/x-subrip` + * - `text/x-tex` + * - `text/x-toml` + * - `text/x-typescript` * - `text/xml` + * - `text/yaml` + * - `video/3gpp` + * - `video/mp2t` * - `video/mp4` + * - `video/mpeg` * - `video/quicktime` + * - `video/webm` + * - `video/x-matroska` * - `video/x-msvideo` * * Notes: @@ -2692,7 +2862,7 @@ export interface paths { * List Embedding Models * @description List the embedding models a source can be created with. * - * Each entry carries the `model_type` to pass as `embedding_model` when creating a source, the `dimensions` it supports, and — most importantly for multi-modal indexing — `supported_input_media`: the modalities that embedder can actually index. A source only honours a `media_types` entry its embedder lists here; unsupported kinds are dropped at save time with an `embedder_warning`, so check this before choosing an embedder for a knowledge base of images or video. + * Each entry carries the `model_type` to pass as `embedding_model` when creating a source, the `dimensions` it supports, and — most importantly for multi-modal indexing — `supported_input_media`: the modalities that embedder can actually index. A source only honours a `media_types` entry its embedder lists here; a kind it does not list is stored and not indexed, so check this before choosing an embedder for a knowledge base of images or video. * * Text-only embedders report `supported_input_media` as null. Pricing is reported as `credits` (per ~1,000 English words of text) plus `per_modality_rates` for the non-text modalities a multi-modal embedder bills differently. * @@ -2820,7 +2990,7 @@ export interface paths { * Cancel Experiment Endpoint * @description Cancel a running or pending model playground experiment. * - * Signals running model calls to abort and marks the experiment as canceled. + * Marks the experiment as canceled. An experiment that has not started never runs. One that is running starts no further model calls, and records each model it did not call with the error `Canceled`. A model call or evaluation already in progress is not interrupted by the cancel: it continues and is billed, and its result is recorded on the canceled experiment. Canceling may therefore not shorten the run or reduce its cost. * * Auth & scoping: * - Requires `X-API-Key` header or OAuth Bearer token. The experiment must belong to the caller's account and, when the credential is bound to a user, to that user; otherwise 404. @@ -3274,10 +3444,14 @@ export interface paths { * Create Source * @description Create a new content source. * - * Source types: `rss`, `website`, `custom_index`. + * Source types: `rss_feed`, `website`, `custom_index`, `cloud_drive`, `email`. * * For RSS and website sources, provide the URL. For custom index sources, the URL is created automatically. * + * An `email` source takes no URL and requires `email_allowed_senders`; the response's `email_address` is where to send mail. + * + * A `cloud_drive` source takes no URL and requires `cloud_drive_connection_id`, the id of a drive connected in the app (`GET /cloud-drives` lists them). + * * For custom_index sources, you can optionally specify an `index_mode`: `fast_and_cheap` (default), `balanced`, `slow_and_thorough`, or `custom`. The legacy `file_uploads` source type is accepted as an alias for `custom_index` with `index_mode=fast_and_cheap`. */ post: operations["create_source_api_sources_post"]; @@ -3336,6 +3510,7 @@ export interface paths { * - `duplicate` — this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll. * - For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=…&content_version_id=…` for a whole batch, to follow each item through to `completed` or `failed`. * - On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes. + * - An item that reports `held_for_review: true` was blocked by an Enforce governance policy. It is not in the source and its id stays `null` unless a reviewer releases it, so stop polling. */ post: operations["upload_inline_text_to_source_api_sources__source_connection_id__post"]; /** @@ -3367,6 +3542,7 @@ export interface paths { * - Each item is keyed by `content_version_id`, which is what the upload endpoints return. Pass those ids as repeated `content_version_id` query parameters to poll exactly the items you uploaded. * - `source_connection_content_version_id` is `null` until an item finishes indexing; once set, it is the id `GET /contents/{id}` takes. * - `content_status` reaches `completed` on success and `failed` on error, with the reason in `error`. The intermediate values are `pending`, `fetching`, `transcribing`, `scanning`, and `indexing`. + * - An item an Enforce governance policy blocked at import is held for review: `held_for_review` is `true` and `source_connection_content_version_id` stays `null` until a reviewer releases it. With `Seclai-Version: 2026-10-05` or later it reports `completed`; earlier versions report it as `failed` with the hold as the `error`. The `status` filter matches the item under `completed` on every version. * * Parameters: * - Pagination: `page` and `limit`. @@ -3398,6 +3574,8 @@ export interface paths { * * Use this to follow one uploaded file through indexing. To follow many at once, use `GET /sources/{id}/contents` with repeated `content_version_id` parameters instead of polling this endpoint per item. * + * An item held for review by an Enforce governance policy reports `held_for_review: true`. With `Seclai-Version: 2026-10-05` or later its `content_status` is `completed`; earlier versions report `failed` with the hold as the `error`. + * * Auth & scoping: * - Requires `X-API-Key` header or OAuth Bearer token. You can only access content belonging to your account. */ @@ -3410,6 +3588,30 @@ export interface paths { patch?: never; trace?: never; }; + "/sources/{source_connection_id}/email-rejections": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List mail an email source refused + * @description List mail that an email content source refused, newest first. Each entry says who sent the message and why it was refused, never its subject or body. A message refused as `unsafe_content` also has a prompt-scan record, which keeps the scanned text. + * + * To accept a refused sender, add its `from_address` or that address's domain to the source's `email_allowed_senders`. That only helps when `authenticated` is true. A `repeat_*` reason marks a message the source received before; allowing its sender does not store it. + * + * Requires an account owner or administrator: a key or token bound to another member gets 403. Returns 404 for a source that is not an email source. + */ + get: operations["list_email_source_rejections_api_api_sources__source_connection_id__email_rejections_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/sources/{source_connection_id}/embedding-migration": { parameters: { query?: never; @@ -3591,22 +3793,31 @@ export interface paths { * **Maximum file size:** 209715200 bytes, except `image/svg+xml` at 5242880 bytes (SVG is sanitized before it is stored). * * **Supported MIME types:** + * - `application/atom+xml` * - `application/epub+zip` * - `application/json` * - `application/pdf` + * - `application/rss+xml` + * - `application/rtf` * - `application/vnd.ms-excel` * - `application/vnd.ms-outlook` * - `application/vnd.ms-powerpoint` * - `application/vnd.openxmlformats-officedocument.presentationml.presentation` * - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` * - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` + * - `application/x-ipynb+json` + * - `application/xhtml+xml` * - `application/xml` * - `application/zip` + * - `audio/aac` + * - `audio/amr` * - `audio/flac` * - `audio/mp4` * - `audio/mpeg` * - `audio/ogg` + * - `audio/opus` * - `audio/wav` + * - `audio/webm` * - `image/bmp` * - `image/gif` * - `image/jpeg` @@ -3614,14 +3825,43 @@ export interface paths { * - `image/svg+xml` * - `image/tiff` * - `image/webp` + * - `message/rfc822` + * - `text/calendar` * - `text/csv` * - `text/html` + * - `text/javascript` * - `text/markdown` * - `text/plain` + * - `text/tab-separated-values` + * - `text/vcard` + * - `text/vtt` + * - `text/x-c` + * - `text/x-c++` + * - `text/x-csharp` + * - `text/x-go` + * - `text/x-ini` + * - `text/x-java` + * - `text/x-log` * - `text/x-markdown` + * - `text/x-php` + * - `text/x-python` + * - `text/x-ruby` + * - `text/x-rust` + * - `text/x-shellscript` + * - `text/x-sql` + * - `text/x-subrip` + * - `text/x-tex` + * - `text/x-toml` + * - `text/x-typescript` * - `text/xml` + * - `text/yaml` + * - `video/3gpp` + * - `video/mp2t` * - `video/mp4` + * - `video/mpeg` * - `video/quicktime` + * - `video/webm` + * - `video/x-matroska` * - `video/x-msvideo` * * Notes: @@ -3640,6 +3880,7 @@ export interface paths { * - `duplicate` — this exact file is already on the source, so nothing was created and nothing is being indexed. `content_version_id` is `null` and `source_connection_content_version_id` is the existing, already-indexed item: pass it straight to `GET /contents/{id}`. There is nothing to poll. * - For an `uploaded` item, poll `GET /sources/{id}/contents/{content_version_id}` with the returned `content_version_id`, or `GET /sources/{id}/contents?content_version_id=…&content_version_id=…` for a whole batch, to follow each item through to `completed` or `failed`. * - On those status endpoints `source_connection_content_version_id` stays `null` until the item finishes indexing; that is the id `GET /contents/{id}` takes. + * - An item that reports `held_for_review: true` was blocked by an Enforce governance policy. It is not in the source and its id stays `null` unless a reviewer releases it, so stop polling. */ post: operations["upload_file_to_source_api_sources__source_connection_id__upload_post"]; delete?: never; @@ -3657,7 +3898,7 @@ export interface paths { }; /** * Download an agent-run attachment - * @description Streams the bytes of an attachment emitted by a step in the given agent run. ``attachment_id`` is the ``id`` of an entry in the run's or a step's ``attachments``, or the URL-safe-base64-encoded storage key, which webhook and email links carry. + * @description Streams the bytes of a file of the given agent run: one a step emitted, or one the run started with. ``attachment_id`` is the ``id`` of an entry in the run's or a step's ``attachments``, or the URL-safe-base64-encoded storage key, which webhook and email links carry. * * Auth & scoping: * - Requires `X-API-Key` header or OAuth Bearer token. @@ -3704,6 +3945,55 @@ export interface paths { export type webhooks = Record; export interface components { schemas: { + /** AcceptedAttachmentSlot */ + AcceptedAttachmentSlot: { + /** + * Content Types + * @description Accepted types, e.g. ``application/pdf`` or ``image/*``; empty accepts any type. + */ + content_types?: string[]; + /** + * Label + * @description Shown to people. + */ + label?: string | null; + /** + * Max + * @description Most files a run may include; empty is no limit. + */ + max?: number | null; + /** + * Min + * @description Fewest files a run must include; fewer refuses the run, except on an email trigger set to run anyway, which lists the shortfall. + * @default 0 + */ + min: number; + /** + * Name + * @description Lowercase letters, digits and underscores, starting with a letter. Steps reference the files as ``{{agent.attachments.}}``. + */ + name: string; + /** + * Name Pattern + * @description Filename glob a file must also match, ignoring case. + */ + name_pattern?: string | null; + }; + /** AcceptedAttachmentsResponse */ + AcceptedAttachmentsResponse: { + /** Accepted Attachments */ + accepted_attachments: components["schemas"]["AcceptedAttachmentSlot"][]; + /** + * Agent Id + * Format: uuid + */ + agent_id: string; + /** + * Trigger Id + * Format: uuid + */ + trigger_id: string; + }; /** AddConversationTurnRequest */ AddConversationTurnRequest: { /** @@ -3741,19 +4031,23 @@ export interface components { }; /** * AgentAttachmentRefsApiResponse - * @description Static attachment-reference contract for an agent. + * @description The input attachments an agent's trigger declares. * - * Mirrors the MCP ``get_agent_attachment_references`` tool: returns - * what files (if any) an agent's templates expect on a run so API - * consumers can stage uploads correctly before calling + * Mirrors the MCP ``get_agent_attachment_references`` tool, so API + * consumers can stage uploads that fit before calling * ``POST /agents/{id}/runs``. */ AgentAttachmentRefsApiResponse: { - /** @description Aggregated selector summary across all consumer steps. ``exact_names`` entries must each appear in the upload batch; ``indexes_max+1`` is the minimum file count; every ``patterns`` glob must match at least one upload. */ + /** + * Accepted Attachments + * @description The attachments the agent's trigger declares. A run's files are each assigned to one; a file none accepts, or an attachment with fewer files than its ``min``, rejects the run with HTTP 400. Steps reference one as ``{{agent.attachments.}}``. + */ + accepted_attachments?: components["schemas"]["AcceptedAttachmentSlot"][]; + /** @description Aggregated summary of the agent-file references in the steps. Informational: which files a run accepts is ``accepted_attachments``. */ agent?: components["schemas"]["AttachmentRefsSourceApiSummary"]; /** * Requires Uploads - * @description When ``false`` the agent's definition does NOT reference any uploaded attachments — ``POST /agents/{id}/upload-input`` will reject with HTTP 400. When ``true`` the ``agent`` block lists the specific selectors a run-time batch must satisfy. + * @description When ``false`` the agent takes no files through the API — it has no ``dynamic_input`` trigger, or that trigger declares no attachments — and ``POST /agents/{id}/upload-input`` will reject with HTTP 400. When ``true`` ``accepted_attachments`` lists what a run's files must fit. */ requires_uploads: boolean; }; @@ -3995,16 +4289,16 @@ export interface components { input?: string | null; /** * Input Upload Id - * @description ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` — use that field to attach multiple files. May be combined with ``input``: the prompt text leads and the file's extracted text follows under a ``# {filename}`` heading. + * @description ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` — use that field to attach multiple files. May be combined with ``input``: the prompt text leads and the file follows under a ``# {filename}`` heading (before ``Seclai-Version: 2026-10-16``, followed by its extracted text). * - * **Attachment visibility:** a step only sees the upload when its template references the input — via ``{{input}}`` / ``{{agent.input}}`` / ``{{step..input|output}}`` (implicit, all attachments) or the ``{{attachments[…]}}`` family (explicit narrowing — e.g. ``{{attachments[0]}}``, ``{{attachments[*.pdf]}}``). + * **Which steps receive it:** a step that sends or stores files takes the files its ``attachments`` field selects. An LLM step (``prompt_call``, ``extract_data``, ``evaluate_step``) takes the files its ``attachments`` field names, or else the files its plain-text templates reference: ``{{agent.attachments.}}`` for one attachment the trigger declares, or ``{{agent.input}}`` for every upload unless a template also names an agent attachment. * - * **Per-batch validation:** every selector the agent's definition declares must be satisfied or the run is rejected with HTTP 400. Exact-name selectors require that filename to be present; indexed selectors require at least N+1 files; glob patterns require at least one matching filename. + * **Per-batch validation:** the batch must fit the trigger's ``accepted_attachments`` — every file fits one declared attachment and each attachment gets at least its ``min`` files — or the run is rejected with HTTP 400. */ input_upload_id?: string | null; /** * Input Upload Ids - * @description IDs of multiple previously uploaded files. Each upload's extracted text is concatenated under a heading; each upload's binary is surfaced as a separate ``MediaAttachment`` so multi-modal prompt steps reason over all files at once. Steps narrow visibility via ``{{attachments[…]}}`` selectors (by index, filename, or fnmatch glob). The batch must satisfy every selector the agent declares — exact names, indexed references (length must exceed the highest index), and glob patterns (each pattern needs at least one match). Mismatches return HTTP 400 with the unmet requirements listed. Mutually exclusive with ``input_upload_id`` (two spellings of the same batch), but may be combined with ``input`` — the prompt text leads and the per-file sections follow, so "a photo plus a sentence about it" needs no synthetic text upload. Max 20 uploads per run. + * @description IDs of multiple previously uploaded files. Each upload gets a heading in ``input`` (before ``Seclai-Version: 2026-10-16``, followed by its extracted text); each upload reaches steps as a separate file (before ``Seclai-Version: 2026-10-16``, a text upload in the open ``files`` attachment is written into ``input`` instead). Steps choose files as described under ``input_upload_id``. The batch must fit the trigger's ``accepted_attachments``; a mismatch returns HTTP 400 listing what does not fit. Mutually exclusive with ``input_upload_id`` (two spellings of the same batch), but may be combined with ``input`` — the prompt text leads and the per-file sections follow, so "a photo plus a sentence about it" needs no synthetic text upload. Max 20 uploads per run. */ input_upload_ids?: string[] | null; /** @@ -4022,7 +4316,7 @@ export interface components { priority: boolean; /** * Replay Of Run Id - * @description Re-run this agent reusing a prior run's uploaded input files. The files are re-resolved server-side from the source run (which must belong to this account and agent) — you do not re-upload them. Combine with ``input`` to change the text while keeping the files. A fresh upload batch (``input_upload_id(s)``) takes precedence and disables replay. Binaries swept by retention fall back to their extracted text. + * @description Re-run this agent reusing a prior run's uploaded input files. The files are re-resolved server-side from the source run (which must belong to this account and agent) — you do not re-upload them. Combine with ``input`` to change the text while keeping the files. A fresh upload batch (``input_upload_id(s)``) takes precedence and disables replay. Binaries swept by retention fall back to their extracted text. Files the trigger's ``accepted_attachments`` no longer accepts are left out. */ replay_of_run_id?: string | null; }; @@ -4085,7 +4379,7 @@ export interface components { input_scan_status?: string | null; /** * Output - * @description The run's output text; its files are in `attachments`. Below `Seclai-Version: 2026-09-30` an output that has files is instead the manifest JSON `{schema, text, attachments: [{storage_key, mime, name, label, bytes}]}`; `bytes` is absent on runs made before that version shipped. + * @description The run's output text; its files are in `attachments`. Below `Seclai-Version: 2026-09-30` an output that has files is instead the manifest JSON `{schema, text, attachments: [{storage_key, mime, name, label, bytes}]}`; `bytes` can be `null` on runs made before that version shipped. */ output: string | null; /** @@ -4117,7 +4411,7 @@ export interface components { steps?: components["schemas"]["AgentRunStepResponse"][] | null; /** * Trace Purged At - * @description When this run's trace content was deleted under the account's agent-trace retention window. Non-null means `input`, `output` and every step's and tool call's I/O are null **by design** and will never be available again — the run aged out, it did not fail. Branch on this rather than on a null `output`: a run that genuinely produced nothing looks identical. Status, timing and credits remain accurate. + * @description When this run's trace content was deleted under the account's agent-trace retention window. Non-null means `input`, `output` and every step's and tool call's I/O are null **by design** and will never be available again — the run aged out, it did not fail. A tool call's `error` may be null as well, so a failed tool call can report its status without a message. Branch on this rather than on a null `output`: a run that genuinely produced nothing looks identical. Status, timing and credits remain accurate. */ trace_purged_at?: string | null; /** @@ -4187,12 +4481,18 @@ export interface components { tool_calls?: components["schemas"]["AgentRunToolCallResponse"][]; /** * Warnings - * @description Authoring problems the step ran into, whether or not it then failed, such as a file name selector that matched none of its source's files. + * @description Problems the step ran into, whether or not it then failed, such as a file name selector that matched none of its source's files, or a model that returned no answer. */ warnings?: string[] | null; }; /** AgentRunStreamRequest */ AgentRunStreamRequest: { + /** + * Include Reasoning + * @description Receive `stream_reasoning` events carrying the model's reasoning while it thinks. They are sent only for a `streaming_result` step whose author enabled `show_reasoning`, and never when a governance policy redacts that step. + * @default false + */ + include_reasoning: boolean; /** * Input * @description Input to provide to the agent upon running for agents with dynamic triggers. @@ -4200,12 +4500,12 @@ export interface components { input?: string | null; /** * Input Upload Id - * @description ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` — use that field to attach multiple files. May be combined with ``input``. Subject to the same per-batch attachment-selector validation as the non-streaming endpoint. + * @description ID of a previously uploaded file (via POST /{agent_id}/upload-input) to use as the run input for dynamic-input triggers. Mutually exclusive with ``input_upload_ids`` — use that field to attach multiple files. May be combined with ``input``. Must fit the trigger's ``accepted_attachments``, as on the non-streaming endpoint. */ input_upload_id?: string | null; /** * Input Upload Ids - * @description IDs of multiple previously uploaded files. See the non-streaming endpoint for full semantics, including per-batch selector validation (exact names, indexed references, and glob patterns must all be satisfied or the run is rejected with HTTP 400) and combining the batch with ``input`` prompt text. Max 20. + * @description IDs of multiple previously uploaded files. See the non-streaming endpoint for full semantics, including fitting the trigger's ``accepted_attachments`` (else HTTP 400) and combining the batch with ``input`` prompt text. Max 20. */ input_upload_ids?: string[] | null; /** @@ -4217,7 +4517,7 @@ export interface components { } | null; /** * Replay Of Run Id - * @description Re-run reusing a prior run's uploaded input files (re-resolved server-side from the source run, which must belong to this account and agent). A fresh upload batch takes precedence. + * @description Re-run reusing a prior run's uploaded input files (re-resolved server-side from the source run, which must belong to this account and agent). A fresh upload batch takes precedence. Files the trigger's ``accepted_attachments`` no longer accepts are left out. */ replay_of_run_id?: string | null; }; @@ -4381,6 +4681,11 @@ export interface components { sampling_config?: { [key: string]: unknown; } | null; + /** + * Trigger Id + * @description ID of the agent's trigger, for the `/agents/{agent_id}/triggers/{trigger_id}/…` endpoints such as `accepted-attachments` and `email-config`. + */ + trigger_id?: string | null; /** * Trigger Type * @description Trigger type for the agent. @@ -5173,6 +5478,64 @@ export interface components { /** Started At */ started_at?: string | null; }; + /** + * ContentAttachmentResponse + * @description A file attached to a content item. + */ + ContentAttachmentResponse: { + /** + * Content Type + * @description MIME type of the attached file. + */ + content_type: string; + /** + * Created At + * @description When the file was first attached. + */ + created_at: string; + /** + * Id + * @description The attachment's id, which the single-attachment endpoints take. + */ + id: string; + /** + * Indexed + * @description Whether indexing the file for search was asked for. + */ + indexed: boolean; + /** + * Indexing Error + * @description Why the file was not indexed, when `indexing_status` is `failed`. + */ + indexing_error: string | null; + /** + * Indexing Status + * @description `pending`, `completed` or `failed`; null when indexing was not asked for. Search finds the file only when `completed`. + */ + indexing_status: string | null; + /** + * Key + * @description The attachment's key, unique within the item. + */ + key: string; + /** + * Metadata + * @description What is known about the file beyond its bytes. An image extracted from a PDF carries its `page_number`, and `page_render: true` when it is a render of the whole page. An image or video from a web page carries `source_url` (the address it was fetched from), `position` (its place among the media the page listed, from 0) and, when the page gave one, `alt_text`. Empty for most files. A retrieval metadata filter matches these keys, except `alt_text`, which is indexed as the attachment's text. + */ + metadata: { + [key: string]: unknown; + }; + /** + * Size Bytes + * @description Size of the attached file in bytes. + */ + size_bytes: number; + /** + * Updated At + * @description When the attachment last changed. + */ + updated_at: string; + }; /** * ContentEmbeddingResponse * @description Response model for content embedding. @@ -5472,6 +5835,31 @@ export interface components { * @description Chunk size for content processing. */ chunk_size?: number | null; + /** + * Cloud Drive Connection Id + * @description Required for a cloud_drive source, and ignored on any other: the id of a connected drive, from GET /cloud-drives. + */ + cloud_drive_connection_id?: string | null; + /** + * Cloud Drive Content Types + * @description For a cloud_drive source: comma-separated MIME types a file must have to be indexed. Omit for no filter. + */ + cloud_drive_content_types?: string | null; + /** + * Cloud Drive Folder Path + * @description For a cloud_drive source: the folder to index, as a path inside the drive. Omit to index the connected drive's own folder. + */ + cloud_drive_folder_path?: string | null; + /** + * Cloud Drive Max File Mb + * @description For a cloud_drive source: files larger than this many megabytes are skipped. Omit for no limit of the source's own. + */ + cloud_drive_max_file_mb?: number | null; + /** + * Cloud Drive Path Pattern + * @description For a cloud_drive source: a glob a file's path must match to be indexed, such as `**\/*.pdf` or `/reports/*`. Omit for no filter. + */ + cloud_drive_path_pattern?: string | null; /** * Content Filter * @description Content filter type. @@ -5482,16 +5870,31 @@ export interface components { * @description Embedding dimensions override. */ dimensions?: number | null; + /** + * Document Images + * @description Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a text-only embedder, by the text in each image. Applies to documents added after it changes. Defaults to true; below Seclai-Version 2026-10-18 it defaults to false on a text-only embedder. On a website or RSS source it is ignored: `media_types` decides. + */ + document_images?: boolean | null; + /** + * Email Allowed Senders + * @description Required for an email source, and only valid there: the senders whose mail is stored. Each entry is a full address (news@example.com) or a bare domain (example.com), which also matches its sub-domains. Matched against the message's From address, which must pass DMARC. + */ + email_allowed_senders?: string[] | null; /** * Embedding Model * @description Embedding model override — a `model_type` from `GET /models/embedders`, which also reports each embedder's `supported_input_media`. Defaults to the platform embedder (`default_model_type` on that endpoint) when omitted. Indexing images or video requires an embedder that lists that modality. */ embedding_model?: string | null; + /** + * Feed Attachments + * @description Kinds of file listed beside a feed item's content to attach to the item and index, on an RSS source. Subset of ['enclosures', 'item_image', 'media_rss']; any other value is refused. None are attached unless chosen. + */ + feed_attachments?: string[] | null; /** @description Index mode for custom_index sources: fast_and_cheap (default), balanced, slow_and_thorough, or custom. */ index_mode?: components["schemas"]["SourceIndexMode"] | null; /** * Media Types - * @description Media kinds to extract from indexed content and embed as multi-modal KB chunks. Subset of ['images', 'video']. Only kinds the source's embedder can index are honored (see `supported_input_media` on GET /models/embedders); unsupported values are dropped. Omit / [] for text-only. + * @description Media kinds in a web page's main content to attach to the page's item and index, on a website or RSS source. Subset of ['images', 'video']. From `Seclai-Version: 2026-10-13` any other value, and any kind on another source type, is refused with a 400; older versions drop an unknown value and store the rest. A kind the source's embedder cannot index is stored and not indexed (see `supported_input_media` on GET /models/embedders). 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files. Applies to pages and documents added after it is set. */ media_types?: string[] | null; /** @@ -5511,7 +5914,7 @@ export interface components { polling_action?: string | null; /** * Polling Max Items - * @description Max items per poll. + * @description The most new feed items a scheduled poll takes. Read for RSS feeds only: from Seclai-Version 2026-10-19 any other source type rejects it with 400. Earlier versions store it there. An email source rejects it at every version. */ polling_max_items?: number | null; /** @@ -5521,7 +5924,7 @@ export interface components { retention?: number | null; /** * Source Type - * @description Source type: rss, website, or custom_index. The legacy value 'file_uploads' is accepted as an alias for custom_index. + * @description Source type: rss_feed, website, custom_index, cloud_drive or email. The legacy value 'file_uploads' is accepted as an alias for custom_index. */ source_type: string; /** @@ -5717,6 +6120,69 @@ export interface components { /** Vanity Plan Names */ vanity_plan_names?: string[]; }; + /** + * EmailSourceRejectionListResponse + * @description A page of mail an email content source refused. + */ + EmailSourceRejectionListResponse: { + /** Data */ + data: components["schemas"]["EmailSourceRejectionResponse"][]; + pagination: components["schemas"]["PaginationResponse"]; + }; + /** + * EmailSourceRejectionResponse + * @description Mail an email content source refused: who sent it and why, never what + * it said. + */ + EmailSourceRejectionResponse: { + /** + * Auth Verdicts + * @description The SPF, DKIM and DMARC verdicts reported for the message. + */ + auth_verdicts?: { + [key: string]: string; + }; + /** + * Authenticated + * @description Whether the message passed DMARC, which is what authenticates its From address. Adding an unauthenticated sender to the allowed senders does not let its mail in. + */ + authenticated: boolean; + /** + * Created At + * @description When the mail was refused. + */ + created_at: string; + /** + * From Address + * @description The address in the message's From line, which the source's allowed senders are matched against. Null when no single From address could be read from the message unambiguously. + */ + from_address?: string | null; + /** + * Id + * @description Unique identifier of the refusal. + */ + id: string; + /** + * Reason + * @description Why it was refused: sender_not_allowed, unauthenticated_sender, unreadable_from, sender_blocked, spam, virus, unsafe_content, rate_limited, account_not_chargeable or empty_message; or, for a message the source received before, what became of the earlier one: repeat_stored, repeat_held, repeat_deleted or repeat_in_progress. + */ + reason: string; + /** + * Recipient + * @description The source address it was sent to. + */ + recipient: string; + /** + * Sender + * @description The envelope sender. For bulk mail this is the delivery provider's bounce address, not the From address. + */ + sender: string; + /** + * Sender Ip + * @description IP address the mail came from. + */ + sender_ip: string | null; + }; /** * EmailTriggerConfigResponse * @description An EMAIL_RECEIVED trigger's resolved address(es) and config. @@ -5748,6 +6214,11 @@ export interface components { * @default true */ email_require_sender_auth: boolean; + /** + * Email Run On Attachment Mismatch + * @default false + */ + email_run_on_attachment_mismatch: boolean; /** * Trigger Id * Format: uuid @@ -6044,7 +6515,7 @@ export interface components { EvaluationResultSummaryResponse: { /** * Average Score - * @description Mean score across all evaluated results, or null if none. + * @description Mean score of the final passed and failed results, or null if none. On /api before Seclai-Version 2026-10-21 it averages every final result's stored score, `error` included. */ average_score?: number | null; /** Error */ @@ -6351,7 +6822,7 @@ export interface components { GenerateAgentStepsResponse: { /** * Agent Config - * @description Suggested agent-level configuration, if any. + * @description Suggested agent-level configuration, if any. For an email_received agent it may carry `email_run_on_attachment_mismatch`, which the caller applies through the trigger's email-config endpoint. For a dynamic_input or email_received agent it may carry `accepted_attachments`, which the caller passes with the steps to `PUT /agents/{agent_id}/definition` so both save together. */ agent_config?: { [key: string]: unknown; @@ -6701,7 +7172,7 @@ export interface components { }; /** * InsufficientCreditsDetail - * @description ``detail`` body for a 402 ``insufficient_credits`` response. + * @description ``error`` body of a 402 ``insufficient_credits`` response. */ InsufficientCreditsDetail: { /** @@ -6710,11 +7181,11 @@ export interface components { */ account_id: string; /** - * Error + * Code * @description Stable machine-readable error code. * @constant */ - error: "insufficient_credits"; + code: "insufficient_credits"; /** * Message * @description Human-readable explanation. @@ -6724,9 +7195,11 @@ export interface components { /** * InsufficientCreditsResponse * @description 402 envelope returned when the account has exhausted its credits. + * + * The wire shape ``http_exception_handler`` and ``insufficient_credits_exception_handler`` send. */ InsufficientCreditsResponse: { - detail: components["schemas"]["InsufficientCreditsDetail"]; + error: components["schemas"]["InsufficientCreditsDetail"]; }; JsonValue: unknown; /** @@ -7396,6 +7869,14 @@ export interface components { message: string; }; }; + /** SetAcceptedAttachmentsRequest */ + SetAcceptedAttachmentsRequest: { + /** + * Accepted Attachments + * @description The input attachments the trigger accepts; ``null`` accepts any files (one attachment named ``files``). Only ``dynamic_input`` and ``email_received`` triggers take files. + */ + accepted_attachments: components["schemas"]["AcceptedAttachmentSlot"][] | null; + }; /** * SetAutoBlockModeRequest * @description Set the account's governance auto-block mode (shared REST request). @@ -7404,9 +7885,37 @@ export interface components { /** Mode */ mode: string; }; - /** SolutionSourceConnectionResponse */ - SolutionSourceConnectionResponse: { - /** + /** + * SkippedAttachmentReason + * @enum {string} + */ + SkippedAttachmentReason: "displayed_in_body" | "over_cap" | "no_filename" | "undecodable"; + /** + * SkippedAttachmentResponse + * @description A part of an email that was not stored as an attachment. + */ + SkippedAttachmentResponse: { + /** + * Content Type + * @description The part's declared media type. + */ + content_type: string; + /** + * Filename + * @description The file name the part is listed under; null when it had none. + */ + filename: string | null; + /** @description Why the part was not stored. */ + reason: components["schemas"]["SkippedAttachmentReason"]; + /** + * Size Bytes + * @description Decoded size in bytes. + */ + size_bytes: number | null; + }; + /** SolutionSourceConnectionResponse */ + SolutionSourceConnectionResponse: { + /** * Id * Format: uuid */ @@ -7554,20 +8063,26 @@ export interface components { error: string | null; /** * Extracted Media Capped - * @description True when extraction stopped with media still unread, so the item references more media than was indexed and media search will not match anything past the cut. Two causes: a web page that ran out of the budget for fetching remote assets, or a container that could not be read to the end (a truncated or hostile archive). An uploaded document that reads cleanly is never capped, however much media it holds — there is no limit on that. + * @description True when extraction stopped with media still unread, so the item references more media than was attached and media search will not match anything past the cut. The cause is a web page that ran out of the budget for fetching remote assets or listed more media than is recorded, or a web page or document that could not be read to the end. * @default false */ extracted_media_capped: boolean; /** * Extracted Media Count - * @description Number of embedded images / videos extracted from inside this item and indexed as their own chunks. There is no limit on this — a document contributes as many as it holds. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container, or found nothing. Treat null as 'unknown', never as zero. + * @description Number of images / videos in this web page's main content, or of images inside this PDF or Office document, that were attached to the item on this source; a file over the per-file size limit, listed as a failed attachment, is not counted. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container or this source's settings, or found nothing. Treat null as 'unknown', never as zero. */ extracted_media_count?: number | null; /** * Extracted Media Limit - * @description The bound that was reached, when extracted_media_capped is true and the stop was a bound — a number of fetch attempts, or a number of seconds. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired. + * @description The bound that was reached, when extracted_media_capped is true and the stop was a bound — a number of fetch attempts, of seconds, of bytes, or of media listed. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired. */ extracted_media_limit?: number | null; + /** + * Held For Review + * @description An ENFORCE governance policy blocked this item at import. It is held for review and is not retrievable: resolving its blocking evaluations releases it into the source, and it is purged when the hold window ends. + * @default false + */ + held_for_review: boolean; /** * Indexed At * @description Timestamp when the item finished indexing and became retrievable. `null` until then. @@ -7703,6 +8218,31 @@ export interface components { * @description Chunk size for content processing. */ chunk_size?: number | null; + /** + * Cloud Drive Connection Id + * @description For a cloud_drive source: the id of the connected drive it indexes. Null for every other source type. + */ + cloud_drive_connection_id?: string | null; + /** + * Cloud Drive Content Types + * @description For a cloud_drive source: the comma-separated MIME types a file must have to be indexed. Null when there is no filter. + */ + cloud_drive_content_types?: string | null; + /** + * Cloud Drive Folder Path + * @description For a cloud_drive source: the folder it indexes. Null when it indexes the connected drive's own folder. + */ + cloud_drive_folder_path?: string | null; + /** + * Cloud Drive Max File Mb + * @description For a cloud_drive source: the size in megabytes above which a file is skipped. Null when the source sets no limit of its own. + */ + cloud_drive_max_file_mb?: number | null; + /** + * Cloud Drive Path Pattern + * @description For a cloud_drive source: the glob a file's path must match to be indexed. Null when there is none. + */ + cloud_drive_path_pattern?: string | null; /** * Content Count * @description Number of content items associated with the source connection. @@ -7724,6 +8264,22 @@ export interface components { * @description Dimensions of the embedding model. */ dimensions?: number | null; + /** + * Document Images + * @description Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a source that follows no web pages and has a text-only embedder, by the text in each image. Applies to documents added after it changes. On a website or RSS source it reports whether `media_types` holds 'images', and the images are attached only when the source's embedder indexes images. + * @default true + */ + document_images: boolean; + /** + * Email Address + * @description For an email source: the address to send mail to. Null for every other source type. + */ + email_address?: string | null; + /** + * Email Allowed Senders + * @description For an email source: the addresses and domains whose mail is stored. Null for every other source type. + */ + email_allowed_senders?: string[] | null; /** * Embedding Model * @description Embedding model used for the source connection. @@ -7734,6 +8290,11 @@ export interface components { * @description Type of the embedding model. */ embedding_model_type?: string | null; + /** + * Feed Attachments + * @description Kinds of file listed beside a feed item's content that an RSS source attaches to the item and indexes (subset of ['enclosures', 'item_image', 'media_rss']). + */ + feed_attachments?: string[]; /** * Free Retention Days * @description Number of days content is stored for free before billing applies. @@ -7754,7 +8315,7 @@ export interface components { index_mode?: components["schemas"]["SourceIndexMode"] | null; /** * Media Types - * @description Media kinds extracted from indexed content and embedded as multi-modal KB chunks (subset of ['images', 'video']). Empty = text-only. + * @description Media kinds in a web page's main content that are attached to the page's item and indexed (subset of ['images', 'video']). On a website or RSS source 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files. */ media_types?: string[]; /** @@ -7779,7 +8340,7 @@ export interface components { polling_action: string | null; /** * Polling Max Items - * @description Maximum items to poll for the source connection. + * @description The most new feed items a scheduled poll takes. Read for RSS feeds only. */ polling_max_items: number | null; /** @@ -7989,6 +8550,8 @@ export interface components { passed: boolean; /** Score */ score: number; + /** @description `passed`, `failed`, or `error` when the evaluator returned no verdict. */ + status: components["schemas"]["EvaluationStatus"]; }; /** UnlinkResourcesRequest */ UnlinkResourcesRequest: { @@ -8005,6 +8568,11 @@ export interface components { }; /** UpdateAgentDefinitionRequest */ UpdateAgentDefinitionRequest: { + /** + * Accepted Attachments + * @description When given, declared on the main branch's file-taking triggers in the same save, so the steps may read its slots as `{{agent.attachments.}}`; omitted, the triggers keep theirs. + */ + accepted_attachments?: components["schemas"]["AcceptedAttachmentSlot"][] | null; /** * Definition * @description The full agent definition (name, description, tags, steps). Steps form a tree workflow. Each step has a `step_type`, `id`, `name`, and type-specific config. Content enrichment steps (write_metadata, write_content_attachment, load_content_attachment, load_content) require content-triggered agents. @@ -8190,9 +8758,44 @@ export interface components { * @description Request body for updating a content source. */ UpdateSourceBody: { + /** + * Cloud Drive Content Types + * @description For a cloud_drive source: comma-separated MIME types a file must have to be indexed. Send an empty string to clear it; omit to leave it unchanged. + */ + cloud_drive_content_types?: string | null; + /** + * Cloud Drive Folder Path + * @description For a cloud_drive source: the folder to index, as a path inside the drive. Send an empty string to index the connected drive's own folder; omit to leave it unchanged. + */ + cloud_drive_folder_path?: string | null; + /** + * Cloud Drive Max File Mb + * @description For a cloud_drive source: files larger than this many megabytes are skipped. Send 0 to clear the source's own limit; omit to leave it unchanged. + */ + cloud_drive_max_file_mb?: number | null; + /** + * Cloud Drive Path Pattern + * @description For a cloud_drive source: a glob a file's path must match to be indexed, such as `**\/*.pdf` or `/reports/*`. Send an empty string to clear it; omit to leave it unchanged. + */ + cloud_drive_path_pattern?: string | null; + /** + * Document Images + * @description Whether the images inside PDF, DOCX, PPTX and XLSX files are attached to the item and indexed; on a text-only embedder, by the text in each image. Applies to documents added after it changes. Omit the field to leave it unchanged. On a website or RSS source it is ignored: `media_types` decides. + */ + document_images?: boolean | null; + /** + * Email Allowed Senders + * @description For an email source: replaces the allowed senders. Each entry is a full address or a bare domain. The list cannot be emptied. Omit to leave it unchanged. + */ + email_allowed_senders?: string[] | null; + /** + * Feed Attachments + * @description Kinds of file listed beside a feed item's content to attach to the item and index, on an RSS source. Subset of ['enclosures', 'item_image', 'media_rss']; any other value is refused. [] attaches none. Applies to items added after it changes. Omit the field to leave it unchanged. + */ + feed_attachments?: string[] | null; /** * Media Types - * @description Media kinds to extract from indexed content and embed as multi-modal KB chunks. Subset of ['images', 'video']. Only kinds the source's embedder can index are honored (see `supported_input_media` on GET /models/embedders); unsupported values are dropped. [] disables media extraction (text-only). + * @description Media kinds in a web page's main content to attach to the page's item and index, on a website or RSS source. Subset of ['images', 'video']. From `Seclai-Version: 2026-10-13` any other value, and any kind on another source type, is refused with a 400; older versions drop an unknown value and store the rest. A kind the source's embedder cannot index is stored and not indexed (see `supported_input_media` on GET /models/embedders). [] attaches no media from web pages. 'images' also covers the images inside PDF, DOCX, PPTX and XLSX files. Applies to pages and documents added after it changes. */ media_types?: string[] | null; /** @@ -8455,6 +9058,11 @@ export interface components { }; /** CreateAgentRequest */ routers__api__agents__CreateAgentRequest: { + /** + * Accepted Attachments + * @description The input attachments the trigger accepts. Omitted, the ``agent_definition`` trigger's declaration is kept when the export carries one and both trigger types take files; otherwise a dynamic_input or email_received trigger accepts any files (one attachment named ``files``), and any other trigger none. + */ + accepted_attachments?: components["schemas"]["AcceptedAttachmentSlot"][] | null; /** * Agent Definition * @description Optional payload in the same format produced by GET /agents/{id}/export. When provided, replaces any template-derived workflow and pre-fills metadata/trigger fields the request does not specify explicitly. Validation errors include line/column references against a canonical pretty-printed echo of the supplied payload. @@ -8540,6 +9148,11 @@ export interface components { * @description When true (default for new triggers), the envelope sender must pass SPF or DMARC even on an open inbox (no allowlist); unauthenticated, spoofable mail is rejected. Set false to accept fully unauthenticated mail on an open inbox. */ require_sender_auth?: boolean | null; + /** + * Run On Attachment Mismatch + * @description When true (default false), an email whose attachments don't fit what the agent expects still runs: files the agent can't take are left out and the problems are listed in the `email_attachment_issues` run metadata. When false, the run fails. + */ + run_on_attachment_mismatch?: boolean | null; }; /** UpdateAgentRequest */ routers__api__agents__UpdateAgentRequest: { @@ -8782,6 +9395,89 @@ export interface components { */ subscribed: boolean; }; + /** + * ContentAttachmentDetailResponse + * @description One attached file, with the text indexed from it. + */ + routers__api__contents__ContentAttachmentDetailResponse: { + /** + * Content Type + * @description MIME type of the attached file. + */ + content_type: string; + /** + * Created At + * @description When the file was first attached. + */ + created_at: string; + /** + * File Withheld + * @description Why the file's bytes are not served, or null when they are: `blocked_by_governance_policy`, `redacted_by_governance_policy` (any text below is the redacted text), or `pending_screening`. + */ + file_withheld: string | null; + /** + * Id + * @description The attachment's id, which the single-attachment endpoints take. + */ + id: string; + /** + * Indexed + * @description Whether indexing the file for search was asked for. + */ + indexed: boolean; + /** + * Indexing Error + * @description Why the file was not indexed, when `indexing_status` is `failed`. + */ + indexing_error: string | null; + /** + * Indexing Status + * @description `pending`, `completed` or `failed`; null when indexing was not asked for. Search finds the file only when `completed`. + */ + indexing_status: string | null; + /** + * Key + * @description The attachment's key, unique within the item. + */ + key: string; + /** + * Metadata + * @description What is known about the file beyond its bytes. An image extracted from a PDF carries its `page_number`, and `page_render: true` when it is a render of the whole page. An image or video from a web page carries `source_url` (the address it was fetched from), `position` (its place among the media the page listed, from 0) and, when the page gave one, `alt_text`. Empty for most files. A retrieval metadata filter matches these keys, except `alt_text`, which is indexed as the attachment's text. + */ + metadata: { + [key: string]: unknown; + }; + /** + * Size Bytes + * @description Size of the attached file in bytes. + */ + size_bytes: number; + /** + * Text Content + * @description The requested range of the text the file is indexed by; null when the file has no completed index or was indexed without text. + */ + text_content: string | null; + /** Text Content End */ + text_content_end: number; + /** Text Content Start */ + text_content_start: number; + /** Text Content Total Length */ + text_content_total_length: number; + /** + * Updated At + * @description When the attachment last changed. + */ + updated_at: string; + }; + /** + * ContentAttachmentsListResponse + * @description Response model for a content item's attachments. + */ + routers__api__contents__ContentAttachmentsListResponse: { + /** Data */ + data: components["schemas"]["ContentAttachmentResponse"][]; + pagination: components["schemas"]["PaginationResponse"]; + }; /** * ContentDetailResponse * @description Response model for content detail. @@ -8834,18 +9530,18 @@ export interface components { error: string | null; /** * Extracted Media Capped - * @description True when extraction stopped with media still unread, so the item references more media than was indexed and media search will not match anything past the cut. Two causes: a web page that ran out of the budget for fetching remote assets, or a container that could not be read to the end (a truncated or hostile archive). An uploaded document that reads cleanly is never capped, however much media it holds — there is no limit on that. + * @description True when extraction stopped with media still unread, so the item references more media than was attached and media search will not match anything past the cut. The cause is a web page that ran out of the budget for fetching remote assets or listed more media than is recorded, or a web page or document that could not be read to the end. * @default false */ extracted_media_capped: boolean; /** * Extracted Media Count - * @description Number of embedded images / videos extracted from inside this item and indexed as their own chunks. There is no limit on this — a document contributes as many as it holds. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container, or found nothing. Treat null as 'unknown', never as zero. + * @description Number of images / videos in this web page's main content, or of images inside this PDF or Office document, that were attached to the item on this source; a file over the per-file size limit, listed as a failed attachment, is not counted. Null when there is no media record for the item: the extraction pass has not run, does not apply to this container or this source's settings, or found nothing. Treat null as 'unknown', never as zero. */ extracted_media_count?: number | null; /** * Extracted Media Limit - * @description The bound that was reached, when extracted_media_capped is true and the stop was a bound — a number of fetch attempts, or a number of seconds. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired. + * @description The bound that was reached, when extracted_media_capped is true and the stop was a bound — a number of fetch attempts, of seconds, of bytes, or of media listed. Null when extraction was not capped, or when it stopped because the container could not be read rather than because a bound fired. */ extracted_media_limit?: number | null; /** @@ -8870,6 +9566,11 @@ export interface components { * @description Timestamp when the content was pulled. */ pulled_at: string; + /** + * Skipped Attachments + * @description Parts of an email delivered to an email content source that were not stored as attachments of this item, each with the reason: displayed_in_body (an image the message body shows, such as a signature logo), over_cap (beyond the per-message attachment limit), no_filename, or undecodable. size_bytes is null for a part that was never decoded. Empty for every other item. + */ + skipped_attachments?: components["schemas"]["SkippedAttachmentResponse"][]; /** * Source Connection Content Version Id * @description ID of the source connection content version. @@ -9602,7 +10303,7 @@ export interface components { content_version_id: string | null; /** * Embedder Warning - * @description Set when the file is non-text but the source's embedder is text-only — indexing will rely on OCR / transcription and may produce a FAILED row if no text can be extracted. + * @description Set when a file that is not text is indexed from its extracted text alone rather than embedded whole: the item is FAILED if no text can be extracted. Says so when the images inside a document are attached to the item and indexed as well. */ embedder_warning?: string | null; /** @@ -9819,6 +10520,11 @@ export interface components { * @description Per-mode rollup for evaluation activity. */ schemas__v1__agent_evaluations__NonManualEvaluationModeStatResponse: { + /** + * Error + * @description Results whose evaluator returned no verdict. + */ + error: number; /** Failed */ failed: number; /** Failure Rate */ @@ -9841,6 +10547,11 @@ export interface components { schemas__v1__agent_evaluations__NonManualEvaluationSummaryResponse: { /** By Mode */ by_mode: components["schemas"]["schemas__v1__agent_evaluations__NonManualEvaluationModeStatResponse"][]; + /** + * Error + * @description Results whose evaluator returned no verdict. + */ + error: number; /** Failed */ failed: number; /** Failure Rate */ @@ -12250,6 +12961,58 @@ export interface operations { }; }; }; + set_accepted_attachments_api_api_agents__agent_id__triggers__trigger_id__accepted_attachments_put: { + parameters: { + query?: never; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + agent_id: string; + trigger_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["SetAcceptedAttachmentsRequest"]; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["AcceptedAttachmentsResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; set_email_trigger_config_api_api_agents__agent_id__triggers__trigger_id__email_config_put: { parameters: { query?: never; @@ -13964,6 +14727,239 @@ export interface operations { }; }; }; + list_content_attachments_api_contents__source_connection_content_version__attachments_get: { + parameters: { + query?: { + page?: number; + limit?: number; + }; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + source_connection_content_version: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["routers__api__contents__ContentAttachmentsListResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; + get_content_attachment_api_contents__source_connection_content_version__attachments__attachment_id__get: { + parameters: { + query?: { + start?: number; + end?: number; + }; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + source_connection_content_version: string; + attachment_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["routers__api__contents__ContentAttachmentDetailResponse"]; + }; + }; + /** @description The account has no credits left (`error.code` is `insufficient_credits`). */ + 402: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; + list_content_attachment_embeddings_api_contents__source_connection_content_version__attachments__attachment_id__embeddings_get: { + parameters: { + query?: { + page?: number; + limit?: number; + }; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + source_connection_content_version: string; + attachment_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["routers__api__contents__ContentEmbeddingsListResponse"]; + }; + }; + /** @description The account has no credits left (`error.code` is `insufficient_credits`). */ + 402: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; + get_content_attachment_file_api_contents__source_connection_content_version__attachments__attachment_id__file_get: { + parameters: { + query?: never; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + source_connection_content_version: string; + attachment_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The file's bytes. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/octet-stream": string; + "application/pdf": string; + "audio/*": string; + "image/*": string; + "text/plain": string; + "video/*": string; + }; + }; + /** @description The account has no credits left (`error.code` is `insufficient_credits`). */ + 402: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description The file is withheld; `error.code` says why. */ + 403: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; list_content_embeddings_api_contents__source_connection_content_version__embeddings_get: { parameters: { query?: { @@ -17861,6 +18857,58 @@ export interface operations { }; }; }; + list_email_source_rejections_api_api_sources__source_connection_id__email_rejections_get: { + parameters: { + query?: { + /** @description Page number. */ + page?: number; + /** @description Items per page. */ + limit?: number; + }; + header?: { + /** @description Target a different organization account (OAuth only). When omitted, the user's default account is used. Ignored for API key authentication — the key's account is always used. */ + "X-Account-Id"?: components["parameters"]["X-Account-Id"]; + /** @description Opt into dated, backward-incompatible API changes (format YYYY-MM-DD). When omitted, the account's pinned baseline version is used and responses keep their legacy shapes. Send a date on or after a change's release to adopt it — e.g. `2026-07-27` enables rejection of undeclared query parameters (422) and the canonical `{data, pagination}` envelope (pagination = `{page, limit, total, pages, has_next, has_prev}`) on every list endpoint that previously returned a bare array, a flat `{data, total, page, limit}`, a `{configs, total}`, or another per-resource key. */ + "Seclai-Version"?: components["parameters"]["Seclai-Version"]; + }; + path: { + source_connection_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["EmailSourceRejectionListResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + /** @description A dependency is unavailable. `database_unavailable` is temporary (for example routine maintenance) and carries a `Retry-After` header, after which the request can be retried unchanged. `vector_store_unavailable` means the vector store backing an embeddings operation is not configured; it carries no `Retry-After` because it does not clear without an operator. */ + 503: { + headers: { + /** @description Seconds to wait before retrying. Sent only with `database_unavailable`. */ + "Retry-After"?: number; + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ServiceUnavailableError"]; + }; + }; + }; + }; get_source_embedding_migration_api_sources__source_connection_id__embedding_migration_get: { parameters: { query?: never; diff --git a/src/types.ts b/src/types.ts index 68f23ad..2f6bbc4 100644 --- a/src/types.ts +++ b/src/types.ts @@ -58,14 +58,62 @@ export type AgentExportResponse = components["schemas"]["AgentExportResponse"]; /** Summary of an agent (returned on create/update). */ export type AgentSummaryResponse = components["schemas"]["AgentSummaryResponse"]; -/** Request body for creating an agent. */ -export type CreateAgentRequest = components["schemas"]["routers__api__agents__CreateAgentRequest"]; +/** + * Request body for creating an agent. + * + * `accepted_attachments` takes {@link AcceptedAttachmentSlotInput}, so a slot's + * server-defaulted `min` can be omitted. + */ +export type CreateAgentRequest = Omit< + components["schemas"]["routers__api__agents__CreateAgentRequest"], + "accepted_attachments" +> & { accepted_attachments?: AcceptedAttachmentSlotInput[] | null }; /** Request body for updating an agent. */ export type UpdateAgentRequest = components["schemas"]["routers__api__agents__UpdateAgentRequest"]; -/** Request body for updating an agent definition (steps, model, etc.). */ -export type UpdateAgentDefinitionRequest = components["schemas"]["UpdateAgentDefinitionRequest"]; +/** + * Request body for updating an agent definition (steps, model, etc.). + * + * `accepted_attachments` takes {@link AcceptedAttachmentSlotInput}, so a slot's + * server-defaulted `min` can be omitted. + */ +export type UpdateAgentDefinitionRequest = Omit< + components["schemas"]["UpdateAgentDefinitionRequest"], + "accepted_attachments" +> & { accepted_attachments?: AcceptedAttachmentSlotInput[] | null }; + +/** + * One input attachment a trigger accepts: a named slot that a run's files are + * assigned to before any step runs. Steps reference it as + * `{{agent.attachments.}}`. + */ +export type AcceptedAttachmentSlot = components["schemas"]["AcceptedAttachmentSlot"]; + +/** + * An {@link AcceptedAttachmentSlot} as written: `min` has a server-side + * default of `0` and can be omitted — the generated type marks + * it required only because the schema declares a default. + */ +export type AcceptedAttachmentSlotInput = Omit & { min?: number }; + +/** + * Request body for {@link Seclai.setAcceptedAttachments}: the full list of + * accepted attachments, with each slot's server-defaulted `min` optional. + */ +export type SetAcceptedAttachmentsInput = Omit< + components["schemas"]["SetAcceptedAttachmentsRequest"], + "accepted_attachments" +> & { accepted_attachments: AcceptedAttachmentSlotInput[] | null }; + +/** + * Request body for declaring the input attachments a trigger accepts. The same + * type as {@link SetAcceptedAttachmentsInput}, so a slot's `min` can be omitted. + */ +export type SetAcceptedAttachmentsRequest = SetAcceptedAttachmentsInput; + +/** The input attachments a trigger now accepts. */ +export type AcceptedAttachmentsResponse = components["schemas"]["AcceptedAttachmentsResponse"]; /** Request body for previewing an agent_definition import (dry-run validation). */ export type AgentImportPreviewRequest = components["schemas"]["routers__api__agents__AgentImportPreviewRequest"]; @@ -126,6 +174,12 @@ export type SetAutoBlockModeRequest = components["schemas"]["SetAutoBlockModeReq /** An inbound email that was discarded before running an agent. */ export type InboundEmailRejectionResponse = components["schemas"]["InboundEmailRejectionResponse"]; +/** Mail an email content source refused: who sent it and why, never its subject or body. */ +export type EmailSourceRejectionResponse = components["schemas"]["EmailSourceRejectionResponse"]; + +/** A page of an email source's refused mail, under `data` with `pagination`. */ +export type EmailSourceRejectionListResponse = components["schemas"]["EmailSourceRejectionListResponse"]; + /** Account-wide inbound-email overload state (breaker paused + queued backlog size). */ export type InboundEmailStatusResponse = components["schemas"]["InboundEmailStatusResponse"]; @@ -140,8 +194,14 @@ export type ResumeInboundResponse = components["schemas"]["ResumeInboundResponse /** Request body for starting an agent run. */ export type AgentRunRequest = components["schemas"]["AgentRunRequest"]; -/** Request body for starting an agent run in streaming mode (SSE). */ -export type AgentRunStreamRequest = components["schemas"]["AgentRunStreamRequest"]; +/** + * Request body for starting an agent run in streaming mode (SSE). + * + * `include_reasoning` has a server-side default of `false` and stays optional — + * the generated type marks it required only because the schema declares a default. + */ +export type AgentRunStreamRequest = Omit & + Partial>; /** Response body describing an agent run. */ export type AgentRunResponse = components["schemas"]["AgentRunResponse"]; @@ -377,8 +437,19 @@ export type NonManualEvaluationModeStatResponse = components["schemas"]["schemas /** Request for testing a draft evaluation. */ export type TestDraftEvaluationRequest = components["schemas"]["TestDraftEvaluationRequest"]; -/** Response from testing a draft evaluation. */ -export type TestDraftEvaluationResponse = components["schemas"]["TestDraftEvaluationResponse"]; +/** + * Response from testing a draft evaluation. When `status` is `error` (no + * verdict), `score` and `passed` are `null` with `apiVersion` `2026-10-21` or + * later, and 0.5 and `false` below it; the spec documents only the latter. + */ +export type TestDraftEvaluationResponse = Omit< + components["schemas"]["TestDraftEvaluationResponse"], + "status" | "score" | "passed" +> & + ( + | { status: Exclude; score: number; passed: boolean } + | { status: "error"; score: number | null; passed: boolean | null } + ); /** Paginated list of runs compatible with a specific evaluation criteria. */ export type CompatibleRunListResponse = VersionedList; @@ -550,6 +621,21 @@ export type ContentEmbeddingsListResponse = components["schemas"]["routers__api_ /** Individual content embedding. */ export type ContentEmbeddingResponse = components["schemas"]["ContentEmbeddingResponse"]; +/** A file attached to a content item, with whether it is indexed and, if indexing failed, why. */ +export type ContentAttachmentResponse = components["schemas"]["ContentAttachmentResponse"]; + +/** A page of a content item's attachments, under `data` with `pagination`. */ +export type ContentAttachmentsListResponse = components["schemas"]["routers__api__contents__ContentAttachmentsListResponse"]; + +/** One content attachment with its indexing status, metadata and a range of the text it is indexed by. */ +export type ContentAttachmentDetailResponse = components["schemas"]["routers__api__contents__ContentAttachmentDetailResponse"]; + +/** A file on an email that was not attached to the content item, with the reason. */ +export type SkippedAttachmentResponse = components["schemas"]["SkippedAttachmentResponse"]; + +/** Why an email's file was not attached: `displayed_in_body`, `over_cap`, `no_filename` or `undecodable`. */ +export type SkippedAttachmentReason = components["schemas"]["SkippedAttachmentReason"]; + /** Upload response for content replacement uploads. */ export type ContentFileUploadResponse = components["schemas"]["routers__api__contents__FileUploadResponse"]; @@ -765,7 +851,7 @@ export type DmarcFailingSourceResponse = components["schemas"]["DmarcFailingSour /** 402 envelope returned when an account has exhausted its credits. */ export type InsufficientCreditsResponse = components["schemas"]["InsufficientCreditsResponse"]; -/** `detail` body of an {@link InsufficientCreditsResponse} (error code, message, and account id). */ +/** `error` body of an {@link InsufficientCreditsResponse} (`code`, message, and account id). */ export type InsufficientCreditsDetail = components["schemas"]["InsufficientCreditsDetail"]; // ─── Sources (enums) ───────────────────────────────────────────────────────── diff --git a/src/versions.ts b/src/versions.ts index 98914ad..e24e4d4 100644 --- a/src/versions.ts +++ b/src/versions.ts @@ -16,10 +16,16 @@ export const SeclaiApiVersion = { V2026_09_28: "2026-09-28", V2026_09_30: "2026-09-30", V2026_10_03: "2026-10-03", + V2026_10_05: "2026-10-05", + V2026_10_13: "2026-10-13", + V2026_10_16: "2026-10-16", + V2026_10_18: "2026-10-18", + V2026_10_19: "2026-10-19", + V2026_10_21: "2026-10-21", /** Baseline applied to an unpinned, header-less caller. */ Default: "2026-07-01", /** Newest version known to this SDK release. May lag the server. */ - Latest: "2026-10-03", + Latest: "2026-10-21", } as const; /** diff --git a/tests/client.test.ts b/tests/client.test.ts index 2b3bc6e..55d9e67 100644 --- a/tests/client.test.ts +++ b/tests/client.test.ts @@ -10,6 +10,7 @@ import { SeclaiStreamingError, SeclaiApiVersion, } from "../src/index"; +import type { SetAcceptedAttachmentsRequest } from "../src/index"; import { parseIni, isTokenValid } from "../src/auth"; type RecordedRequest = { @@ -82,6 +83,17 @@ function makeSseResponse( }); } +/** Like fetch, never answers: rejects with an AbortError once `init.signal` aborts. */ +function hangUntilAborted(_input: RequestInfo | URL, init?: RequestInit): Promise { + return new Promise((_resolve, reject) => { + const signal = init?.signal; + if (!signal) return; + const abort = () => reject(new DOMException("The operation was aborted.", "AbortError")); + if (signal.aborted) abort(); + else signal.addEventListener("abort", abort, { once: true }); + }); +} + function makeClient( handler: (req: RecordedRequest) => Response | Promise, extra: Partial[0]> = {}, @@ -445,6 +457,29 @@ describe("Streaming", () => { expect(events[2].event).toBe("done"); expect((events[2].data as any).status).toBe("completed"); }); + + test("runStreamingAgent sends include_reasoning and keeps it optional", async () => { + const bodies: unknown[] = []; + const client = makeClient((req) => { + bodies.push(JSON.parse(req.bodyText!)); + return makeSseResponse([`event: done\ndata: ${JSON.stringify({ run_id: "run_1" })}\n\n`], { signal: req.signal }); + }); + // No cast: `include_reasoning` is server-defaulted and must not be required. + for await (const _ of client.runStreamingAgent("ag_1", { input: "hi" })) void _; + for await (const _ of client.runStreamingAgent("ag_1", { input: "hi", include_reasoning: true })) void _; + expect(bodies).toEqual([{ input: "hi" }, { input: "hi", include_reasoning: true }]); + }); + test("runStreamingAgentAndWait does not send include_reasoning from an untyped caller", async () => { + const bodies: unknown[] = []; + const client = makeClient((req) => { + bodies.push(JSON.parse(req.bodyText!)); + return makeSseResponse([`event: done\ndata: ${JSON.stringify({ run_id: "run_1" })}\n\n`], { signal: req.signal }); + }); + // A plain-JS caller can pass the key the TypeScript signature omits. + const body = { input: "hi", include_reasoning: true } as unknown as { input: string }; + await client.runStreamingAgentAndWait("ag_1", body); + expect(bodies).toEqual([{ input: "hi" }]); + }); }); // ───────────────────────────────────────────────────────────────────────────── @@ -581,6 +616,61 @@ describe("Memory Banks", () => { // ───────────────────────────────────────────────────────────────────────────── describe("Sources", () => { + test("listEmailSourceRejections sends GET /sources/:id/email-rejections with page/limit", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("GET"); + expect(u.pathname).toBe("/sources/src_1/email-rejections"); + expect(u.searchParams.get("page")).toBe("3"); + expect(u.searchParams.get("limit")).toBe("10"); + return jsonResponse({ + data: [ + { + id: "r1", + created_at: "2026-10-21T00:00:00Z", + recipient: "inbox@example.seclai.com", + sender: "bounce@example.com", + sender_ip: "203.0.113.5", + from_address: "a@example.com", + reason: "sender_not_allowed", + authenticated: true, + }, + ], + pagination: { page: 3, limit: 10, total: 21, pages: 3, has_next: false, has_prev: true }, + }); + }); + const res = await client.listEmailSourceRejections("src_1", { page: 3, limit: 10 }); + expect(res.data[0]!.reason).toBe("sender_not_allowed"); + expect(res.pagination.pages).toBe(3); + }); + + test("listEmailSourceRejections sends no query by default", async () => { + const client = makeClient((req) => { + expect(new URL(req.url).search).toBe(""); + return jsonResponse({ data: [], pagination: {} }); + }); + await client.listEmailSourceRejections("src_1"); + }); + + test("createSource and updateSource send the new source settings", async () => { + const bodies: unknown[] = []; + const client = makeClient((req) => { + bodies.push(JSON.parse(req.bodyText!)); + return jsonResponse({ id: "src_1" }); + }); + await client.createSource({ + name: "Inbox", + source_type: "email", + email_allowed_senders: ["example.com"], + document_images: true, + }); + await client.updateSource("src_1", { feed_attachments: ["enclosures"], cloud_drive_max_file_mb: 25 }); + expect(bodies).toEqual([ + { name: "Inbox", source_type: "email", email_allowed_senders: ["example.com"], document_images: true }, + { feed_attachments: ["enclosures"], cloud_drive_max_file_mb: 25 }, + ]); + }); + test("listSources sends GET /sources with query params", async () => { const client = makeClient((req) => { const u = new URL(req.url); @@ -705,6 +795,15 @@ describe("Source Exports", () => { const text = await resp.text(); expect(text).toBe("binary-data"); }); + + test("downloadSourceExport forwards the abort signal", async () => { + const controller = new AbortController(); + const client = makeClient((req) => { + expect(req.signal).toBe(controller.signal); + return new Response("binary-data", { status: 200 }); + }); + await client.downloadSourceExport("src_1", "exp_1", { signal: controller.signal }); + }); }); // ───────────────────────────────────────────────────────────────────────────── @@ -770,6 +869,93 @@ describe("Content", () => { await client.listContentEmbeddings("cv_1"); }); + test("listContentAttachments sends GET /contents/:id/attachments with page/limit", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("GET"); + expect(u.pathname).toBe("/contents/cv_1/attachments"); + expect(u.searchParams.get("page")).toBe("2"); + expect(u.searchParams.get("limit")).toBe("50"); + return jsonResponse({ + data: [{ id: "att_1", key: "k", content_type: "image/png", size_bytes: 3, indexed: true }], + pagination: { page: 2, limit: 50, total: 51, pages: 2, has_next: false, has_prev: true }, + }); + }); + const res = await client.listContentAttachments("cv_1", { page: 2, limit: 50 }); + expect(res.data[0]!.id).toBe("att_1"); + expect(res.pagination.total).toBe(51); + }); + + test("listContentAttachments sends no query by default", async () => { + const client = makeClient((req) => { + expect(new URL(req.url).search).toBe(""); + return jsonResponse({ data: [], pagination: {} }); + }); + await client.listContentAttachments("cv_1"); + }); + + test("getContentAttachment sends GET with start/end", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("GET"); + expect(u.pathname).toBe("/contents/cv_1/attachments/att_1"); + expect(u.searchParams.get("start")).toBe("10"); + expect(u.searchParams.get("end")).toBe("20"); + return jsonResponse({ id: "att_1", text_content: "hello", file_withheld: null }); + }); + const res = await client.getContentAttachment("cv_1", "att_1", { start: 10, end: 20 }); + expect(res.text_content).toBe("hello"); + }); + + test("listContentAttachmentEmbeddings sends GET .../embeddings with page/limit", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("GET"); + expect(u.pathname).toBe("/contents/cv_1/attachments/att_1/embeddings"); + expect(u.searchParams.get("page")).toBe("1"); + expect(u.searchParams.get("limit")).toBe("100"); + return jsonResponse({ items: [] }); + }); + await client.listContentAttachmentEmbeddings("cv_1", "att_1", { page: 1, limit: 100 }); + }); + + test("downloadContentAttachment returns the raw Response", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("GET"); + expect(u.pathname).toBe("/contents/cv_1/attachments/att_1/file"); + expect(u.search).toBe(""); + return new Response("png-bytes", { status: 200, headers: { "content-type": "image/png" } }); + }); + const resp = await client.downloadContentAttachment("cv_1", "att_1"); + expect(resp.headers.get("content-type")).toBe("image/png"); + expect(await resp.text()).toBe("png-bytes"); + }); + + test("getContentAttachment sends end=0", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(u.searchParams.get("start")).toBe("0"); + expect(u.searchParams.get("end")).toBe("0"); + return jsonResponse({ id: "att_1", text_content: "", file_withheld: null }); + }); + await client.getContentAttachment("cv_1", "att_1", { start: 0, end: 0 }); + }); + + test("downloadContentAttachment forwards the abort signal", async () => { + const controller = new AbortController(); + const client = makeClient((req) => { + expect(req.signal).toBe(controller.signal); + return new Response("bytes", { status: 200 }); + }); + await client.downloadContentAttachment("cv_1", "att_1", { signal: controller.signal }); + }); + + test("downloadContentAttachment throws on a withheld file", async () => { + const client = makeClient(() => jsonResponse({ detail: "withheld" }, 403)); + await expect(client.downloadContentAttachment("cv_1", "att_1")).rejects.toThrow(); + }); + test("uploadFileToContent sends multipart", async () => { const client = makeClient((req) => { expect(new URL(req.url).pathname).toBe("/contents/cv_1/upload"); @@ -1051,6 +1237,24 @@ describe("Agent Input Uploads", () => { }); expect(await resp.text()).toBe("file-bytes"); }); + + test("downloadAgentRunAttachment forwards the abort signal", async () => { + const controller = new AbortController(); + const client = makeClient((req) => { + expect(req.signal).toBe(controller.signal); + return new Response("file-bytes", { status: 200 }); + }); + await client.downloadAgentRunAttachment("run_1", "att_1", { signal: controller.signal }); + }); + + test("downloadAgentRunAttachment rejects when the signal is already aborted", async () => { + const controller = new AbortController(); + controller.abort(); + const client = makeClient(() => new Response("unused"), { fetch: hangUntilAborted }); + await expect( + client.downloadAgentRunAttachment("run_1", "att_1", { signal: controller.signal }), + ).rejects.toMatchObject({ name: "AbortError" }); + }); }); // ───────────────────────────────────────────────────────────────────────────── @@ -2188,6 +2392,72 @@ describe("Agent Email Triggers", () => { }); expect(config.email_addresses).toEqual(["support.acct@agent.seclai.com"]); }); + + test("setEmailTriggerConfig sends run_on_attachment_mismatch", async () => { + const client = makeClient((req) => { + expect(JSON.parse(req.bodyText!)).toEqual({ run_on_attachment_mismatch: true }); + return jsonResponse({ trigger_id: "tr_1", email_run_on_attachment_mismatch: true }); + }); + const config = await client.setEmailTriggerConfig("ag_1", "tr_1", { run_on_attachment_mismatch: true }); + expect(config.email_run_on_attachment_mismatch).toBe(true); + }); + + test("setAcceptedAttachments sends PUT /agents/:id/triggers/:tid/accepted-attachments", async () => { + const client = makeClient((req) => { + const u = new URL(req.url); + expect(req.method).toBe("PUT"); + expect(u.pathname).toBe("/agents/ag_1/triggers/tr_1/accepted-attachments"); + expect(u.search).toBe(""); + expect(JSON.parse(req.bodyText!)).toEqual({ + accepted_attachments: [{ name: "invoice", content_types: ["application/pdf"], max: 1 }], + }); + return jsonResponse({ + trigger_id: "tr_1", + agent_id: "ag_1", + accepted_attachments: [{ name: "invoice", content_types: ["application/pdf"], min: 0, max: 1 }], + }); + }); + // `min` is server-defaulted, so a slot without it must typecheck. + const res = await client.setAcceptedAttachments("ag_1", "tr_1", { + accepted_attachments: [{ name: "invoice", content_types: ["application/pdf"], max: 1 }], + }); + expect(res.accepted_attachments[0]!.min).toBe(0); + }); + + test("SetAcceptedAttachmentsRequest accepts a slot without min", async () => { + const body: SetAcceptedAttachmentsRequest = { accepted_attachments: [{ name: "doc" }] }; + const client = makeClient((req) => { + expect(JSON.parse(req.bodyText!)).toEqual({ accepted_attachments: [{ name: "doc" }] }); + return jsonResponse({ trigger_id: "tr_1", agent_id: "ag_1", accepted_attachments: [{ name: "doc", min: 0 }] }); + }); + await client.setAcceptedAttachments("ag_1", "tr_1", body); + }); + + test("setAcceptedAttachments sends null to clear the declaration", async () => { + const client = makeClient((req) => { + expect(JSON.parse(req.bodyText!)).toEqual({ accepted_attachments: null }); + return jsonResponse({ trigger_id: "tr_1", agent_id: "ag_1", accepted_attachments: [] }); + }); + await client.setAcceptedAttachments("ag_1", "tr_1", { accepted_attachments: null }); + }); + + test("createAgent and updateAgentDefinition accept slots without min", async () => { + const bodies: unknown[] = []; + const client = makeClient((req) => { + bodies.push(JSON.parse(req.bodyText!)); + return jsonResponse({ id: "ag_1" }); + }); + await client.createAgent({ name: "A", trigger_type: "dynamic_input", accepted_attachments: [{ name: "doc" }] }); + await client.updateAgentDefinition("ag_1", { + expected_change_id: "chg_1", + definition: {}, + accepted_attachments: [{ name: "doc" }], + }); + expect(bodies).toEqual([ + { name: "A", trigger_type: "dynamic_input", accepted_attachments: [{ name: "doc" }] }, + { expected_change_id: "chg_1", definition: {}, accepted_attachments: [{ name: "doc" }] }, + ]); + }); }); // ───────────────────────────────────────────────────────────────────────────── @@ -2788,7 +3058,7 @@ describe("API version constants", () => { test("a constant reaches the wire", async () => { const client = makeClient( (req) => { - expect(req.headers["seclai-version"]).toBe("2026-10-03"); + expect(req.headers["seclai-version"]).toBe("2026-10-21"); return jsonResponse({ data: [] }); }, { apiVersion: SeclaiApiVersion.Latest },