@typeship-ax/cli 0.6.0 → 0.8.0

package/api.md

@@ -1,6 +1,6 @@
 # typeship — API reference
 
-Version 0.6.0. Generated by typeship; regenerate rather than editing.
+API version 1.0.0. Package version 0.8.0. Generated by typeship; regenerate rather than editing.
 
 All methods return `ApiResult<T, E>`: check `result.ok`, or `unwrap(result)` to throw typed errors.
 
@@ -10,7 +10,7 @@ For complete input and output schemas, use [`api.json`](./api.json), the machine
 
 ### `client.generate.run(body)`
 
-Generate a package from a spec
+Generate one Target from a Definition
 
 `POST /generate`
 
@@ -18,9 +18,9 @@ Stateless generation: nothing is stored. Returns the full generated
 package as files. Works without an API key: anonymous calls generate
 the first 25 operations, rate limited per IP address, and the
 response's `limits` object says what was held back and where to lift
-it; anonymous calls from a spec URL also carry `claim.url`, a link
+it; anonymous calls from a Definition URL also carry `claim.url`, a link
 that turns the run into a project once a person signs in. With a key, the free plan generates the first 25 operations and
-paid plans generate the whole spec. A present but invalid key is a
+paid plans generate the complete Definition. A present but invalid key is a
 401, not a downgrade to anonymous.
 
 Safety: **write** · Authentication: **optional**
@@ -35,12 +35,12 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (40
 
 ```json
 {
-  "spec": {
+  "definition": {
     "url": "https://example.com"
   },
-  "outputs": [
-    "typescript-sdk"
-  ]
+  "target": {
+    "generator": "typescript-sdk"
+  }
 }
 ```
 
@@ -59,9 +59,9 @@ Safety: **read** · Authentication: **required**
 | Parameter | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
 
-Returns: `PagePromise<Project>` — auto-paginating (`for await` walks every page)
+Returns: `PagePromise<ProjectSummary>` — auto-paginating (`for await` walks every page)
 Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
 
 <details>
@@ -79,7 +79,7 @@ Create a project
 
 `POST /projects`
 
-Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected output, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and the whole spec.
+Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected target, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and generates every operation in the Definition.
 
 Safety: **write** · Authentication: **required**
 
@@ -90,7 +90,7 @@ Safety: **write** · Authentication: **required**
 Body: `CreateProjectRequest` (required)
 
 Returns: `Project`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `ConflictError` (409), `RateLimitedError` (429), `InternalServerError` (500)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
 
 <details>
 <summary>Wire arguments (CLI and MCP)</summary>
@@ -98,12 +98,17 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredErro
 ```json
 {
   "name": "example",
-  "source": {
-    "kind": "url",
-    "url": "https://example.com"
+  "definition": {
+    "source": {
+      "kind": "url",
+      "url": "https://example.com"
+    }
   },
-  "outputs": [
-    "typescript-sdk"
+  "targets": [
+    {
+      "name": "example",
+      "generator": "typescript-sdk"
+    }
   ]
 }
 ```
@@ -177,7 +182,7 @@ Safety: **write** · Authentication: **required**
 Body: `UpdateProjectRequest` (required)
 
 Returns: `Project`
-Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
 
 <details>
 <summary>Wire arguments (CLI and MCP)</summary>
@@ -190,13 +195,13 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredErro
 
 </details>
 
-### `client.projects.retrieveGithubHealth(projectId)`
+### `client.projects.retrieveDiagnostics(projectId)`
 
-Diagnose a project's GitHub integration
+Analyze a project's latest Definition Revision
 
-`GET /projects/{project_id}/github`
+`GET /projects/{project_id}/diagnostics`
 
-Returns machine-actionable source and destination access, spec readability, optional label setup, required status names, and the latest durable webhook delivery. The console renders this same result.
+Runs deterministic OpenAPI or GraphQL authorship checks against the latest observed immutable Definition Revision after applying the Definition's existing patches. Diagnostics group every affected location under a stable rule. Exact patches are included only when Typeship can derive the change without inventing API behavior.
 
 Safety: **read** · Authentication: **required**
 
@@ -204,7 +209,96 @@ Safety: **read** · Authentication: **required**
 | --- | --- | --- | --- | --- |
 | `projectId` | path | `ProjectId` | yes | — |
 
-Returns: `GithubIntegrationHealth`
+Returns: `DiagnosticReport`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.refreshDiagnostics(projectId)`
+
+Refresh a project's Diagnostics from its configured source
+
+`POST /projects/{project_id}/diagnostics`
+
+Fetches the complete configured source, records a new immutable revision only when content changed, and returns its Diagnostics. This does not generate targets or consume a metered generation.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `DiagnosticReport`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.remediateDiagnostics(projectId, body)`
+
+Apply exact, reviewed diagnostic remediations
+
+`POST /projects/{project_id}/diagnostics/remediations`
+
+Applies only deterministic patches. Repository sources receive an updateable source pull request; URL sources receive project overlays. Diagnostics that require API-owner intent return 422 and include an authoring_brief in the Diagnostic instead.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Body: `DiagnosticRemediationRequest` (required)
+
+Returns: `DiagnosticRemediation`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n",
+  "diagnostic_ids": [
+    "value"
+  ]
+}
+```
+
+</details>
+
+### `client.projects.retrieveIntegrationHealth(projectId)`
+
+Diagnose a project's repository integrations
+
+`GET /projects/{project_id}/integration-health`
+
+Returns provider-neutral, machine-actionable source and destination access, Definition readability, source-approval label setup, required status names, and the latest durable webhook delivery. The Console renders this same result.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `RepositoryIntegrationHealth`
 Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
 
 <details>
@@ -230,8 +324,8 @@ Safety: **read** · Authentication: **required**
 | --- | --- | --- | --- | --- |
 | `projectId` | path | `ProjectId` | yes | — |
 | `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
-| `output` | query | `OutputId` | no | Only generations for this output. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `targetId` | query | `TargetId` | no | Only generations for this persisted Target. |
 
 Returns: `PagePromise<Generation>` — auto-paginating (`for await` walks every page)
 Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
@@ -249,11 +343,11 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (40
 
 ### `client.projects.generate(projectId)`
 
-Generate outputs and open pull requests
+Generate targets and open pull requests
 
 `POST /projects/{project_id}/generations`
 
-Resolves the project's URL or repository source, generates every
+Resolves the project's URL or GitHub source, generates every
 configured delivery package, stores each result in the project's history,
 and attempts to open a pull request in every configured destination.
 When the complete generated tree already matches a destination, no
@@ -281,6 +375,263 @@ Errors: `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError
 
 </details>
 
+## definitions
+
+### `client.definitions.retrieve(definitionId)`
+
+Retrieve a Definition
+
+`GET /definitions/{definition_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `definitionId` | path | `DefinitionId` | yes | — |
+
+Returns: `Definition`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "definition_id": "def_2p8m4q7k1v9d6h3c"
+}
+```
+
+</details>
+
+### `client.definitions.update(definitionId, body)`
+
+Update and resolve a Definition
+
+`PATCH /definitions/{definition_id}`
+
+Resolves the complete document graph and records a new immutable revision before saving.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `definitionId` | path | `DefinitionId` | yes | — |
+
+Body: `DefinitionUpdateRequest` (required)
+
+Returns: `Definition`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "definition_id": "def_2p8m4q7k1v9d6h3c"
+}
+```
+
+</details>
+
+## targets
+
+### `client.targets.list(projectId, params)`
+
+List a project's Targets
+
+`GET /projects/{project_id}/targets`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+
+Returns: `PagePromise<Target>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.targets.create(projectId, body)`
+
+Create an independently configured Target
+
+`POST /projects/{project_id}/targets`
+
+Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Body: `TargetFields` (required)
+
+Returns: `TargetResponse`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n",
+  "name": "example",
+  "definition_id": "def_2p8m4q7k1v9d6h3c",
+  "generator": "typescript-sdk"
+}
+```
+
+</details>
+
+### `client.targets.retrieve(targetId)`
+
+Retrieve a Target
+
+`GET /targets/{target_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `targetId` | path | `TargetId` | yes | — |
+
+Returns: `TargetResponse`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "target_id": "tgt_5m8q2v7k1p9d4h6c"
+}
+```
+
+</details>
+
+### `client.targets.delete(targetId)`
+
+Delete an unused Target
+
+`DELETE /targets/{target_id}`
+
+Targets with Generation or release history, or an active release candidate, must be disabled instead.
+
+Safety: **destructive** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `targetId` | path | `TargetId` | yes | — |
+
+Returns: `DeletedTarget`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "target_id": "tgt_5m8q2v7k1p9d4h6c"
+}
+```
+
+</details>
+
+### `client.targets.update(targetId, body)`
+
+Update a Target, its Deliveries, or its next reviewed version
+
+`PATCH /targets/{target_id}`
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `targetId` | path | `TargetId` | yes | — |
+
+Body: `TargetUpdateRequest` (required)
+
+Returns: `TargetResponse`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "target_id": "tgt_5m8q2v7k1p9d4h6c"
+}
+```
+
+</details>
+
+### `client.targets.listReleases(targetId, params)`
+
+List immutable releases for a Target
+
+`GET /targets/{target_id}/releases`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `targetId` | path | `TargetId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+
+Returns: `PagePromise<TargetRelease>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "target_id": "tgt_5m8q2v7k1p9d4h6c"
+}
+```
+
+</details>
+
+### `client.targets.retrieveRelease(targetReleaseId)`
+
+Retrieve an immutable Target release
+
+`GET /target_releases/{target_release_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `targetReleaseId` | path | `TargetReleaseId` | yes | — |
+
+Returns: `TargetReleaseResponse`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "target_release_id": "rel_7m2q8v4k1p9d5h6c"
+}
+```
+
+</details>
+
 ## generations
 
 ### `client.generations.retrieve(generationId)`
@@ -297,7 +648,7 @@ Safety: **read** · Authentication: **required**
 | --- | --- | --- | --- | --- |
 | `generationId` | path | `GenerationId` | yes | — |
 
-Returns: `Generation`
+Returns: `GenerationResponse`
 Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
 
 <details>
@@ -317,7 +668,7 @@ Fetch one file from a generation
 
 `GET /generations/{generation_id}/file`
 
-Raw file content, for generations whose output was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+Raw file content, for generations whose target was too large to inline (files_omitted true). The generation's files_index lists valid paths.
 
 Safety: **read** · Authentication: **required**
 
@@ -341,25 +692,25 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (40
 
 </details>
 
-## specRevisions
+## definitionRevisions
 
-### `client.specRevisions.list(projectId, params)`
+### `client.definitionRevisions.list(definitionId, params)`
 
-List specification revisions
+List Definition Revisions
 
-`GET /projects/{project_id}/spec_revisions`
+`GET /definitions/{definition_id}/revisions`
 
-Immutable snapshots of the exact source text this project consumed, newest first. Raw content is available from each revision's content endpoint and is never embedded in a list response.
+Immutable snapshots of the complete resolved document graph this Definition observed, newest first. Content is available from the revision and document endpoints and is never embedded in a list response.
 
 Safety: **read** · Authentication: **required**
 
 | Parameter | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `projectId` | path | `ProjectId` | yes | — |
+| `definitionId` | path | `DefinitionId` | yes | — |
 | `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
 
-Returns: `PagePromise<SpecRevision>` — auto-paginating (`for await` walks every page)
+Returns: `PagePromise<DefinitionRevision>` — auto-paginating (`for await` walks every page)
 Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
 
 <details>
@@ -367,27 +718,27 @@ Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (40
 
 ```json
 {
-  "project_id": "prj_4f8k2m7x9q1v6b3n"
+  "definition_id": "def_2p8m4q7k1v9d6h3c"
 }
 ```
 
 </details>
 
-### `client.specRevisions.retrieve(specRevisionId)`
+### `client.definitionRevisions.retrieve(definitionRevisionId)`
 
-Retrieve a specification revision
+Retrieve a Definition Revision
 
-`GET /spec_revisions/{spec_revision_id}`
+`GET /definition_revisions/{definition_revision_id}`
 
-Metadata for one immutable source snapshot. Fetch raw source text from the content endpoint so metadata responses stay small and predictable.
+Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
 
 Safety: **read** · Authentication: **required**
 
 | Parameter | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
 
-Returns: `SpecRevision`
+Returns: `DefinitionRevisionResponse`
 Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
 
 <details>
@@ -395,25 +746,52 @@ Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404)
 
 ```json
 {
-  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c"
 }
 ```
 
 </details>
 
-### `client.specRevisions.retrieveContent(specRevisionId)`
+### `client.definitionRevisions.retrieveContent(definitionRevisionId)`
+
+Retrieve a Definition Revision's canonical content
+
+`GET /definition_revisions/{definition_revision_id}/content`
+
+Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
+
+Returns: `string`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c"
+}
+```
+
+</details>
 
-Retrieve a specification revision's raw text
+### `client.definitionRevisions.retrieveDocumentContent(definitionRevisionId, documentId)`
 
-`GET /spec_revisions/{spec_revision_id}/content`
+Retrieve one source document from a Definition Revision
 
-Returns the exact source text identified by the revision's SHA-256 digest, suitable for saving or piping directly into a diff.
+`GET /definition_revisions/{definition_revision_id}/documents/{document_id}/content`
 
 Safety: **read** · Authentication: **required**
 
 | Parameter | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+| `definitionRevisionId` | path | `DefinitionRevisionId` | yes | — |
+| `documentId` | path | `DefinitionDocumentId` | yes | — |
 
 Returns: `string`
 Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
@@ -423,7 +801,8 @@ Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404)
 
 ```json
 {
-  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+  "definition_revision_id": "drev_6m1q8v4k2p9d7h3c",
+  "document_id": "doc_8q2m5v1k9p4d7h3c"
 }
 ```
 
@@ -469,7 +848,7 @@ Safety: **read** · Authentication: **required**
 | Parameter | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `limit` | query | `number` | no | Maximum number of resources to return. |
-| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
 
 Returns: `PagePromise<ApiKey>` — auto-paginating (`for await` walks every page)
 Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
@@ -489,7 +868,7 @@ Revoke an API key
 
 `DELETE /api_keys/{api_key_id}`
 
-Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded.
+Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded. An OAuth member may revoke a key they created; an organization admin may revoke any key. Organization API keys retain account-wide authority.
 
 Safety: **destructive** · Authentication: **required**
 
@@ -497,7 +876,7 @@ Safety: **destructive** · Authentication: **required**
 | --- | --- | --- | --- | --- |
 | `apiKeyId` | path | `string` | yes | — |
 
-Returns: `ApiKey`
+Returns: `ApiKeyResponse`
 Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
 
 <details>