## Lifecycle management

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/application-sdk/api/workflow-management

> Complete app lifecycle management including HTTP-triggered execution, status monitoring, and app termination.

<!--vale off-->
The request body maps directly to the app's [Input contract](https://docs.atlan.com/llms/platform/build-apps/inputs-and-outputs/llms.txt) — its exact shape is defined by the fields on your app's `Input` class. The fields below are representative of a connector-type app.</>,
 schema: [
 {
 name: "cron_schedule",
 type: "string",
 required: false,
 description: "Standard cron expression (5 fields) for scheduling recurring app executions, omit for immediate execution",
 example: "optional-cron-expression"
 },
 {
 name: "credentials",
 type: "object",
 required: false,
 description: "Source system credentials. If provided, stored separately as credential_guid and replaced in workflow_args. In development: stored in StateStore. In production: throws error as credential storage is not supported.",
 schema: [
 {
 name: "authType",
 type: "string",
 required: true,
 description: "Source system authentication method",
 enum: ["basic", "oauth", "token"],
 example: "basic"
 },
 {
 name: "host",
 type: "string",
 required: true,
 description: "Source system hostname or IP address",
 example: "localhost"
 },
 {
 name: "port",
 type: "integer",
 required: true,
 description: "Source system port number",
 example: 5432
 },
 {
 name: "username",
 type: "string",
 required: true,
 description: "Source system username for authentication",
 example: "username"
 },
 {
 name: "password",
 type: "string",
 required: true,
 description: "Source system password or authentication token",
 example: "password"
 },
 {
 name: "database",
 type: "string",
 required: true,
 description: "Target database name or schema identifier for connection scope",
 example: "databasename"
 },
 {
 name: "extra",
 type: "object",
 required: false,
 description: "Extended authentication parameters including SSL certificates, API keys, OAuth tokens, private keys, and source-system-specific connection options, automatically parsed from JSON string or object format",
 example: {
 "ssl_cert": "-----BEGIN CERTIFICATE-----...",
 "api_key": "sk-1234567890abcdef",
 "oauth_token": "bearer_token_123",
 "ssl_mode": "require"
 }
 }
 ]
 },
 {
 name: "connection",
 type: "object",
 required: false,
 description: "Connection reference for the app execution context. Shape is app-defined.",
 schema: [
 {
 name: "name",
 type: "string",
 required: true,
 description: "Connection identifier",
 example: "production"
 }
 ]
 },
 {
 name: "metadata",
 type: "object",
 required: false,
 description: "Metadata filtering and discovery configuration. Fields vary by app type.",
 example: {"databases": ["MY_DB"]}
 }
 ]
 },

 response: {
 status: 200,
 description: "App started successfully",
 schema: [
 {
 name: "success",
 type: "boolean",
 required: true,
 description: "Whether the operation was successful",
 example: true
 },
 {
 name: "message",
 type: "string",
 required: true,
 description: "Status message",
 example: "App started successfully"
 },
 {
 name: "data",
 type: "object",
 required: true,
 description: "Object containing app execution details",
 schema: [
 {
 name: "workflow_id",
 type: "string",
 required: true,
 description: "Unique identifier for the app",
 example: "4b805f36-48c5-4dd3-942f-650e06f75bbc"
 },
 {
 name: "run_id",
 type: "string",
 required: true,
 description: "Unique identifier for the app run",
 example: "efe16ffe-24b2-4391-a7ec-7000c32c5893"
 }
 ]
 }
 ]
 },

 examples: {
 request: {
 curl: {
 code: `curl -X POST "http://localhost:8000/workflows/v1/start" \\
 -H "Content-Type: application/json" \\
 -d '{
 "credentials": {
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 },
 "connection": {
 "name": "production"
 },
 "metadata": {
 "databases": ["MY_DB"]
 }
 }'`
 },
 python: {
 code: `import requests

response = requests.post(
 "http://localhost:8000/workflows/v1/start",
 json={
 "credentials": {
 "authType": "basic",
 "host": "localhost",
 "port": 5432,
 "username": "username",
 "password": "password",
 "database": "databasename"
 },
 "connection": {
 "name": "production"
 },
 "metadata": {
 "databases": ["MY_DB"]
 }
 }
)
app_data = response.json()`
 }
 },
 response: {
 "200": `{
 "success": true,
 "message": "App started successfully",
 "data": {
 "workflow_id": "4b805f36-48c5-4dd3-942f-650e06f75bbc",
 "run_id": "efe16ffe-24b2-4391-a7ec-7000c32c5893"
 }
}`,
 "500": `{
 "success": false,
 "message": "App failed to start",
 "data": {
 "workflow_id": "",
 "run_id": ""
 }
}`
 }
 }
 },

 {
 id: "stop-workflow",
 method: "POST",
 path: "/workflows/v1/stop/{workflow_id}/{run_id}",
 title: "Stop app",
 description: "Gracefully terminate a running app execution, allowing in-progress operations to complete before stopping. Returns immediately with confirmation while the app shuts down asynchronously.",

 pathParams: [
 {
 name: "workflow_id",
 type: "string",
 required: true,
 description: "Unique identifier for the app",
 example: "4b805f36-48c5-4dd3-942f-650e06f75bbc"
 },
 {
 name: "run_id",
 type: "string",
 required: true,
 description: "Unique identifier for a specific execution instance of the app",
 example: "efe16ffe-24b2-4391-a7ec-7000c32c5893"
 }
 ],

 response: {
 status: 200,
 description: "App stop request accepted",
 schema: [
 {
 name: "success",
 type: "boolean",
 required: true,
 description: "Always true for successful stop request",
 example: true
 }
 ]
 },

 examples: {
 request: {
 curl: {
 code: `curl -X POST "http://localhost:8000/workflows/v1/stop/4b805f36-48c5-4dd3-942f-650e06f75bbc/efe16ffe-24b2-4391-a7ec-7000c32c5893"`
 },
 python: {
 code: `import requests

response = requests.post(
 f"http://localhost:8000/workflows/v1/stop/{workflow_id}/{run_id}")
)
stop_result = response.json()`
 }
 },
 response: {
 "200": `{
 "success": true
}`,
 "400": `{
 "success": false,
 "error": "An internal error has occurred.",
 "details": "Invalid app ID or run ID format"
}`,
 "500": `{
 "success": false,
 "error": "An internal error has occurred.", 
 "details": "Workflow operation failed"
}`
 }
 }
 }
 ]}

 errorCodes={[
 {
 code: 400,
 name: "Bad Request",
 description: "Invalid app ID or run ID format"
 },
 {
 code: 401,
 name: "Unauthorized",
 description: "Missing or invalid authentication token"
 },
 {
 code: 404,
 name: "Not Found",
 description: "App or app run not found"
 },
 {
 code: 500,
 name: "Internal Server Error",
 description: "App operation failed"
 }
 ]}
/>

---