You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6098c7e
Browse filesBrowse the repository at this point in the historyBrowse files
improvement(api): consolidate the v2 surface and close seven defects
Endpoint consolidation:
- Fold POST /logs/query into GET /logs; add sortBy/sortOrder, cap the
comma lists, and move the list onto the shared keyset codec
- Fold GET /knowledge/archived into GET /knowledge?scope=archived,
matching files, tables, and workflows
- Re-home chat deployments as a singleton under the workflow they
belong to; keep the workspace-scoped discovery list
- Move the tag-definition writes off the document path onto
/knowledge/{id}/tags, where they already acted
- Nest the table export and dispatch reads under their parent table
Defects:
- Publish isPublicApi on the deployment read; it was write-only, so a
workflow could be opened to unauthenticated execution unauditably
- Stop publishing raw storage keys and an unusable URL in log files
- Classify a chat-identifier unique violation as 409 rather than 500
- Fall back to the root path instead of throwing when a knowledge
base's folder is archived
- Cap bulk-download at the ceiling it actually enforces
- Normalize variables through one helper on both graph write paths
- Fix a folder-name log filter that matched workflow names
Naming and gaps:
- Rename /files/{id}/extract to /unarchive, /rows/find to /rows/search,
/rows/batch-update to /rows/bulk-update, /columns/run to /dispatches
- Type the last six generic [id] path segments
- Add table folder restore and id-addressed dispatch cancel
Copy file name to clipboardExpand all lines: .agents/skills/v2-api-conventions/SKILL.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -113,7 +113,9 @@ Every paged list's binding is declared in `lib/api/contracts/v2/__tests__/list-p
113
113
114
114
Return `nextCursor: null` on the last page and only then. Never construct a cursor client-side.
115
115
116
-
**Ordering is `sortBy` + `sortOrder`, except where there is nothing to sort by.** Fourteen lists take the pair. Two — `GET /logs` and `GET /workflows/{id}/runs` — have exactly one sortable column (start time), so there is no `sortBy` to pair with and the direction rides on a single `order` param; `sortBy`/`sortOrder` are not accepted there. That split is documented in both contracts and is the *only* sanctioned deviation. A new list picks the pair. Do not "fix" the two by accepting `sortOrder` as an alias: an alias is a second spelling of one thing with undefined precedence when both arrive, which is its own inconsistency, and renaming `order` would break every shipped caller.
116
+
**Ordering is `sortBy` + `sortOrder`, except where there is nothing to sort by.** Fifteen lists take the pair. Exactly one — `GET /workflows/{workflowId}/runs` — has a single sortable column (start time), so there is no `sortBy` to pair with and the direction rides on a single `order` param; `sortBy`/`sortOrder` are not accepted there. That is the *only* sanctioned deviation, and it is documented in its contract. A new list picks the pair. Do not "fix" it by accepting `sortOrder` as an alias: an alias is a second spelling of one thing with undefined precedence when both arrive, which is its own inconsistency.
117
+
118
+
`GET /logs` was the second exception until it absorbed `POST /logs/query`. That fold is the cautionary tale for this rule: the justification for the `order` spelling was "logs have exactly one sortable column", and a second endpoint sorting the same rows four ways had already disproved it. When a rule's premise is contradicted by another endpoint on the same collection, fix the premise rather than documenting the exception.
117
119
118
120
**A boolean query param is a real boolean**, declared with `booleanQueryFlagSchema` from `contracts/primitives.ts`. It coerces `'true'`/`'1'` and `'false'`/`'0'`/`''`, so it is a strict widening of a `z.enum(['true','false'])` — which is what two v2 params used to be, purely by inheritance from the internal shapes they reused. Reusing an internal `.shape.x` inherits the internal spelling; re-declare instead when the internal one is not the v2 convention.
Copy file name to clipboardExpand all lines: apps/docs/content/docs/en/cli/chat-deployments.mdx
-107Lines changed: 0 additions & 107 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,76 +7,6 @@ import { CommandTable } from '@/components/ui/command-table'
7
7
8
8
Every command below also accepts the [global options](/cli/commands#global-options).
9
9
10
-
## Create chat deployment
11
-
12
-
```bash
13
-
sim chat-deployments create [options]
14
-
```
15
-
16
-
**Options**
17
-
18
-
<CommandTable>
19
-
20
-
| Option | Required | Description |
21
-
| --- | --- | --- |
22
-
|`--workflow-id <value>`| Yes | Workflow to publish as a chat. |
23
-
|`--identifier <value>`| Yes | URL slug the deployed chat will answer on. Must be free across live deployments. |
24
-
|`--title <value>`| Yes | Title shown to visitors. |
25
-
|`--description <value>`| No | Description shown to visitors. |
26
-
|`--customizations <json\|@file>`| No | Presentation overrides. Omitted fields take platform defaults. (JSON, or @path / @- to read a file or stdin). |
27
-
|`--auth-type <value>`| No | How visitors are gated. `public` leaves the chat open to anyone holding the URL. Accepted values: `public`, `password`, `email`, `sso`. |
28
-
|`--password <value>`| No | Write-only password, required when `authType` is `password`. Never readable back. |
29
-
|`--allowed-emails <json\|@file>`| No | Email addresses or domains admitted under `email` and `sso` gating. At least one is required for those modes. (JSON, or @path / @- to read a file or stdin). |
30
-
|`--output-configs <json\|@file>`| No | Block outputs to surface to visitors. (JSON, or @path / @- to read a file or stdin). |
31
-
|`--include-thinking`| No | Allow visitors to receive provider thinking events. |
32
-
|`--no-include-thinking`| No | Send --include-thinking as false. |
33
-
|`--include-tool-calls`| No | Allow visitors to receive tool lifecycle events. |
34
-
|`--no-include-tool-calls`| No | Send --include-tool-calls as false. |
|`--identifier <value>`| No | New URL slug for the deployed chat. |
124
-
|`--title <value>`| No | New title shown to visitors. |
125
-
|`--description <value>`| No | New description shown to visitors. |
126
-
|`--customizations <json\|@file>`| No | Replacement presentation overrides. Replaced wholesale, not merged. (JSON, or @path / @- to read a file or stdin). |
127
-
|`--auth-type <value>`| No | New visitor gate. Switching modes clears the gate the previous mode owned: a stored password is dropped when moving to `email` or `sso`, and the allow-list is cleared when moving to `password` or `public` unless the same request supplies a replacement `allowedEmails`, which is applied after the clear. Accepted values: `public`, `password`, `email`, `sso`. |
128
-
|`--password <value>`| No | Write-only replacement password. Ignored unless the deployment ends up `password`-gated. Omit to keep the stored one. |
129
-
|`--allowed-emails <json\|@file>`| No | Replacement allow-list for `email` and `sso` gating. Replaced wholesale. (JSON, or @path / @- to read a file or stdin). |
130
-
|`--output-configs <json\|@file>`| No | Replacement block outputs. Replaced wholesale. (JSON, or @path / @- to read a file or stdin). |
131
-
|`--include-thinking`| No | Allow visitors to receive thinking events. |
132
-
|`--no-include-thinking`| No | Send --include-thinking as false. |
133
-
|`--include-tool-calls`| No | Allow visitors to receive tool lifecycle events. |
134
-
|`--no-include-tool-calls`| No | Send --include-tool-calls as false. |
0 commit comments