From 4be35b032819d2f6154e5d4afe47a6a7e0c982c1 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Wed, 21 Jan 2026 15:18:53 +0000 Subject: [PATCH] chore(docs): remove outdated API reference docs and migrate to Scalar API documentation is now auto-generated by Elysia and served via Scalar. Updated all API reference links to point to: - Documentation: https://stg.perstack.ai/api/v1/spec - OpenAPI Spec: https://stg.perstack.ai/api/v1/spec/json Removed: - docs/api-reference/ directory (obsolete static docs) - scripts/generate-api-docs.ts (no longer needed) - .agent/workflows/api-client.md (api-client now external) Co-Authored-By: Claude Opus 4.5 --- .agent/workflows/api-client.md | 135 -- .cursorrules | 1 - CLAUDE.md | 1 - README.md | 2 +- .../registry-v1/experts-versions.md | 76 -- docs/api-reference/registry-v1/experts.md | 444 ------- .../studio-v1/expert-jobs-checkpoints.md | 576 -------- .../studio-v1/expert-jobs-continue.md | 144 -- .../expert-jobs-workspace-instance-to-run.md | 141 -- .../expert-jobs-workspace-instance.md | 738 ----------- docs/api-reference/studio-v1/expert-jobs.md | 439 ------ docs/api-reference/studio-v1/experts.md | 438 ------ docs/api-reference/studio-v1/workspace.md | 1175 ----------------- docs/making-experts/publishing.md | 2 +- docs/understanding-perstack/concept.md | 2 +- docs/understanding-perstack/registry.md | 2 +- scripts/generate-api-docs.ts | 531 -------- 17 files changed, 4 insertions(+), 4843 deletions(-) delete mode 100644 .agent/workflows/api-client.md delete mode 100644 docs/api-reference/registry-v1/experts-versions.md delete mode 100644 docs/api-reference/registry-v1/experts.md delete mode 100644 docs/api-reference/studio-v1/expert-jobs-checkpoints.md delete mode 100644 docs/api-reference/studio-v1/expert-jobs-continue.md delete mode 100644 docs/api-reference/studio-v1/expert-jobs-workspace-instance-to-run.md delete mode 100644 docs/api-reference/studio-v1/expert-jobs-workspace-instance.md delete mode 100644 docs/api-reference/studio-v1/expert-jobs.md delete mode 100644 docs/api-reference/studio-v1/experts.md delete mode 100644 docs/api-reference/studio-v1/workspace.md delete mode 100644 scripts/generate-api-docs.ts diff --git a/.agent/workflows/api-client.md b/.agent/workflows/api-client.md deleted file mode 100644 index 95cf2691..00000000 --- a/.agent/workflows/api-client.md +++ /dev/null @@ -1,135 +0,0 @@ -# API Client Workflow - -This document defines the workflow for implementing or updating the `@perstack/api-client` package based on API changes. - -> **Re-read this document before starting any API client work to avoid drift.** - -## Prerequisites - -- Read `.agent/rules/coding-style.md` for coding standards -- Read `.agent/rules/how-you-work.md` for general workflow - -## Phase 1: Generate and Diff - -1. **Generate API Reference from OpenAPI spec** - - ```bash - npx tsx scripts/generate-api-docs.ts --output ./docs/api-reference - ``` - -2. **Check for changes** - - ```bash - git diff --name-only docs/api-reference/ - ``` - -3. **If no changes** — API is in sync, no work needed - -4. **If changes exist** — Proceed to Phase 2 - -## Phase 2: Analyze Changes - -1. **View the diff for changed files only** - - ```bash - git diff docs/api-reference/ - ``` - -2. **Read only the changed .md files** - - Do NOT read all API reference files. Only read files that appear in the diff. - -3. **Identify the affected api-client modules** - - | Changed API Reference | Affected api-client Module | - | --------------------------------- | -------------------------- | - | `registry-v1/experts.md` | `v1/registry/experts.ts` | - | `registry-v1/experts-versions.md` | `v1/registry/experts.ts` | - | `studio-v1/experts.md` | `v1/studio/experts.ts` | - | `studio-v1/expert-jobs.md` | `v1/studio/expert-jobs.ts` | - | `studio-v1/expert-jobs-*.md` | `v1/studio/expert-jobs.ts` | - | `studio-v1/workspace.md` | `v1/studio/workspace.ts` | - -4. **ultrathink** — Plan the changes based on the diff - -## Phase 3: Implementation - -### Read existing code (only affected modules) - -``` -packages/api-client/v1/ -├── client.ts # ApiV1Client class -├── schemas/ # Zod schemas -└── [affected module] # Only read what you need to change -``` - -### Reuse @perstack/core schemas - -**Critical**: Import and extend from `@perstack/core` where possible. - -```typescript -// Good: Import from core -import { expertSchema, expertKeyRegex } from "@perstack/core" - -// Bad: Duplicate definition -const expertSchema = z.object({ ... }) -``` - -### Implementation Pattern - -> **TBD**: Implementation patterns will be defined after api-client rewrite. - -## Phase 4: Testing - -> **TBD**: Testing patterns will be defined after api-client rewrite. - -## Phase 5: Validation - -```bash -pnpm typecheck -pnpm format-and-lint -pnpm test -- packages/api-client -``` - -## Phase 6: Commit - -Commit both the generated docs and the api-client changes: - -```bash -git add docs/api-reference/ packages/api-client/ -git commit -m "feat(api-client): sync with API changes" -``` - -## Mapping: API Reference → Zod - -| API Reference Field | Zod Implementation | -| ------------------------ | ------------------------------------------- | -| `type: string` | `z.string()` | -| `type: string (pattern)` | `z.string().regex(pattern)` | -| `type: number` | `z.number()` | -| `type: enum` | `z.enum([...])` or `z.union([z.literal()])` | -| `type: object` | `z.object({ ... })` | -| `type: array` | `z.array(schema)` | -| `format: date-time` | `z.iso.datetime().transform(...)` | -| `minLength/maxLength` | `.min()/.max()` with error messages | -| `required: Yes` | Field in `z.object()` (not `.optional()`) | -| `required: No` | `.optional()` | - -## Quick Reference - -``` -1. GENERATE & DIFF - npx tsx scripts/generate-api-docs.ts --output ./docs/api-reference - git diff --name-only docs/api-reference/ - -2. READ ONLY CHANGED FILES - git diff docs/api-reference/ - (Do NOT read unchanged files) - -3. IMPLEMENT (TBD) - -4. TEST & VALIDATE (TBD) - -5. COMMIT - git add docs/api-reference/ packages/api-client/ -``` diff --git a/.cursorrules b/.cursorrules index 7d4c9d04..85e0bde5 100644 --- a/.cursorrules +++ b/.cursorrules @@ -30,7 +30,6 @@ Your configuration source is the `.agent/` directory. | `.agent/workflows/qa.md` | When running QA | | `.agent/workflows/audit.md` | When auditing security | | `.agent/workflows/creating-expert.md` | When creating an Expert | -| `.agent/workflows/api-client.md` | When updating @perstack/api-client | ## Project diff --git a/CLAUDE.md b/CLAUDE.md index 9fe6d126..cebc639c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,7 +30,6 @@ Your configuration source is the `.agent/` directory. | `.agent/workflows/qa.md` | When running QA | | `.agent/workflows/audit.md` | When auditing security | | `.agent/workflows/creating-expert.md` | When creating an Expert | -| `.agent/workflows/api-client.md` | When updating @perstack/api-client | ## Project diff --git a/README.md b/README.md index 99fa2de1..f6ea519a 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ Perstack helps you package, share, and compose the Experts that power them. ### Can Experts in the Registry be used with other AI agent frameworks? Yes. Registry entries are plain text definitions, so other frameworks can consume them too. -See the [API Reference](./docs/references/registry-api.md). +See the [API Reference](https://stg.perstack.ai/api/v1/spec). ### Can Experts created with other AI agent frameworks be used with Perstack? diff --git a/docs/api-reference/registry-v1/experts-versions.md b/docs/api-reference/registry-v1/experts-versions.md deleted file mode 100644 index b49372a1..00000000 --- a/docs/api-reference/registry-v1/experts-versions.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Experts Versions API" ---- - -# Experts Versions - -**Product:** registry -**Version:** v1 - -## Endpoints - -- [GET `/api/registry/v1/experts/{expertKey}/versions`](#get-api-registry-v1-experts-expertkey-versions) - -## GET `/api/registry/v1/experts/{expertKey}/versions` - -**List expert versions** - -List all available versions of a specific expert from the Registry. Returns versions sorted by version number (descending) with the latest tag indicated. - -**Operation ID:** `getApiRegistryV1ExpertsByExpertKeyVersions` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| versions | object[] | Yes | | -| latest | string | Yes | | -| meta | object | Yes | | -| total | union | Yes | | - -#### 404 - -Not Found. Possible reasons: -- Expert not found -- Latest version not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/registry-v1/experts.md b/docs/api-reference/registry-v1/experts.md deleted file mode 100644 index 527b3ded..00000000 --- a/docs/api-reference/registry-v1/experts.md +++ /dev/null @@ -1,444 +0,0 @@ ---- -title: "Experts API" ---- - -# Experts - -**Product:** registry -**Version:** v1 - -## Endpoints - -- [GET `/api/registry/v1/experts/{expertKey}`](#get-api-registry-v1-experts-expertkey-) -- [POST `/api/registry/v1/experts/{expertKey}`](#post-api-registry-v1-experts-expertkey-) -- [DELETE `/api/registry/v1/experts/{expertKey}`](#delete-api-registry-v1-experts-expertkey-) -- [GET `/api/registry/v1/experts/`](#get-api-registry-v1-experts-) -- [POST `/api/registry/v1/experts/`](#post-api-registry-v1-experts-) - -## GET `/api/registry/v1/experts/{expertKey}` - -**Get an expert** - -Retrieve detailed information about a specific expert version from the Registry. Accepts expert key format (name@version or name@tag). - -**Operation ID:** `getApiRegistryV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | object | Yes | | -| type | `"registryExpert"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | Yes | Semantic version of the expert | -| status | `available` \| `deprecated` \| `disabled` | Yes | | -| instruction | string | Yes | System prompt that defines the expert's behavior | -| skills | object | Yes | MCP skills available to this expert | -| delegates | RegExp[] | Yes | Other published experts this expert can delegate tasks to | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | - -#### 404 - -Expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/registry/v1/experts/{expertKey}` - -**Update an expert** - -Update metadata of an existing expert version (status, tags). Status transitions are restricted (e.g., deprecated cannot become available). Requires authentication and ownership. - -**Operation ID:** `postApiRegistryV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| status | `available` \| `deprecated` \| `disabled` | No | | -| tags | RegExp[] | No | Version tags (e.g., latest, stable) | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Expert is not owned by the organization -- Status is the same as the current status -- Cannot change status of disabled expert -- Cannot change deprecated expert to available -- Cannot manually set latest tag -- Cannot remove latest tag from latest version - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/registry/v1/experts/{expertKey}` - -**Delete an expert version** - -Delete a specific version of an expert from the Registry. Cannot delete if the expert is delegated to other experts. Requires authentication and ownership. - -**Operation ID:** `deleteApiRegistryV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `type` - -#### 400 - -Bad Request. Possible reasons: -- Expert is not owned by the organization -- Expert is delegated to other experts - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/registry/v1/experts/` - -**List experts** - -List all experts from the Registry. Returns only latest versions. Supports filtering by name prefix, sorting, and pagination. - -**Operation ID:** `getApiRegistryV1Experts` - -### Parameters - -#### `organizationId` (query) - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `filter` (query) - -**Type:** string -**Length:** min: 1, max: 256 - -#### `sort` (query) - -**Type:** enum -**Values:** `name`, `version`, `createdAt`, `updatedAt` - -#### `order` (query) - -**Type:** enum -**Values:** `asc`, `desc` - -#### `take` (query) - -**Required** - -**Type:** number -**Range:** min: 1, max: 100 -**Default:** `100` - -#### `skip` (query) - -**Required** - -**Type:** number -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| experts | object[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/registry/v1/experts/` - -**Publish an expert** - -Publish a new version of an expert to the Registry. If the expert name does not exist, it creates a new expert. Requires authentication. - -**Operation ID:** `postApiRegistryV1Experts` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | Yes | Semantic version of the expert | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| instruction | string | Yes | System prompt that defines the expert's behavior | -| skills | object | Yes | MCP skills available to this expert | -| delegates | RegExp[] | No | Other published experts this expert can delegate tasks to | -| tags | RegExp[] | No | Version tags (e.g., latest, stable) | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Expert {name} already exists (owned by another organization) -- Version {version} is already published -- @perstack/base is required -- Expert name cannot be scoped (for personal accounts) -- Expert name must be scoped (for team accounts) -- Delegate expert not found: {delegate} - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/expert-jobs-checkpoints.md b/docs/api-reference/studio-v1/expert-jobs-checkpoints.md deleted file mode 100644 index 7d130b4b..00000000 --- a/docs/api-reference/studio-v1/expert-jobs-checkpoints.md +++ /dev/null @@ -1,576 +0,0 @@ ---- -title: "Expert Jobs Checkpoints API" ---- - -# Expert Jobs Checkpoints - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/{checkpointId}`](#get-api-studio-v1-expert-jobs-expertjobid-checkpoints-checkpointid-) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/`](#get-api-studio-v1-expert-jobs-expertjobid-checkpoints-) -- [POST `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/`](#post-api-studio-v1-expert-jobs-expertjobid-checkpoints-) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/stream`](#get-api-studio-v1-expert-jobs-expertjobid-checkpoints-stream) - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/{checkpointId}` - -**Get a checkpoint** - -Retrieve detailed information about a specific checkpoint including messages and tool calls. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdCheckpointsByCheckpointId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `checkpointId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| checkpoint | object | Yes | | -| type | `"checkpoint"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| action | union | Yes | | -| runId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| expertJobId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| stepNumber | number | Yes | | -| status | `init` \| `proceeding` \| `completed` \| `stoppedByInteractiveTool` \| `stoppedByDelegate` \| `stoppedByExceededMaxSteps` \| `stoppedByError` | Yes | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| skillName | string | No | | -| toolName | string | No | | -| delegateTo | object | No | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| delegatedBy | object | No | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| checkpointId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| inputMessages | unknown[] | No | | -| messages | unknown[] | Yes | | -| newMessages | unknown[] | Yes | | -| toolCall | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| args | object | Yes | | -| toolResult | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| result | unknown[] | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| contextWindow | number | No | | -| contextWindowUsage | number | No | | -| startedAt | string | Yes | | -| finishedAt | string | No | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Checkpoint not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/` - -**List checkpoints** - -List all checkpoints for a specific expert job. Supports sorting and pagination. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdCheckpoints` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `filter` (query) - -**Type:** string -**Length:** min: 1, max: 256 - -#### `sort` (query) - -**Type:** enum -**Values:** `createdAt`, `updatedAt` - -#### `order` (query) - -**Type:** enum -**Values:** `asc`, `desc` - -#### `take` (query) - -**Required** - -**Type:** number -**Range:** min: 1, max: 100 -**Default:** `10` - -#### `skip` (query) - -**Required** - -**Type:** number -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| checkpoints | object[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Query or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/` - -**Create a checkpoint** - -Create a new checkpoint for an expert job. Internal API called by the expert job runtime. - -**Operation ID:** `postApiStudioV1Expert_jobsByExpertJobIdCheckpoints` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| checkpoint | object | Yes | | -| status | `init` \| `proceeding` \| `completed` \| `stoppedByInteractiveTool` \| `stoppedByDelegate` \| `stoppedByExceededMaxSteps` \| `stoppedByError` | Yes | | -| stepNumber | number | Yes | | -| messages | unknown[] | Yes | | -| expert | object | Yes | | -| key | string | Yes | | -| name | string | Yes | | -| version | string | Yes | | -| delegateTo | object | No | | -| expert | object | Yes | | -| key | string | Yes | | -| name | string | Yes | | -| version | string | Yes | | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| query | string | Yes | | -| delegatedBy | object | No | | -| expert | object | Yes | | -| key | string | Yes | | -| name | string | Yes | | -| version | string | Yes | | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| checkpointId | string | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| contextWindow | number | No | | -| contextWindowUsage | number | No | | -| step | object | Yes | | -| stepNumber | number | Yes | | -| inputMessages | unknown[] | No | | -| newMessages | unknown[] | Yes | | -| toolCall | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| args | object | Yes | | -| toolResult | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| result | unknown[] | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| startedAt | number | Yes | | -| finishedAt | number | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| checkpoint | object | Yes | | -| type | `"checkpoint"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| action | union | Yes | | -| runId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| expertJobId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| stepNumber | number | Yes | | -| status | `init` \| `proceeding` \| `completed` \| `stoppedByInteractiveTool` \| `stoppedByDelegate` \| `stoppedByExceededMaxSteps` \| `stoppedByError` | Yes | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| skillName | string | No | | -| toolName | string | No | | -| delegateTo | object | No | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| delegatedBy | object | No | | -| expert | object | Yes | | -| type | `"expertDigest"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| key | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| owner | object | Yes | Organization that owns this expert | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| createdAt | string | Yes | Creation timestamp | -| updatedAt | string | Yes | Last update timestamp | -| version | string (pattern: `^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*...`) | No | Semantic version of the expert | -| tags | RegExp[] | Yes | Version tags (e.g., latest, stable) | -| toolCallId | string | Yes | | -| toolName | string | Yes | | -| checkpointId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| inputMessages | unknown[] | No | | -| messages | unknown[] | Yes | | -| newMessages | unknown[] | Yes | | -| toolCall | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| args | object | Yes | | -| toolResult | object | No | | -| id | string | Yes | | -| skillName | string | Yes | | -| toolName | string | Yes | | -| result | unknown[] | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| contextWindow | number | No | | -| contextWindowUsage | number | No | | -| startedAt | string | Yes | | -| finishedAt | string | No | | - -#### 400 - -Bad Request. Expert not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/checkpoints/stream` - -**Stream checkpoints** - -Stream checkpoints in real-time via Server-Sent Events (SSE) as an expert job executes. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdCheckpointsStream` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/expert-jobs-continue.md b/docs/api-reference/studio-v1/expert-jobs-continue.md deleted file mode 100644 index af8cd931..00000000 --- a/docs/api-reference/studio-v1/expert-jobs-continue.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: "Expert Jobs Continue API" ---- - -# Expert Jobs Continue - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [POST `/api/studio/v1/expert_jobs/{expertJobId}/continue`](#post-api-studio-v1-expert-jobs-expertjobid-continue) - -## POST `/api/studio/v1/expert_jobs/{expertJobId}/continue` - -**Continue an expert job** - -Continue a paused expert job from its last checkpoint. Used for interactive tool responses, additional queries, or resuming after max steps exceeded. - -**Operation ID:** `postApiStudioV1Expert_jobsByExpertJobIdContinue` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| query | string | No | | -| interactiveToolCallResult | boolean | No | | -| files | union | No | | -| temperature | string | No | | -| maxSteps | string | No | | -| maxRetries | string | No | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | - -#### 400 - -Bad Request. Possible reasons: -- Query or files are required -- No checkpoint found -- Current status is unable to continue -- Provider API key not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job or workspace instance not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/expert-jobs-workspace-instance-to-run.md b/docs/api-reference/studio-v1/expert-jobs-workspace-instance-to-run.md deleted file mode 100644 index 24182bfb..00000000 --- a/docs/api-reference/studio-v1/expert-jobs-workspace-instance-to-run.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Expert Jobs Workspace Instance To Run API" ---- - -# Expert Jobs Workspace Instance To Run - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance_to_run/`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-to-run-) - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance_to_run/` - -**Get workspace instance to run** - -Retrieve workspace instance data needed to run an expert job. Internal API for system use only. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instance_to_run` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceInstanceToRun | object | Yes | | -| type | `"workspaceInstanceToRun"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | object | Yes | | -| envSecrets | object | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid system API key - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job or workspace instance not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/expert-jobs-workspace-instance.md b/docs/api-reference/studio-v1/expert-jobs-workspace-instance.md deleted file mode 100644 index 28be8b86..00000000 --- a/docs/api-reference/studio-v1/expert-jobs-workspace-instance.md +++ /dev/null @@ -1,738 +0,0 @@ ---- -title: "Expert Jobs Workspace Instance API" ---- - -# Expert Jobs Workspace Instance - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-) -- [POST `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/`](#post-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-workspaceitemid-) -- [POST `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}`](#post-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-workspaceitemid-) -- [DELETE `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}`](#delete-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-workspaceitemid-) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}/download`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-workspaceitemid-download) -- [GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/find`](#get-api-studio-v1-expert-jobs-expertjobid-workspace-instance-items-find) - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/` - -**Get workspace instance** - -Retrieve the workspace instance associated with an expert job. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instance` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceInstance | object | Yes | | -| type | `"workspaceInstance"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job or workspace instance not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/` - -**List workspace instance items** - -List all items in the workspace instance. Includes both workspace defaults and expert job specific items. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItems` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `take` (query) - -**Required** - -**Type:** number -**Range:** min: 1, max: 100 -**Default:** `100` - -#### `skip` (query) - -**Required** - -**Type:** number -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItems | unknown[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/` - -**Create a workspace instance item** - -Create a new file or directory in the workspace instance. Parent directory must exist. - -**Operation ID:** `postApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItems` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Invalid path -- Directory not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}` - -**Get a workspace instance item** - -Retrieve detailed information about a specific workspace instance item. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItemsByWorkspaceItemId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}` - -**Update a workspace instance item** - -Update the lifecycle, permission, or path of a workspace instance item. - -**Operation ID:** `postApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItemsByWorkspaceItemId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| lifecycle | `application` \| `expertJob` | No | | -| permission | `readOnly` \| `readWrite` | No | | -| path | string | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- At least one field is required -- Invalid path -- Directory not found -- Path already exists - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}` - -**Delete a workspace instance item** - -Delete a file or directory from the workspace instance. Deleting a directory also deletes all its contents. - -**Operation ID:** `deleteApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItemsByWorkspaceItemId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `type` - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/{workspaceItemId}/download` - -**Download a workspace instance file** - -Download the content of a file from the workspace instance. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItemsByWorkspaceItemIdDownload` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `text/plain` - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Not Found. Possible reasons: -- Workspace item not found -- File not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/{expertJobId}/workspace_instance/items/find` - -**Find workspace instance items by path** - -Find workspace instance items matching the specified path. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobIdWorkspace_instanceItemsFind` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `path` (query) - -**Required** - -**Type:** string -**Length:** min: 1 - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItems | unknown[] | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/expert-jobs.md b/docs/api-reference/studio-v1/expert-jobs.md deleted file mode 100644 index 2c4553e5..00000000 --- a/docs/api-reference/studio-v1/expert-jobs.md +++ /dev/null @@ -1,439 +0,0 @@ ---- -title: "Expert Jobs API" ---- - -# Expert Jobs - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/expert_jobs/{expertJobId}`](#get-api-studio-v1-expert-jobs-expertjobid-) -- [POST `/api/studio/v1/expert_jobs/{expertJobId}`](#post-api-studio-v1-expert-jobs-expertjobid-) -- [GET `/api/studio/v1/expert_jobs/`](#get-api-studio-v1-expert-jobs-) -- [POST `/api/studio/v1/expert_jobs/`](#post-api-studio-v1-expert-jobs-) - -## GET `/api/studio/v1/expert_jobs/{expertJobId}` - -**Get an expert job** - -Retrieve detailed information about a specific expert job including its current status. - -**Operation ID:** `getApiStudioV1Expert_jobsByExpertJobId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/expert_jobs/{expertJobId}` - -**Update an expert job status** - -Update the status of an expert job. Internal API for system use only. - -**Operation ID:** `postApiStudioV1Expert_jobsByExpertJobId` - -### Parameters - -#### `expertJobId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid system API key - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert job not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/expert_jobs/` - -**List expert jobs** - -List all expert jobs in the application. Supports filtering by expert key, sorting, and pagination. - -**Operation ID:** `getApiStudioV1Expert_jobs` - -### Parameters - -#### `applicationId` (query) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `filter` (query) - -**Type:** string -**Length:** min: 1, max: 256 - -#### `sort` (query) - -**Type:** enum -**Values:** `createdAt`, `updatedAt` - -#### `order` (query) - -**Type:** enum -**Values:** `asc`, `desc` - -#### `take` (query) - -**Required** - -**Type:** number -**Range:** min: 1, max: 100 -**Default:** `100` - -#### `skip` (query) - -**Required** - -**Type:** number -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expertJobs | object[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/expert_jobs/` - -**Start an expert job** - -Start a new expert job execution. Requires an expert key, and optionally a query and/or files. The job runs asynchronously and can be monitored via checkpoints. - -**Operation ID:** `postApiStudioV1Expert_jobs` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | union | No | | -| temperature | string | No | | -| maxSteps | string | No | | -| maxRetries | string | No | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expertJob | object | Yes | | -| type | `"expertJob"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| status | `queued` \| `processing` \| `completed` \| `requestInteractiveToolResult` \| `requestDelegateResult` \| `exceededMaxSteps` \| `failed` \| `canceling` \| `canceled` \| `expired` | Yes | | -| runtimeVersion | `"v1.0"` | Yes | | -| expertKey | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | Yes | Unique identifier for an expert version (name@version or name@tag) | -| query | string | No | | -| files | string[] | Yes | | -| interactiveToolCallResult | boolean | No | | -| expert | union | Yes | | -| model | `claude-opus-4-5` \| `claude-opus-4-1` \| `claude-opus-4-20250514` \| `claude-sonnet-4-5` \| `claude-sonnet-4-20250514` \| `claude-3-7-sonnet-20250219` \| `claude-haiku-4-5` \| `claude-3-5-haiku-latest` \| `gemini-3-pro-preview` \| `gemini-2.5-pro` \| `gemini-2.5-flash` \| `gemini-2.5-flash-lite` \| `gpt-5` \| `gpt-5-mini` \| `gpt-5-nano` \| `gpt-5-chat-latest` \| `o4-mini` \| `o3` \| `o3-mini` \| `gpt-4.1` \| `deepseek-chat` \| `deepseek-reasoner` | Yes | | -| temperature | number | Yes | | -| maxSteps | number | Yes | | -| maxRetries | number | Yes | | -| currentStep | number | Yes | | -| totalSteps | number | Yes | | -| totalDuration | number | Yes | | -| usage | object | Yes | | -| inputTokens | number | Yes | | -| outputTokens | number | Yes | | -| reasoningTokens | number | Yes | | -| totalTokens | number | Yes | | -| cachedInputTokens | number | Yes | | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | - -#### 400 - -Bad Request. Possible reasons: -- Query or files are required -- Provider API key not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Expert not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/experts.md b/docs/api-reference/studio-v1/experts.md deleted file mode 100644 index d632e247..00000000 --- a/docs/api-reference/studio-v1/experts.md +++ /dev/null @@ -1,438 +0,0 @@ ---- -title: "Experts API" ---- - -# Experts - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/experts/`](#get-api-studio-v1-experts-) -- [POST `/api/studio/v1/experts/`](#post-api-studio-v1-experts-) -- [GET `/api/studio/v1/experts/{expertKey}`](#get-api-studio-v1-experts-expertkey-) -- [POST `/api/studio/v1/experts/{expertKey}`](#post-api-studio-v1-experts-expertkey-) -- [DELETE `/api/studio/v1/experts/{expertKey}`](#delete-api-studio-v1-experts-expertkey-) - -## GET `/api/studio/v1/experts/` - -**List studio experts** - -List all studio experts in the application. Supports filtering by name prefix, sorting, and pagination. - -**Operation ID:** `getApiStudioV1Experts` - -### Parameters - -#### `applicationId` (query) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -#### `filter` (query) - -**Type:** string -**Length:** min: 1, max: 256 - -#### `sort` (query) - -**Type:** enum -**Values:** `name`, `version`, `createdAt`, `updatedAt` - -#### `order` (query) - -**Type:** enum -**Values:** `asc`, `desc` - -#### `take` (query) - -**Required** - -**Range:** min: 1, max: 100 -**Default:** `100` - -#### `skip` (query) - -**Required** - -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| experts | object[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/experts/` - -**Create a studio expert** - -Create a new studio expert in the application. Studio experts are development versions that can be tested before publishing to the Registry. - -**Operation ID:** `postApiStudioV1Experts` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| name | string (pattern: `^(@[a-z0-9][a-z0-9_-]*\/)?[a-z...`) | Yes | Expert name. Scoped names (@org/name) are required for team organizations | -| minRuntimeVersion | `"v1.0"` | Yes | | -| description | string | Yes | Brief description of what the expert does | -| instruction | string | Yes | System prompt that defines the expert's behavior | -| skills | object | Yes | MCP skills available to this expert | -| delegates | RegExp[] | Yes | Other published experts this expert can delegate tasks to | -| forkFrom | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | No | Key of the registry expert this was forked from | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Expert with this name already exists -- Delegate expert not found -- forkFrom expert not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/experts/{expertKey}` - -**Get a studio expert** - -Retrieve detailed information about a specific studio expert. - -**Operation ID:** `getApiStudioV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | union | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Studio expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/experts/{expertKey}` - -**Update a studio expert** - -Update an existing studio expert. All fields are optional; only provided fields will be updated. - -**Operation ID:** `postApiStudioV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| minRuntimeVersion | `"v1.0"` | No | | -| description | string | No | Brief description of what the expert does | -| instruction | string | No | System prompt that defines the expert's behavior | -| skills | object | No | MCP skills available to this expert | -| delegates | RegExp[] | No | Other published experts this expert can delegate tasks to | -| forkFrom | string (pattern: `^((?:@[a-z0-9][a-z0-9_.-]*\/)?...`) | No | Key of the registry expert this was forked from | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| expert | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Delegate expert not found -- forkFrom expert not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Studio expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/studio/v1/experts/{expertKey}` - -**Delete a studio expert** - -Delete a studio expert from the application. - -**Operation ID:** `deleteApiStudioV1ExpertsByExpertKey` - -### Parameters - -#### `expertKey` (path) - -**Required** - -**Description:** Unique identifier for an expert version (name@version or name@tag) -**Type:** string (pattern) -**Pattern:** `^((?:@[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.-]*)(?:@((?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\w.-]+)?(?:\+[\w.-]+)?)|@([a-z0-9][a-z0-9_.-]*))?$` -**Length:** min: 1, max: 511 -**Examples:** `my-expert@1.0.0`, `@perstack/base@latest` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `type` - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Studio expert not found with the specified key. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/api-reference/studio-v1/workspace.md b/docs/api-reference/studio-v1/workspace.md deleted file mode 100644 index 09c64da6..00000000 --- a/docs/api-reference/studio-v1/workspace.md +++ /dev/null @@ -1,1175 +0,0 @@ ---- -title: "Workspace API" ---- - -# Workspace - -**Product:** studio -**Version:** v1 - -## Endpoints - -- [GET `/api/studio/v1/workspace/`](#get-api-studio-v1-workspace-) -- [GET `/api/studio/v1/workspace/items/`](#get-api-studio-v1-workspace-items-) -- [POST `/api/studio/v1/workspace/items/`](#post-api-studio-v1-workspace-items-) -- [GET `/api/studio/v1/workspace/items/{workspaceItemId}`](#get-api-studio-v1-workspace-items-workspaceitemid-) -- [POST `/api/studio/v1/workspace/items/{workspaceItemId}`](#post-api-studio-v1-workspace-items-workspaceitemid-) -- [DELETE `/api/studio/v1/workspace/items/{workspaceItemId}`](#delete-api-studio-v1-workspace-items-workspaceitemid-) -- [GET `/api/studio/v1/workspace/items/{workspaceItemId}/download`](#get-api-studio-v1-workspace-items-workspaceitemid-download) -- [GET `/api/studio/v1/workspace/items/find`](#get-api-studio-v1-workspace-items-find) -- [POST `/api/studio/v1/workspace/secrets/`](#post-api-studio-v1-workspace-secrets-) -- [DELETE `/api/studio/v1/workspace/secrets/{envSecretName}`](#delete-api-studio-v1-workspace-secrets-envsecretname-) -- [POST `/api/studio/v1/workspace/variables/`](#post-api-studio-v1-workspace-variables-) -- [POST `/api/studio/v1/workspace/variables/{envVariableName}`](#post-api-studio-v1-workspace-variables-envvariablename-) -- [DELETE `/api/studio/v1/workspace/variables/{envVariableName}`](#delete-api-studio-v1-workspace-variables-envvariablename-) - -## GET `/api/studio/v1/workspace/` - -**Get workspace** - -Retrieve the workspace associated with the application. A workspace is the default file storage area. - -**Operation ID:** `getApiStudioV1Workspace` - -### Parameters - -#### `expertJobId` (query) - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/workspace/items/` - -**List workspace items** - -List all items in the workspace with pagination support. - -**Operation ID:** `getApiStudioV1WorkspaceItems` - -### Parameters - -#### `applicationId` (query) - -**Type:** string - -#### `take` (query) - -**Required** - -**Type:** number -**Range:** min: 1, max: 100 -**Default:** `100` - -#### `skip` (query) - -**Required** - -**Type:** number -**Range:** min: 0 -**Default:** `0` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItems | unknown[] | Yes | | -| meta | object | Yes | | -| total | number | Yes | | -| take | number | Yes | | -| skip | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/workspace/items/` - -**Create a workspace item** - -Create a new file or directory in the workspace. Parent directory must exist. - -**Operation ID:** `postApiStudioV1WorkspaceItems` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- Invalid path -- Directory not found -- Path already exists - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/workspace/items/{workspaceItemId}` - -**Get a workspace item** - -Retrieve detailed information about a specific workspace item. - -**Operation ID:** `getApiStudioV1WorkspaceItemsByWorkspaceItemId` - -### Parameters - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/workspace/items/{workspaceItemId}` - -**Update a workspace item** - -Update the lifecycle, permission, or path of a workspace item. - -**Operation ID:** `postApiStudioV1WorkspaceItemsByWorkspaceItemId` - -### Parameters - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| lifecycle | `application` \| `expertJob` | No | | -| permission | `readOnly` \| `readWrite` | No | | -| path | string | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItem | union | Yes | | - -#### 400 - -Bad Request. Possible reasons: -- At least one field is required -- Invalid path -- Directory not found -- Path already exists - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/studio/v1/workspace/items/{workspaceItemId}` - -**Delete a workspace item** - -Delete a file or directory from the workspace. Deleting a directory also deletes all its contents. - -**Operation ID:** `deleteApiStudioV1WorkspaceItemsByWorkspaceItemId` - -### Parameters - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `type` - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Workspace item not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/workspace/items/{workspaceItemId}/download` - -**Download a workspace file** - -Download the content of a file from the workspace. - -**Operation ID:** `getApiStudioV1WorkspaceItemsByWorkspaceItemIdDownload` - -### Parameters - -#### `workspaceItemId` (path) - -**Required** - -**Description:** A unique identifier for a resource -**Type:** string (pattern) -**Pattern:** `^[a-z0-9]+$` -**Length:** min: 24, max: 24 -**Examples:** `test12345678901234567890` - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `text/plain` - -#### 400 - -Bad Request. Can only download files, not directories. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Not Found. Possible reasons: -- Workspace item not found -- File not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## GET `/api/studio/v1/workspace/items/find` - -**Find workspace items by path** - -Find workspace items matching the specified path. - -**Operation ID:** `getApiStudioV1WorkspaceItemsFind` - -### Parameters - -#### `applicationId` (query) - -**Type:** string - -#### `path` (query) - -**Required** - -**Type:** string -**Length:** min: 1 - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspaceItems | unknown[] | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Query parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/workspace/secrets/` - -**Create a workspace secret** - -Create an encrypted environment secret in the workspace. Secrets are available to expert jobs as environment variables. - -**Operation ID:** `postApiStudioV1WorkspaceSecrets` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| name | string (pattern: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) | Yes | | -| value | string | Yes | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 400 - -Bad Request. Env name already exists in workspace. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/studio/v1/workspace/secrets/{envSecretName}` - -**Delete a workspace secret** - -Delete an encrypted environment secret from the workspace. - -**Operation ID:** `deleteApiStudioV1WorkspaceSecretsByEnvSecretName` - -### Parameters - -#### `envSecretName` (path) - -**Required** - -**Type:** string (pattern) -**Pattern:** `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` -**Length:** min: 1, max: 256 - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Env secret not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/workspace/variables/` - -**Create a workspace variable** - -Create an environment variable in the workspace. Variables are available to expert jobs as environment variables. - -**Operation ID:** `postApiStudioV1WorkspaceVariables` - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| name | string (pattern: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) | Yes | | -| value | string | Yes | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 400 - -Bad Request. Env name already exists in workspace. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `400` | Yes | | -| error | `"Bad Request"` | Yes | | -| reason | string | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 422 - -Request body schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## POST `/api/studio/v1/workspace/variables/{envVariableName}` - -**Update a workspace variable** - -Update the name or value of an environment variable in the workspace. - -**Operation ID:** `postApiStudioV1WorkspaceVariablesByEnvVariableName` - -### Parameters - -#### `envVariableName` (path) - -**Required** - -**Type:** string (pattern) -**Pattern:** `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` -**Length:** min: 1, max: 256 - -### Request Body - -**Required** - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| name | string (pattern: `^[a-zA-Z0-9][a-zA-Z0-9_-]*$`) | No | | -| value | string | No | | - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Env variable not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Request body or path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- - -## DELETE `/api/studio/v1/workspace/variables/{envVariableName}` - -**Delete a workspace variable** - -Delete an environment variable from the workspace. - -**Operation ID:** `deleteApiStudioV1WorkspaceVariablesByEnvVariableName` - -### Parameters - -#### `envVariableName` (path) - -**Required** - -**Type:** string (pattern) -**Pattern:** `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` -**Length:** min: 1, max: 256 - -### Responses - -#### 200 - -Response for status 200 - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| data | object | Yes | | -| workspace | object | Yes | | -| type | `"workspace"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| applicationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| application | object | Yes | | -| type | `"application"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organizationId | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| organization | object | Yes | | -| type | `"organization"` | Yes | | -| id | string (pattern: `^[a-z0-9]+$`) | Yes | A unique identifier for a resource | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string (pattern: `^[a-z0-9][a-z0-9_.-]*$`) | No | | -| nameChangedAt | string | No | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| organizationType | `personal` \| `personalPlus` \| `team` \| `serviceAdmin` | Yes | | -| maxApplications | number | Yes | | -| maxApiKeys | number | Yes | | -| maxStudioExperts | number | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| name | string | Yes | | -| status | `active` \| `inactive` \| `deleted` | Yes | | -| createdAt | string | Yes | | -| updatedAt | string | Yes | | -| items | unknown[] | Yes | | -| countItems | number | Yes | | -| envVariables | string[] | Yes | | -| envSecrets | string[] | Yes | | -| countWorkspaceInstances | number | Yes | | - -#### 401 - -Authentication failed. Possible reasons: -- Authorization header is not provided -- Invalid API key -- Application not found - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `401` | Yes | | -| error | `"Unauthorized"` | Yes | | -| reason | `"Failed to authenticate"` | Yes | | - -#### 404 - -Env variable not found. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `404` | Yes | | -| error | `"Not Found"` | Yes | | -| reason | string | Yes | | - -#### 422 - -Path parameter schema validation failed. - -**Content-Type:** `application/json` - -| Property | Type | Required | Description | -|----------|------|----------|-------------| -| code | `422` | Yes | | -| error | `"Validation Failed"` | Yes | | -| reason | unknown | Yes | | - ---- diff --git a/docs/making-experts/publishing.md b/docs/making-experts/publishing.md index 0a1a998a..84ee737d 100644 --- a/docs/making-experts/publishing.md +++ b/docs/making-experts/publishing.md @@ -202,4 +202,4 @@ The `--force` flag is required when using CLI mode. ## What's next - [Registry](../understanding-perstack/registry.md) — how the Registry works -- [Registry API](../references/registry-api.md) — programmatic access +- [Registry API](https://stg.perstack.ai/api/v1/spec) — programmatic access diff --git a/docs/understanding-perstack/concept.md b/docs/understanding-perstack/concept.md index 1d37f7f1..74888dbf 100644 --- a/docs/understanding-perstack/concept.md +++ b/docs/understanding-perstack/concept.md @@ -47,7 +47,7 @@ Expert Stack focuses on **how to define, share, and reuse** agent capabilities. Most agent frameworks optimize for building applications, not for reusing what's built. Expert Stack was designed from the ground up with reusability as a first-class concern. -Expert definitions are plain text with no framework dependency. Any agent framework can consume them through the [Registry API](../references/registry-api.md). The ecosystem is open. +Expert definitions are plain text with no framework dependency. Any agent framework can consume them through the [Registry API](https://stg.perstack.ai/api/v1/spec). The ecosystem is open. ## Key features diff --git a/docs/understanding-perstack/registry.md b/docs/understanding-perstack/registry.md index b0c5c955..dd70dcb0 100644 --- a/docs/understanding-perstack/registry.md +++ b/docs/understanding-perstack/registry.md @@ -102,4 +102,4 @@ Registry security is one layer of defense. See [Sandbox Integration](./sandbox-i ## API Reference -For programmatic access, see [Registry API Reference](../references/registry-api.md). +For programmatic access, see [API Reference](https://stg.perstack.ai/api/v1/spec). diff --git a/scripts/generate-api-docs.ts b/scripts/generate-api-docs.ts deleted file mode 100644 index f19d8eae..00000000 --- a/scripts/generate-api-docs.ts +++ /dev/null @@ -1,531 +0,0 @@ -/** - * Generates API documentation from OpenAPI specification. - * - * Output structure: - * docs/api-reference/[product]-[version]/[resource].md - * e.g., docs/api-reference/studio-v1/experts.md - * - * Usage: - * npx tsx scripts/generate-api-docs.ts - * npx tsx scripts/generate-api-docs.ts --output ./docs/api-reference - * npx tsx scripts/generate-api-docs.ts --url http://localhost:3000/openapi.json - * npx tsx scripts/generate-api-docs.ts --save-spec - * npx tsx scripts/generate-api-docs.ts --save-spec packages/api-client/openapi.json - */ - -import * as fs from "node:fs/promises" -import * as path from "node:path" - -interface OpenAPISpec { - openapi: string - info: { - title: string - description: string - version: string - } - paths: Record -} - -interface PathItem { - get?: Operation - post?: Operation - put?: Operation - patch?: Operation - delete?: Operation -} - -interface Operation { - tags?: string[] - summary?: string - description?: string - operationId?: string - parameters?: Parameter[] - requestBody?: RequestBody - responses?: Record -} - -interface Parameter { - name: string - in: "path" | "query" | "header" | "cookie" - required?: boolean - description?: string - schema?: Schema -} - -interface RequestBody { - description?: string - required?: boolean - content?: Record -} - -interface Response { - description?: string - content?: Record -} - -interface MediaType { - schema?: Schema -} - -interface Schema { - type?: string - const?: unknown - enum?: unknown[] - description?: string - properties?: Record - items?: Schema - required?: string[] - anyOf?: Schema[] - allOf?: Schema[] - oneOf?: Schema[] - patternProperties?: Record - minLength?: number - maxLength?: number - minItems?: number - maxItems?: number - minimum?: number - maximum?: number - format?: string - default?: unknown - examples?: unknown[] - source?: string - flags?: string - discriminantKey?: string -} - -interface ParsedPath { - product: string - version: string - resource: string - subResource?: string - fullPath: string -} - -async function fetchOpenAPISpec(url: string): Promise { - if (url.startsWith("file://") || url.startsWith("/") || url.match(/^[A-Za-z]:\\/)) { - const filePath = url.startsWith("file://") ? url.slice(7) : url - const content = await fs.readFile(filePath, "utf-8") - return JSON.parse(content) as OpenAPISpec - } - - const response = await fetch(url) - if (!response.ok) { - throw new Error(`Failed to fetch OpenAPI spec: ${response.statusText}`) - } - return response.json() as Promise -} - -function parsePath(apiPath: string): ParsedPath | null { - const match = apiPath.match(/^\/api\/([^/]+)\/([^/]+)\/([^/]+)/) - if (!match) return null - - const [, product, version, resource] = match - const remaining = apiPath.slice(match[0].length) - const subResourceMatch = remaining.match(/^\/\{[^}]+\}\/([^/]+)/) - const subResource = subResourceMatch ? subResourceMatch[1] : undefined - - return { - product, - version, - resource: resource.replace(/_/g, "-"), - subResource: subResource?.replace(/_/g, "-"), - fullPath: apiPath, - } -} - -function getResourceKey(parsed: ParsedPath): string { - if (parsed.subResource) { - return `${parsed.product}-${parsed.version}/${parsed.resource}-${parsed.subResource}` - } - return `${parsed.product}-${parsed.version}/${parsed.resource}` -} - -function formatSchema(schema: Schema, indent = 0): string { - const pad = " ".repeat(indent) - const lines: string[] = [] - - if (schema.description) { - lines.push(`${pad}**Description:** ${schema.description}`) - } - - if (schema.type === "RegExp" && schema.source) { - lines.push(`${pad}**Type:** string (pattern)`) - lines.push(`${pad}**Pattern:** \`${schema.source}\``) - } else if (schema.const !== undefined) { - lines.push(`${pad}**Type:** constant`) - lines.push(`${pad}**Value:** \`${JSON.stringify(schema.const)}\``) - } else if (schema.enum) { - lines.push(`${pad}**Type:** enum`) - lines.push(`${pad}**Values:** ${schema.enum.map((v) => `\`${v}\``).join(", ")}`) - } else if (schema.type) { - lines.push(`${pad}**Type:** ${schema.type}`) - } - - if (schema.format) { - lines.push(`${pad}**Format:** ${schema.format}`) - } - - if (schema.minLength !== undefined || schema.maxLength !== undefined) { - const constraints: string[] = [] - if (schema.minLength !== undefined) constraints.push(`min: ${schema.minLength}`) - if (schema.maxLength !== undefined) constraints.push(`max: ${schema.maxLength}`) - lines.push(`${pad}**Length:** ${constraints.join(", ")}`) - } - - if (schema.minItems !== undefined || schema.maxItems !== undefined) { - const constraints: string[] = [] - if (schema.minItems !== undefined) constraints.push(`min: ${schema.minItems}`) - if (schema.maxItems !== undefined) constraints.push(`max: ${schema.maxItems}`) - lines.push(`${pad}**Items:** ${constraints.join(", ")}`) - } - - if (schema.minimum !== undefined || schema.maximum !== undefined) { - const constraints: string[] = [] - if (schema.minimum !== undefined) constraints.push(`min: ${schema.minimum}`) - if (schema.maximum !== undefined) constraints.push(`max: ${schema.maximum}`) - lines.push(`${pad}**Range:** ${constraints.join(", ")}`) - } - - if (schema.default !== undefined) { - lines.push(`${pad}**Default:** \`${JSON.stringify(schema.default)}\``) - } - - if (schema.examples && schema.examples.length > 0) { - lines.push(`${pad}**Examples:** ${schema.examples.map((e) => `\`${e}\``).join(", ")}`) - } - - return lines.join("\n") -} - -function formatSchemaAsTable(schema: Schema, depth = 0): string { - if (!schema.properties) return "" - - const lines: string[] = [] - const required = schema.required ?? [] - - if (depth === 0) { - lines.push("| Property | Type | Required | Description |") - lines.push("|----------|------|----------|-------------|") - } - - for (const [name, prop] of Object.entries(schema.properties)) { - const isRequired = required.includes(name) - let typeStr = prop.type ?? "unknown" - - if (prop.type === "RegExp" && prop.source) { - typeStr = `string (pattern: \`${prop.source.slice(0, 30)}${prop.source.length > 30 ? "..." : ""}\`)` - } else if (prop.const !== undefined) { - typeStr = `\`${JSON.stringify(prop.const)}\`` - } else if (prop.enum) { - typeStr = prop.enum.map((v) => `\`${v}\``).join(" \\| ") - } else if (prop.type === "array" && prop.items) { - const itemType = prop.items.type ?? "unknown" - typeStr = `${itemType}[]` - } else if (prop.anyOf) { - typeStr = "union" - } - - const desc = prop.description ?? "" - const prefix = " ".repeat(depth) - lines.push(`| ${prefix}${name} | ${typeStr} | ${isRequired ? "Yes" : "No"} | ${desc} |`) - - if (prop.properties) { - lines.push(formatSchemaAsTable(prop, depth + 1)) - } - } - - return lines.join("\n") -} - -function formatParameter(param: Parameter): string { - const lines: string[] = [] - lines.push(`#### \`${param.name}\` (${param.in})`) - lines.push("") - - if (param.required) { - lines.push("**Required**") - lines.push("") - } - - if (param.description) { - lines.push(param.description) - lines.push("") - } - - if (param.schema) { - lines.push(formatSchema(param.schema)) - lines.push("") - } - - return lines.join("\n") -} - -function formatRequestBody(body: RequestBody): string { - const lines: string[] = [] - lines.push("### Request Body") - lines.push("") - - if (body.description) { - lines.push(body.description) - lines.push("") - } - - if (body.required) { - lines.push("**Required**") - lines.push("") - } - - if (body.content) { - for (const [contentType, media] of Object.entries(body.content)) { - if (contentType !== "application/json") continue - lines.push(`**Content-Type:** \`${contentType}\``) - lines.push("") - - if (media.schema) { - const table = formatSchemaAsTable(media.schema) - if (table) { - lines.push(table) - lines.push("") - } - } - } - } - - return lines.join("\n") -} - -function formatResponse(statusCode: string, response: Response): string { - const lines: string[] = [] - lines.push(`#### ${statusCode}`) - lines.push("") - - if (response.description) { - lines.push(response.description) - lines.push("") - } - - if (response.content) { - for (const [contentType, media] of Object.entries(response.content)) { - lines.push(`**Content-Type:** \`${contentType}\``) - lines.push("") - - if (media.schema) { - const table = formatSchemaAsTable(media.schema) - if (table) { - lines.push(table) - lines.push("") - } - } - } - } - - return lines.join("\n") -} - -function formatOperation(method: string, apiPath: string, operation: Operation): string { - const lines: string[] = [] - - lines.push(`## ${method.toUpperCase()} \`${apiPath}\``) - lines.push("") - - if (operation.summary) { - lines.push(`**${operation.summary}**`) - lines.push("") - } - - if (operation.description) { - lines.push(operation.description) - lines.push("") - } - - if (operation.operationId) { - lines.push(`**Operation ID:** \`${operation.operationId}\``) - lines.push("") - } - - if (operation.parameters && operation.parameters.length > 0) { - lines.push("### Parameters") - lines.push("") - for (const param of operation.parameters) { - lines.push(formatParameter(param)) - } - } - - if (operation.requestBody) { - lines.push(formatRequestBody(operation.requestBody)) - } - - if (operation.responses) { - lines.push("### Responses") - lines.push("") - for (const [statusCode, response] of Object.entries(operation.responses)) { - lines.push(formatResponse(statusCode, response)) - } - } - - lines.push("---") - lines.push("") - - return lines.join("\n") -} - -type EndpointInfo = { method: string; path: string; operation: Operation } - -function groupEndpointsByResource( - spec: OpenAPISpec, -): Map { - const groups = new Map() - - for (const [apiPath, pathItem] of Object.entries(spec.paths)) { - const methods: Array<[string, Operation | undefined]> = [ - ["get", pathItem.get], - ["post", pathItem.post], - ["put", pathItem.put], - ["patch", pathItem.patch], - ["delete", pathItem.delete], - ] - - for (const [method, operation] of methods) { - if (!operation) continue - - const parsed = parsePath(apiPath) - if (!parsed) continue - - const key = getResourceKey(parsed) - if (!groups.has(key)) { - groups.set(key, { parsed, endpoints: [] }) - } - groups.get(key)?.endpoints.push({ method, path: apiPath, operation }) - } - } - - return groups -} - -function generateResourceMarkdown(parsed: ParsedPath, endpoints: EndpointInfo[]): string { - const lines: string[] = [] - - const title = parsed.subResource - ? `${capitalize(parsed.resource)} ${capitalize(parsed.subResource)}` - : capitalize(parsed.resource) - - lines.push("---") - lines.push(`title: "${title} API"`) - lines.push("---") - lines.push("") - lines.push(`# ${title}`) - lines.push("") - lines.push(`**Product:** ${parsed.product}`) - lines.push(`**Version:** ${parsed.version}`) - lines.push("") - - lines.push("## Endpoints") - lines.push("") - for (const { method, path: apiPath } of endpoints) { - const anchor = `${method}-${apiPath}`.toLowerCase().replace(/[^a-z0-9]+/g, "-") - lines.push(`- [${method.toUpperCase()} \`${apiPath}\`](#${anchor})`) - } - lines.push("") - - for (const { method, path: apiPath, operation } of endpoints) { - lines.push(formatOperation(method, apiPath, operation)) - } - - return lines.join("\n") -} - -function capitalize(str: string): string { - return str - .split("-") - .map((word) => word.charAt(0).toUpperCase() + word.slice(1)) - .join(" ") -} - -function printStats(spec: OpenAPISpec): void { - const groups = groupEndpointsByResource(spec) - let totalEndpoints = 0 - - console.log("\n=== OpenAPI Spec Statistics ===\n") - console.log(`Title: ${spec.info.title}`) - console.log(`Version: ${spec.info.version}`) - console.log(`OpenAPI: ${spec.openapi}`) - console.log("") - console.log("Resources:") - console.log("----------") - - for (const [key, { endpoints }] of groups) { - console.log(` ${key}: ${endpoints.length} endpoints`) - totalEndpoints += endpoints.length - - for (const { method, path: apiPath } of endpoints) { - console.log(` ${method.toUpperCase().padEnd(7)} ${apiPath}`) - } - } - - console.log("") - console.log(`Total: ${totalEndpoints} endpoints across ${groups.size} resources`) - console.log("") -} - -async function writeDocumentation(spec: OpenAPISpec, outputDir: string): Promise { - const groups = groupEndpointsByResource(spec) - - await fs.mkdir(outputDir, { recursive: true }) - - const writtenFiles: string[] = [] - - for (const [key, { parsed, endpoints }] of groups) { - const filePath = path.join(outputDir, `${key}.md`) - const dir = path.dirname(filePath) - - await fs.mkdir(dir, { recursive: true }) - - const content = generateResourceMarkdown(parsed, endpoints) - await fs.writeFile(filePath, content, "utf-8") - writtenFiles.push(filePath) - } - - console.log(`\nWritten ${writtenFiles.length} files:`) - for (const file of writtenFiles) { - console.log(` ${file}`) - } -} - -async function main(): Promise { - const args = process.argv.slice(2) - - let url = "http://localhost:3000/openapi.json" - let outputDir: string | undefined - let statsOnly = false - - for (let i = 0; i < args.length; i++) { - if (args[i] === "--url" && args[i + 1]) { - url = args[i + 1] - i++ - } else if (args[i] === "--output" && args[i + 1]) { - outputDir = args[i + 1] - i++ - } else if (args[i] === "--stats") { - statsOnly = true - } - } - - console.log(`Fetching OpenAPI spec from: ${url}`) - - try { - const spec = await fetchOpenAPISpec(url) - - printStats(spec) - - if (!statsOnly && outputDir) { - await writeDocumentation(spec, outputDir) - } else if (!statsOnly) { - console.log("Use --output to write documentation files") - } - } catch (error) { - console.error("Error:", error instanceof Error ? error.message : error) - process.exit(1) - } -} - -main()