@elevasis/sdk 0.5.12 → 0.5.14

package/reference/deployment/api.mdx

@@ -1,297 +1,297 @@
----
-title: Execution API
-description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
-loadWhen: "Calling the API directly or debugging API responses"
----
-
-The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_API_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
-
-**Authentication header:**
-
-```
-Authorization: Bearer sk_...
-```
-
----
-
-## API Base URL
-
-| Environment | Base URL |
-| ----------- | -------- |
-| Production | `https://api.elevasis.io` |
-| Development | `http://localhost:<port>` |
-
-Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
-
----
-
-## Endpoints
-
-| Method | Path | Purpose |
-| ------ | ---- | ------- |
-| `GET` | `/api/external/resources` | List all resources for your organization |
-| `GET` | `/api/external/resources/:resourceId/definition` | Get resource metadata and schemas |
-| `POST` | `/api/external/execute` | Execute a resource synchronously |
-| `POST` | `/api/external/execute-async` | Execute a resource asynchronously |
-| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution |
-| `GET` | `/api/external/executions/:resourceId` | List execution history for a resource |
-| `GET` | `/api/external/executions/:resourceId/:executionId` | Get full execution detail |
-| `POST` | `/api/external/deploy` | Upload bundle and deploy resources |
-| `GET` | `/api/external/deployments` | List all deployments |
-| `GET` | `/api/external/deployments/:id` | Get a deployment by ID |
-
----
-
-## Execution Endpoints
-
-### POST /api/external/execute
-
-Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "success": true,
-  "data": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-}
-```
-
-### POST /api/external/execute-async
-
-Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": { "clientName": "Jane" }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "running"
-}
-```
-
-### POST /api/external/executions/:resourceId/:executionId/cancel
-
-Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
-
-**Response:**
-
-```json
-{
-  "success": true
-}
-```
-
----
-
-## Resource Endpoints
-
-### GET /api/external/resources
-
-List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
-
-**Response:**
-
-```json
-[
-  {
-    "resourceId": "onboard-client",
-    "resourceType": "workflow",
-    "name": "Onboard Client",
-    "status": "prod"
-  },
-  {
-    "resourceId": "email-assistant",
-    "resourceType": "agent",
-    "name": "Email Assistant",
-    "status": "prod"
-  }
-]
-```
-
-### GET /api/external/resources/:resourceId/definition
-
-Get the full definition for a single resource: metadata, input schema, and output schema.
-
-**Response:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "resourceType": "workflow",
-  "name": "Onboard Client",
-  "description": "Creates a client record and sends a welcome email",
-  "status": "prod",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "clientName": { "type": "string" },
-      "email": { "type": "string", "format": "email" }
-    },
-    "required": ["clientName", "email"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "success": { "type": "boolean" },
-      "clientId": { "type": "string" }
-    }
-  }
-}
-```
-
-Returns `404` if the resource is not found.
-
----
-
-## Execution History Endpoints
-
-### GET /api/external/executions/:resourceId
-
-List execution history for a resource.
-
-**Query parameters:**
-
-| Parameter | Description |
-| --------- | ----------- |
-| `limit` | Maximum number of results (default: 20) |
-| `status` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-
-**Response:**
-
-```json
-[
-  {
-    "executionId": "550e8400-e29b-41d4-a716-446655440000",
-    "resourceId": "onboard-client",
-    "status": "completed",
-    "createdAt": "2026-02-25T14:32:01Z",
-    "durationMs": 1234
-  }
-]
-```
-
-### GET /api/external/executions/:resourceId/:executionId
-
-Get the full detail for a single execution including input, output, logs, and error.
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "resourceId": "onboard-client",
-  "status": "completed",
-  "createdAt": "2026-02-25T14:32:01Z",
-  "durationMs": 1234,
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  },
-  "output": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  },
-  "logs": [
-    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
-    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
-  ],
-  "error": null
-}
-```
-
----
-
-## Deployment Endpoints
-
-### POST /api/external/deploy
-
-Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
-
-**Response:**
-
-```json
-{
-  "deployId": "deploy_abc123",
-  "status": "active",
-  "resources": 4
-}
-```
-
-Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
-
-### GET /api/external/deployments
-
-List all deployments for your organization.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "deploy_abc123",
-    "status": "active",
-    "createdAt": "2026-02-25T14:00:00Z",
-    "resources": 4
-  },
-  {
-    "id": "deploy_abc122",
-    "status": "stopped",
-    "createdAt": "2026-02-24T09:30:00Z",
-    "resources": 3
-  }
-]
-```
-
-### GET /api/external/deployments/:id
-
-Get a single deployment by ID.
-
-**Response shape:** Same as a single item from `GET /deployments`.
-
----
-
-## CLI Execution Commands
-
-The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
-
-| Command | API call | Purpose |
-| ------- | -------- | ------- |
-| `elevasis-sdk resources` | `GET /api/external/resources` | List all resources |
-| `elevasis-sdk describe <resource>` | `GET /api/external/resources/:id/definition` | Show resource definition |
-| `elevasis-sdk exec <resource> --input '...'` | `POST /api/external/execute` | Execute synchronously |
-| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async` | Execute asynchronously |
-| `elevasis-sdk executions <resource>` | `GET /api/external/executions/:id` | List execution history |
-| `elevasis-sdk execution <resource> <id>` | `GET /api/external/executions/:id/:execId` | Get execution detail |
-| `elevasis-sdk deployments` | `GET /api/external/deployments` | List deployments |
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Execution API
+description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
+loadWhen: "Calling the API directly or debugging API responses"
+---
+
+The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_PLATFORM_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
+
+**Authentication header:**
+
+```
+Authorization: Bearer sk_...
+```
+
+---
+
+## API Base URL
+
+| Environment | Base URL                    |
+| ----------- | --------------------------- |
+| Production  | `https://api.elevasis.io`   |
+| Development | `http://localhost:<port>` |
+
+Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
+
+---
+
+## Endpoints
+
+| Method | Path                                                       | Purpose                                  |
+| ------ | ---------------------------------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/external/resources`                                  | List all resources for your organization |
+| `GET`  | `/api/external/resources/:resourceId/definition`           | Get resource metadata and schemas        |
+| `POST` | `/api/external/execute`                                    | Execute a resource synchronously         |
+| `POST` | `/api/external/execute-async`                              | Execute a resource asynchronously        |
+| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution               |
+| `GET`  | `/api/external/executions/:resourceId`                     | List execution history for a resource    |
+| `GET`  | `/api/external/executions/:resourceId/:executionId`        | Get full execution detail                |
+| `POST` | `/api/external/deploy`                                     | Upload bundle and deploy resources       |
+| `GET`  | `/api/external/deployments`                                | List all deployments                     |
+| `GET`  | `/api/external/deployments/:id`                            | Get a deployment by ID                   |
+
+---
+
+## Execution Endpoints
+
+### POST /api/external/execute
+
+Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "success": true,
+  "data": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+}
+```
+
+### POST /api/external/execute-async
+
+Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": { "clientName": "Jane" }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "running"
+}
+```
+
+### POST /api/external/executions/:resourceId/:executionId/cancel
+
+Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
+
+**Response:**
+
+```json
+{
+  "success": true
+}
+```
+
+---
+
+## Resource Endpoints
+
+### GET /api/external/resources
+
+List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
+
+**Response:**
+
+```json
+[
+  {
+    "resourceId": "onboard-client",
+    "resourceType": "workflow",
+    "name": "Onboard Client",
+    "status": "prod"
+  },
+  {
+    "resourceId": "email-assistant",
+    "resourceType": "agent",
+    "name": "Email Assistant",
+    "status": "prod"
+  }
+]
+```
+
+### GET /api/external/resources/:resourceId/definition
+
+Get the full definition for a single resource: metadata, input schema, and output schema.
+
+**Response:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "resourceType": "workflow",
+  "name": "Onboard Client",
+  "description": "Creates a client record and sends a welcome email",
+  "status": "prod",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "clientName": { "type": "string" },
+      "email": { "type": "string", "format": "email" }
+    },
+    "required": ["clientName", "email"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "success": { "type": "boolean" },
+      "clientId": { "type": "string" }
+    }
+  }
+}
+```
+
+Returns `404` if the resource is not found.
+
+---
+
+## Execution History Endpoints
+
+### GET /api/external/executions/:resourceId
+
+List execution history for a resource.
+
+**Query parameters:**
+
+| Parameter | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `limit`   | Maximum number of results (default: 20)                         |
+| `status`  | Filter by status: `running`, `completed`, `failed`, `cancelled` |
+
+**Response:**
+
+```json
+[
+  {
+    "executionId": "550e8400-e29b-41d4-a716-446655440000",
+    "resourceId": "onboard-client",
+    "status": "completed",
+    "createdAt": "2026-02-25T14:32:01Z",
+    "durationMs": 1234
+  }
+]
+```
+
+### GET /api/external/executions/:resourceId/:executionId
+
+Get the full detail for a single execution including input, output, logs, and error.
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "resourceId": "onboard-client",
+  "status": "completed",
+  "createdAt": "2026-02-25T14:32:01Z",
+  "durationMs": 1234,
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  },
+  "output": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  },
+  "logs": [
+    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
+    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
+  ],
+  "error": null
+}
+```
+
+---
+
+## Deployment Endpoints
+
+### POST /api/external/deploy
+
+Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
+
+**Response:**
+
+```json
+{
+  "deployId": "deploy_abc123",
+  "status": "active",
+  "resources": 4
+}
+```
+
+Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
+
+### GET /api/external/deployments
+
+List all deployments for your organization.
+
+**Response:**
+
+```json
+[
+  {
+    "id": "deploy_abc123",
+    "status": "active",
+    "createdAt": "2026-02-25T14:00:00Z",
+    "resources": 4
+  },
+  {
+    "id": "deploy_abc122",
+    "status": "stopped",
+    "createdAt": "2026-02-24T09:30:00Z",
+    "resources": 3
+  }
+]
+```
+
+### GET /api/external/deployments/:id
+
+Get a single deployment by ID.
+
+**Response shape:** Same as a single item from `GET /deployments`.
+
+---
+
+## CLI Execution Commands
+
+The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
+
+| Command                                                | API call                                     | Purpose                  |
+| ------------------------------------------------------ | -------------------------------------------- | ------------------------ |
+| `elevasis-sdk resources`                               | `GET /api/external/resources`                | List all resources       |
+| `elevasis-sdk describe <resource>`                   | `GET /api/external/resources/:id/definition` | Show resource definition |
+| `elevasis-sdk exec <resource> --input '...'`         | `POST /api/external/execute`                 | Execute synchronously    |
+| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async`           | Execute asynchronously   |
+| `elevasis-sdk executions <resource>`                 | `GET /api/external/executions/:id`           | List execution history   |
+| `elevasis-sdk execution <resource> <id>`           | `GET /api/external/executions/:id/:execId`   | Get execution detail     |
+| `elevasis-sdk deployments`                             | `GET /api/external/deployments`              | List deployments         |
+
+---
+
+**Last Updated:** 2026-02-25