> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cessy.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cessy.ai/_mcp/server.

# Execute one command

POST https://cessy.ai/api/rest/tenant-id/app-id/commands/{commandType}
Content-Type: application/json

Executes a command from the published DomainConfig. Use the generated app OpenAPI document for the concrete request schema, required business fields, and response event types. Declared UUID fields marked by the command model as generated/defaulted are optional for callers and are materialized server-side before DCB boundary resolution. Supply a client-owned Idempotency-Key UUID and reuse it with the identical body after an ambiguous outcome; a committed intent returns its canonical receipt without another append.

Reference: https://docs.cessy.ai/runtime-api-template/commands/execute-command

## Authentication

- `Authorization` header (bearer token, required) — Runtime bearer accepted by the normal app-scoped pipeline: an API key or OAuth/JWT with the 'runtime' scope, or an app-scoped agent service token. Individual operations may require a narrower principal type.

## Request

### Path parameters

- `commandType` (string, required) — Command name from DomainConfig.commands.

### Query parameters

- `workspaceId` (string, optional) — Optional Workspace runtime selector for preview or validation calls. If supplied with X-CES-Workspace-ID, both values must match.

### Headers

- `X-CES-Workspace-ID` (string, optional) — Optional Workspace runtime selector header. If supplied with workspaceId, both values must match.
- `Idempotency-Key` (string, optional) — Client-owned intent UUID. Retry an ambiguous outcome with the same key and identical body; a committed intent returns its canonical receipt without another append.

### Body (application/json)

This endpoint expects a map from string to any.

- `map from string to any`

## Response

### 200

Command executed on an existing scope

- `success` (boolean, required)
- `executionId` (string, required) — Stable command intent and protected execution-log lookup identifier.
- `command` (string, required)
- `eventsEmitted` (integer, required)
- `correlationId` (string, required) — Identifier for related requests and diagnostics.
- `events` (list of CommandResultEventsItems, required)
- `scopeKey` (string, optional)
- `idempotentReplay` (boolean, optional) — True when the response was reconstructed from an already-committed intent.
- `warnings` (list of string, optional)
- `policyErrors` (list of map from string to any, optional)

### 201

Creation command executed

- `success` (boolean, required)
- `executionId` (string, required) — Stable command intent and protected execution-log lookup identifier.
- `command` (string, required)
- `eventsEmitted` (integer, required)
- `correlationId` (string, required) — Identifier for related requests and diagnostics.
- `events` (list of CommandResultEventsItems, required)
- `scopeKey` (string, optional)
- `idempotentReplay` (boolean, optional) — True when the response was reconstructed from an already-committed intent.
- `warnings` (list of string, optional)
- `policyErrors` (list of map from string to any, optional)

## Errors

### 400 Bad Request Error

Invalid JSON or validation error

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 401 Unauthorized Error

Missing or invalid bearer token

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 403 Forbidden Error

Forbidden by app, scope, platform-agent blocklist, or auth rules

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 404 Not Found Error

Unknown command or app

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 409 Conflict Error

Idempotency key was already used with different command input

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 422 Unprocessable Entity Error

Command rule failed

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

### 503 Service Unavailable Error

Command did not commit before the request boundary closed

- `error` (string, required)
- `message` (string, optional) — Operator-safe failure text when the endpoint exposes a typed error.
- `details` (any, optional)
- `code` (string, optional) — Stable machine-readable failure category when available.
- `executionId` (string, optional) — Protected execution-log lookup identifier when execution started.
- `correlationId` (string, optional) — Identifier for related requests and diagnostics when available.
- `effectState` (enum, optional) — Authoritative confirmation that the command effect is absent.
  - Allowed values: `rejected`, `rolled_back`

## Types

### CommandResultEventsItems

- `type` (string, optional)
- `data` (map from string to any, optional)

## Examples

### Example 1

**Request**

```json
{}
```

**Response**

```json
{
  "success": true,
  "executionId": "a3f1c2d4-e5b6-47a8-9c0d-1e2f3a4b5c6d",
  "command": "PlaceOrder",
  "eventsEmitted": 1,
  "correlationId": "c9d8e7f6-a5b4-43c2-d1e0-f9a8b7c6d5e4",
  "events": [
    {
      "type": "OrderPlaced",
      "data": {}
    }
  ],
  "scopeKey": "order:7f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "idempotentReplay": false,
  "warnings": [
    "Inventory reservation will expire in 15 minutes if payment is not completed."
  ],
  "policyErrors": [
    {}
  ]
}
```

**SDK Code**

```python
import requests

url = "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 2

**Request**

```json
{}
```

**Response**

```json
{
  "success": true,
  "executionId": "a3f1c2d4-e5b6-47a8-9c0d-1e2f3a4b5c6d",
  "command": "PlaceOrder",
  "eventsEmitted": 1,
  "correlationId": "c9d8e7f6-a5b4-43c2-d1e0-f9a8b7c6d5e4",
  "events": [
    {
      "type": "OrderPlaced",
      "data": {}
    }
  ],
  "scopeKey": "order:7f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "idempotentReplay": false,
  "warnings": [
    "Inventory reservation will expire in 15 minutes if payment is not completed."
  ],
  "policyErrors": [
    {}
  ]
}
```

**SDK Code**

```python
import requests

url = "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://cessy.ai/api/rest/tenant-id/app-id/commands/commandType")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```